ref: bedac6438461449392694dd8c4a7028ccdc46019
parent: 97cc4a9ae486ecca17806520f760d03dcb19ed52
author: kvik <kvik@a-b.xyz>
date: Mon Jan 11 21:33:45 EST 2021
rc-httpd-werc: new docs (thanks tevo)
--- /dev/null
+++ b/rc-httpd-werc.md
@@ -1,0 +1,50 @@
+# Setting up rc-httpd
+
+`rc-httpd` is a web server written in rc and shipped with 9front; It is used to host [9front.org](http://9front.org) and [cat-v.org](http://cat-v.org), among other related websites. It relies on `listen`/`listen1` for network listening, and invokes `/rc/bin/rc-httpd/select-handler` in order to decide how to serve the requested page. For setting up a simple web page:
+
+* Set up `listen` to invoke rc-httpd: on a default 9front instalation (when configured as a cpu server), `listen` looks for unpriviledged services (that run as the user `none`) in `/rc/bin/service`, and priviledged ones (that run as the current user) in `/rc/bin/service.auth`. 9front also ships with a script that invokes `rc-httpd` each connection in `/rc/bin/service/!tcp80`; renaming this file to `tcp80` in the same folder should work for most common cases; check listen(8) for more options and details. `listen1` may also be useful to setup a oneshot server for testing.
+
+* Edit the script `/rc/bin/rc-httpd/select-handler` (you might have to create and `chmod +x` it) to set up the appropriate environment variables and handle the request. At the very least, set up FS_ROOT to point to the root directory of the server, PATH_INFO to the location (relative to `$FS_ROOT`) to be served (usually set to `$location`, which contains the path specified in the request) and `exec` one of the `rc-httpd` default handlers. `$SERVER_NAME` contains the address requested, useful if many websites are being hosted in the same machine. A example `select-handler` is shown below:
+
+ #!/bin/rc
+
+ PATH_INFO=$location
+
+ switch($SERVER_NAME) {+ case example.com
+ FS_ROOT=/sys/www/$SERVER_NAME
+ exec static-or-index
+
+ case *
+ error 503
+ }
+
+ A list of available handlers, along with set/used environment variables and more information about the `select-handler` script is available at rc-httpd(8). `/sys/log/www` may contain useful debugging information, in case things don't work.
+
+Congratulations! You've just got yourself a 100% genuine 9front-hosted webshit, complete with everything one could ever ask for! I'm sorry.
+
+# Werc with rc-httpd
+
+Werc is a minimalist web "anti-framework" written in rc; It powers [9front.org](http://9front.org), [cat-v.org](http://cat-v.org) and other related websites. For using it together with `rc-httpd`:
+
+* Download the most recent tarball from [werc.cat-v.org](http://werc.cat-v.org/) and unpack it somewhere. This guide will use `/sys/www/werc`, replace accordingly.
+
+* Create your website page at `/sys/www/werc/sites/<domain>` and set it up appropriately. This is left as an exercise to the reader.
+
+* In your `/rc/bin/rc-httpd/select-handler`, set the PLAN9 variable to `/` (in order to support plan9port, werc expects PLAN9 to be set to the location where it can find the standard Plan 9 hierarchy and utilities; in Plan 9 (assuming a standard namespace), this is our root folder), make the appropriate arrangements, set FS_ROOT to the werc website path then `exec static-or-cgi <path to werc.rc>` (replace `static-or-cgi` with `cgi` if you don't want `rc-httpd` falling back to serving as static content). An example `select-handler` follows:
+
+ #!/bin/rc
+
+ PLAN9=/
+ PATH_INFO=$location
+
+ switch($SERVER_NAME) {+ case example.com
+ FS_ROOT=/sys/www/werc/sites/$SERVER_NAME
+ exec static-or-cgi /sys/www/werc/bin/werc.rc
+
+ case *
+ error 503
+ }
+
+Congratulations! Your 9front-hosted webshit should now be using werc.