Add some doc

Signed-off-by: Laurent Bercot <ska@appnovation.com>

2 files changed, 166 insertions, 7 deletions

diff --git a/doc/index.html b/doc/index.html
index 9f3bc2f..6cb995d 100644
--- a/doc/index.html
+++ b/doc/index.html
@@ -20,18 +20,34 @@
 <h2> What is it&nbsp;? </h2>
 
 <p>
-  tipidee is a web server. It supports HTTP/1.1. It aims to be compliant
+  tipidee is a web server. It supports HTTP 1.0 and 1.1. It aims to be compliant
 with <a href="https://datatracker.ietf.org/doc/html/rfc9112">RFC 9112</a>:
 while it only implements a very limited subset of the optional functionality
-in HTTP/1.1, it implements all the mandatory parts.
+in HTTP 1.1, it implements all the mandatory parts. It is usable with both
+HTTP and HTTPS.
+</p>
+
+<p>
+ It runs under a super-server, e.g. inetd,
+<a href="//skarnet.org/software/s6-networking/s6-tcpserver.html">s6-tcpserver</a>, or
+<a href="//skarnet.org/software/s6-networking/s6-tlsserver.html">s6-tlsserver</a>
+(for HTTPS). Traditionally, inetd-mode web servers aren't considered performant,
+but tipidee aims to eke out every single drop of performance that is attainable from
+its programming model.
 </p>
 
 <hr />
 
+<ul>
+ <li> For the impatient: a <a href="quickstart.html">quickstart guide</a>. </li>
+</ul>
+
+<hr />
+
 <h2> Why another Web server? </h2>
 
 <p>
- There are two groups of web servers.
+ There are roughly two groups of web servers.
 </p>
 
 <p>
@@ -46,14 +62,41 @@ for instance, was developed as a proof of concept for solving the
 </p>
 
 <p>
- The second one is 
+ The second one is small, quick-and-dirty servers, aimed at easily deploying
+basic HTTP service for serving static files for prototying or in resource
+constrained environments such as embedded devices. Among them, for instance,
+<a href="https://busybox.net/">busybox httpd</a>,
+<a href="http://www.eterna.com.au/bozohttpd/">bozohttpd</a>, or various
+httpds from <a href="https://acme.com/software/">ACME Labs</a>.
+</p>
+
+<p>
+ And, surprisingly, not much in between. There are a ton of supposedly
+"tiny" or "minimal" servers, written in languages whose naked runtime uses
+more resources than <a href="//skarnet.org/software/">the whole skarnet.org
+ecosystem</a> by two orders of magnitude; but there isn't one that focused
+on what I want from a web server, which is:
+</p>
+
+<ul>
+ <li> Usability with HTTPS without the need to entangle the code with a
+given TLS library (which means delegating the TLS layer to a super-server
+and not performing the socket work itself) </li>
+ <li> Support for HTTP 1.1, not only 1.0 </li>
+ <li> Support for real CGI, not only NPH </li>
+</ul>
+
+<p>
+ All in all, I felt that despite how crowded the web server space is,
+there wasn't a satisfactory offer for the needs of skarnet.org and a
+few similar sites.
 </p>
 
 <h3> And why "tipidee"? </h3>
 
 <p>
- Because <em>h-t-t-p-d</em> is pretty tedious to say out loud, and only
-keeping the last syllables makes it easier.
+ Because <em>h-t-t-p-d</em> is pretty tedious to say out loud.
+kKeeping the last three syllables makes it easier.
 </p>
 
 <h2> Installation </h2>
@@ -72,7 +115,10 @@ library. </li>
 on a super-server to listen to the network and provide connection
 information via environment variables. It also defers to tools such as
 <a href="//skarnet.org/software/s6-networking/s6-tcpserver-access.html">s6-tcpserver-access</a>
-to provide access control and connection fine-tuning. </li>
+to provide access control and connection fine-tuning. And if you want
+to run an HTTPS server, you'll need something like
+<a href="//skarnet.org/software/s6-networking/s6-tlsserver.html">s6-tlsserver</a>
+to manage the TLS transport layer. </li>
 </ul>
 
 <h3> Licensing </h3>
@@ -126,6 +172,12 @@ the previous versions of tipidee and the current one. </li>
 <li><a href="tipidee-config-preprocess.html">The <tt>tipidee-config-preprocess</tt> internal program</a></li>
 </ul>
 
+<h3> Configuration format </h3>
+
+<ul>
+<li><a href="tipidee.conf.html">The <tt>/etc/tipidee.conf</tt> file format</a></li>
+</ul>
+
 <h2> Related resources </h2>
 
 <ul>
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>:&gt; /etc/tipidee.conf &amp;&amp; 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>