Update README.md

README.md

@@ -1,16 +1,143 @@
 # <img src="../../raw/assets/icon.png" width=75> simple-shortener
 
+Easily wrap a self-hosted URL shortening service around your personal sites.
+
+[View on Docker Hub](https://hub.docker.com/r/jessiehildebrandt/simple-shortener)
+
+Created with [Fennel](https://fennel-lang.org), [Turbo](https://github.com/kernelsauce/turbo), and [Mithril](https://mithril.js.org/).
+
+[![Build Status](https://gitlab.com/jessieh/simple-shortener/badges/main/pipeline.svg)](https://gitlab.com/jessieh/simple-shortener/-/pipelines)
+
 ## Demo
 
 <img src="../../raw/assets/demo.png">
 
+## Deploying
 
-# To Document:
+**NOTE**: You will need to configure `auth_secret` before the service will run. See **[Configuration](#configuration)**.
 
-* Docker deployment
+With Docker<sup>1</sup>:
 
-* docker-compose deployment
+```bash
+docker run -d \
+-p 80:80 \
+--env-file config.env \
+--mount source=shortener-db,target=/simple-shortener/db \
+--mount type=bind,source=/PATH/TO/YOUR/SITE,target=/simple-shortener/static/landing_page,readonly \
+jessiehildebrandt/simple-shortener
+```
 
-* Update landing page deployment examples
+With Docker Compose<sup>1</sup>:
 
-* API endpoints and response codes
+```yaml
+simple-shortener:
+  image: jessiehildebrandt/simple-shortener
+  env_file: config.env
+  ports:
+    - 80:80
+  volumes:
+    - shortener-db:/simple-shortener/db
+    - /PATH/TO/YOUR/SITE:/simple-shortener/static/landing_page:ro
+
+volumes:
+  shortener-db:
+```
+
+After deploying, you should be able to navigate your browser to `<YOUR_DOMAIN>` to view your site, or `<YOUR_DOMAIN>/shorten` to log in to the control panel. If you have TOTP auth enabled (on by default), check your Docker logs for a QR code to scan with your TOTP generator app of choice. If you disabled TOTP auth, you can log in by entering `auth_secret` as the passcode.
+
+<sup>1</sup> You should probably avoid directly exposing the Turbo HTTP server as in these examples, and should instead opt to use a more robust server as a reverse-proxy.
+
+## Configuration
+
+You can easily configure your deployment by supplying an environment variable file with your desired settings.
+
+An [example environment variable file](config_template.env) is provided for use as a template.
+
+Supported configuration options:
+
+### auth_secret ***(REQUIRED)***
+**string**
+
+*THIS VALUE NEEDS TO BE SET BEFORE THE SERVICE WILL START!*
+
+This is used to authenticate sessions for the shortener control panel and the REST API.
+Depending on configuration, this can either be used as a TOTP secret or as a password.
+
+### enable_control_panel
+**boolean**
+
+Whether or not a static control panel page for interacting with the shortening service will be exposed at `/shorten`.
+
+Default `true`
+
+### enable_landing_page
+**boolean**
+
+Whether or not a static landing page will be served when not visiting shortened links or the control panel.
+
+Default `true`
+
+### landing_page_index
+**string**
+
+The path to the file to use as the index for the landing page.
+
+*This only has an effect when `enable_landing_page` is set to true.*
+
+Default `index.html`
+
+### listen_port
+**number**
+
+The port that the HTTP server will listen on.
+
+Default `80`
+
+### query_limit
+**number**
+
+The maximum number of database entries that the API will return in a single query.
+
+Default `100`
+
+### session_max_length_hours
+**number**
+
+The duration (in hours) that an API session will be valid for once signed in, regardless of activity.
+
+Default `24`
+
+### session_max_idle_length_hours
+**number**
+
+The duration (in hours) that an API session will be valid for without any activity.
+
+Default `1`
+
+### use_secure_cookies
+**boolean**
+
+Whether or not to tag API session cookies with the `Secure` and `SameSite=Strict` attributes.'
+
+Secure cookies expect your server to have HTTPS enabled, and will prevent the control panel and API from functioning over unsecured connections.
+
+Default `true`
+
+### use_totp
+**boolean**
+
+Whether or not `auth_secret` will be used as a TOTP secret instead of a password.
+
+If enabled, the server will print a QR code to stdout containing a standardized URL that you can scan with most TOTP generators.
+
+(TOTP is recommended, but you may want to disable it if (e.g) your system cannot be synchronized to global time.)
+
+Default `true`
+
+## API
+
+The shortening service exposes a simple API at `/shorten/api` that you may consume from your own control panel<sup>1</sup>, a browser extension, etc.
+
+The API endpoints and response codes are documented in the docstrings of their respective [handler modules](src/handlers).
+
+<sup>1</sup> If you wish to replace the default control panel, you can provide your own by mounting it at `/simple-shortener/static/control_panel`.