From 7ebaca411d5d63a37121279d37c5be83edf7d1c7 Mon Sep 17 00:00:00 2001 From: Jessie Hildebrandt Date: Tue, 21 Dec 2021 03:07:50 -0500 Subject: [PATCH] Update README.md --- README.md | 137 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 132 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 31fbabb..85e0926 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,143 @@ # 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 +## Deploying -# To Document: +**NOTE**: You will need to configure `auth_secret` before the service will run. See **[Configuration](#configuration)**. -* Docker deployment +With Docker1: -* 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 Compose1: -* 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 `` to view your site, or `/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. + +1 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 panel1, a browser extension, etc. + +The API endpoints and response codes are documented in the docstrings of their respective [handler modules](src/handlers). + +1 If you wish to replace the default control panel, you can provide your own by mounting it at `/simple-shortener/static/control_panel`.