From e6ada0b74352f77124a682d98c6d842fd5c44b45 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Wed, 23 Aug 2023 15:36:55 +0000 Subject: Add some doc Signed-off-by: Laurent Bercot --- doc/quickstart.html | 107 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 107 insertions(+) create mode 100644 doc/quickstart.html (limited to 'doc/quickstart.html') 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 @@ + + + + + + tipidee: quickstart guide + + + + + + +

+tipidee
+Software
+skarnet.org +

+ +

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 and you need to +serve the example.com and example.org domains, create +/home/www/example.com and /home/www/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 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 adresses.
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, +the basic command line for an HTTP service is: +s6-envuidgid www s6-tcpserver -U example.com 80 s6-tcpserver-access -v0 -- 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. 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.
- 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 -e example.com 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. For every client connection, 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 made aware 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. + + + + -- cgit v1.3.1