A tipidee quickstart guide
Preparation
- Make sure you have s6 and s6-networking installed alongside tipidee.
- Prepare your document root for every virtual domain you aim to serve. For instance, if your documents are in /home/www/docs and you need to serve the example.com and example.org domains, create /home/www/docs/example.com and /home/www/docs/example.org directories, they will be the document roots for the example.com and example.org virtual sites respectively.
- Symlink these canonical directories to all the host:port combinations you want them to be available on. If you want example.com and example.org to be both available on ports 80 and 443, then symlink example.com to example.com:80 and example.com:443 in the /home/www/docs directory, and do the same with example.org.
- Compile a default configuration for tipidee:
:> /etc/tipidee.conf && tipidee-config.
- If you need more than the basic defaults, you can also write a real /etc/tipidee.conf config file before running tipidee-config.
Running the server
- 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 addresses.
- Start these processes in the /home/www directory, the base for all the domains you're serving.
- Assuming you want to run the server as user www, and your
local IP address is ${ip}, the basic command line for an HTTP service is:
s6-envuidgid www s6-tcpserver -U ${ip} 80 s6-tcpserver-access tipideed.
- s6-envuidgid puts the uid and gid of user www into the environment, for s6-tcpserver to drop root privileges to.
- s6-tcpserver binds to the address and port given, drops privileges, and listens; it accepts connections and spawns a new process for each one.
- s6-tcpserver-access performs DNS requests to fill environment variables that tipidee needs. (The main purpose of this program 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.)
- tipideed is the tipidee daemon, and will handle HTTP requests until the client closes the connection or tipideed itself needs to close it.
- HTTPS requires a bit of additional setup for TLS. If
your certificate is in /etc/ssl/acme/example.com/cert.pem and the
corresponding private key is in /etc/ssl/acme/private/example.com/key.pem,
the basic command line for your HTTPS service could look like:
s6-envuidgid www
env CERTFILE=/etc/ssl/acme/example.com/cert.pem KEYFILE=/etc/ssl/acme/private/example.com/key.pem
s6-tlsserver -U ${ip} 443 tipideed.
- s6-envuidgid puts the uid and gid of user www into the environment.
- env adds the appropriate CERTFILE and KEYFILE variables to the environment, so TLS programs down the line can find the certificate and key.
- s6-tlsserver rewrites itself into a command line that does a lot of different things; the long-running process is still s6-tcpserver, listening and accepting client connections. For every client, it spawns a process that sets up the TLS transport layer and eventually execs into tipideed.
- tipideed always speaks plaintext HTTP, it has no knowledge of cryptography itself, but it is aware (via an environment variable) that it's running under TLS, and CGI scripts it runs will have the HTTPS=on marker.
- 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.
tipidee service templates
The tipidee source distribution comes with an examples/ subdirectory containing service files to run tipidee under various service managers.