diff options
Diffstat (limited to 'doc/quickstart.html')
| -rw-r--r-- | doc/quickstart.html | 107 |
1 files changed, 107 insertions, 0 deletions
diff --git a/doc/quickstart.html b/doc/quickstart.html new file mode 100644 index 0000000..4b369eb --- /dev/null +++ b/doc/quickstart.html @@ -0,0 +1,107 @@ +<html> + <head> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <meta http-equiv="Content-Language" content="en" /> + <title>tipidee: quickstart guide</title> + <meta name="Description" content="tipidee: quickstart" /> + <meta name="Keywords" content="tipidee quickstart guide" /> + <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> + </head> +<body> + +<p> +<a href="index.html">tipidee</a><br /> +<a href="//skarnet.org/software/">Software</a><br /> +<a href="//skarnet.org/">skarnet.org</a> +</p> + +<h1> A tipidee quickstart guide </h1> + +<h3> Preparation </h3> + +<ol> + <li> Make sure you have <a href="//skarnet.org/software/s6/">s6</a> and + <a href="//skarnet.org/software/s6-networking/">s6-networking</a> installed +alongside tipidee. </li> + <li> Prepare your document root for every virtual domain you aim to serve. +For instance, if your documents are in <tt>/home/www</tt> and you need to +serve the <tt>example.com</tt> and <tt>example.org</tt> domains, create +<tt>/home/www/example.com</tt> and <tt>/home/www/example.org</tt> directories, +they will be the document roots for the <tt>example.com</tt> and <tt>example.org</tt> +virtual sites respectively. </li> + <li> Symlink these canonical directories to all the <em>host:port</em> combinations +you want them to be available on. If you want <tt>example.com</tt> and +<tt>example.org</tt> to be both available on ports 80 and 443, then symlink +<tt>example.com</tt> to <tt>example.com:80</tt> and <tt>example.com:443</tt> +in the <tt>/home/www</tt> directory, and do the same with <tt>example.org</tt>. </li> + <li> Compile a default configuration for tipidee: +<tt>:> /etc/tipidee.conf && tipidee-config</tt>. + <ul> + <li> If you need more than the basic defaults, you can also write a real +<a href="tipidee.conf.html">/etc/tipidee.conf</a> config file before running +<a href="tipidee-config.html">tipidee-config</a>. </li> + </ul> </li> +</ol> + +<h3> Running the server </h3> + +<ul> + <li> You need one long-running process per port you want tipidee to serve. +If you want to serve HTTP on port 80 and HTTPS on port 443, then you'll need +two services. Or four if you want to serve on both IPv4 and IPv6 adresses. </li> + <li> Start these processes in the <tt>/home/www</tt> directory, the base +for all the domains you're serving. </li> + <li> Assuming you want to run the server as user <tt>www</tt>, +the basic command line for an HTTP service is: +<tt>s6-envuidgid www s6-tcpserver -U example.com 80 s6-tcpserver-access -v0 -- tipideed</tt>. + <ul> + <li> <a href="//skarnet.org/software/s6/s6-envuidgid.html">s6-envuidgid</a> +puts the uid and gid of user <tt>www</tt> into the environment, for <tt>s6-tcpserver</tt> +to drop root privileges to. </li> + <li> <a href="//skarnet.org/software/s6-networking/s6-tcpserver.html">s6-tcpserver</a> +binds to the address and port given, drops privileges, and listens; it accepts connections +and spawns a new process for each one. </li> + <li> <a href="//skarnet.org/software/s6-networking/s6-tcpserver-access.html">s6-tcpserver-access</a> +performs DNS requests to fill environment variables that tipidee needs. Its main +purpose is to perform access control, but we're not using it for that here: +chances are your web server is public access and doesn't need to be IP-restricted. </li> + <li> <a href="tipideed.html">tipideed</a> is the tipidee daemon, and will +handle HTTP requests until the client closes the connection or tipideed itself +needs to close it. </li> + </ul> </li> + <li> HTTPS requires a bit of additional setup for TLS. If +your certificate is in <tt>/etc/ssl/acme/example.com/cert.pem</tt> and the +corresponding private key is in <tt>/etc/ssl/acme/private/example.com/key.pem</tt>, +the basic command line for your HTTPS service could look like: +<tt>s6-envuidgid www +env CERTFILE=/etc/ssl/acme/example.com/cert.pem KEYFILE=/etc/ssl/acme/private/example.com/key.pem +s6-tlsserver -U -e example.com 443 tipideed<tt>. + <ul> + <li> <a href="//skarnet.org/software/s6/s6-envuidgid.html">s6-envuidgid</a> +puts the uid and gid of user <tt>www</tt> into the environment. </li> + <li> <tt>env</tt> adds the appropriate CERTFILE and KEYFILE variables to the +environment, so TLS programs down the line can find the certificate and key. + <li> <a href="//skarnet.org/software/s6-networking/s6-tlsserver.html">s6-tlsserver</a> +rewrites itself into a command line that does a lot of different things; the +long-running process is still <a href="//skarnet.org/software/s6-networking/s6-tcpserver.html">s6-tcpserver</a> +listening. For every client connection, it spawns a process that sets up the TLS +transport layer and eventually execs into <tt>tipideed</tt>. </li> + <li> <a href="tipideed.html">tipideed</a> always speaks plaintext HTTP, it has +no knowledge of cryptography itself, but it is made aware that it's running under +TLS, and CGI scripts it runs will have the <tt>HTTPS=on</tt> marker. </li> + </ul> </li> + <li> These command lines will block (remain in the foreground) and log everything +to their stderr. For more server-like functionality, you should integrate them to +your service manager scripts. </li> +</ul> + + <h3> tipidee service templates </h3> + +<p> + The tipidee source distribution comes with an <tt>examples/</tt> subdirectory +containing service files to run tipidee under various service managers. +</p> + +</body> +</html> |