docs: proper docs

DEVELOPMENT.md

@@ -0,0 +1,72 @@
+# Development
+
+## Makefile targets
+
+```txt
+Usage: make [target1] [target2] ...
+
+Commands/Targets:
+help                 show this message
+install              install project
+update               update project dependencies
+format               format project
+lint                 lint project
+build                build project
+start                start server in localhost
+test                 test project
+test-%               test project with specific test
+coverage             test project with coverage
+uv-sync              uv sync
+uv-upgrade           uv sync upgrade
+ruff                 ruff check
+ruff-fix             ruff check (and fix)
+ruff-format          ruff format
+ruff-format-check    ruff format (check only)
+ty                   ty check
+unittest             unittest
+unittest-%           unittest -k [filter]
+coverage-unittest    coverage run -m unittest
+coverage-report      coverage report
+coverage-html        coverage html
+coverage-xml         coverage xml
+docker-build         docker build
+docker-run           docker run
+```
+
+## TODO
+
+- [x] basic http server
+- [x] docker container
+- [x] env instead of args when available
+- [x] PUT gzip data into /data/xxx
+- [x] DELETE request
+- [x] max file size
+- [x] .host in /data/xxx can be translated as host in GET /
+- [x] header to setup .host file instead of in archive
+- [x] ignore .gitignore/.host etc at root
+- [x] cerbot install in container + path env/arg
+- [x] redirect /.well-known/acme-challenge to specific path
+- [x] certbot/self-signed create/renew in specific dir
+- [x] better logger
+- [x] renew command
+- [x] https mode w/ multiple hosts
+- [x] create certificate on request
+- [x] certbot copy certificates for unique path
+- [x] better error page
+- [x] add favicon.ico + special path
+- [x] [http.server security](https://docs.python.org/3/library/http.server.html#http-server-security)
+- [x] launch separate upgrade 80->443 server when https
+- [x] token management with "generate" command and bind path to specific token
+- [x] docker compose example + .env
+- [x] 404 GET on host not found
+- [x] 403 PUT on host already taken
+- [x] remove dot files after file extract
+- [x] unit tests
+- [x] github actions
+- [x] X-Redirect
+- [x] X-Proxy
+- [ ] detect root certificate change and update server
+- [ ] detect tokens change and update token_manager
+- [ ] allow args before/after command
+- [x] proper doc
+

README.md

@@ -1,7 +1,53 @@
-# Stapler
+# Stapler <!-- omit in toc -->
+
+*Static pages as simple as a gzip file*
 
 ![logo.svg](logo.svg)
 
+## Table of Contents <!-- omit in toc -->
+
+- [What is Stapler](#what-is-stapler)
+- [Python CLI](#python-cli)
+  - [Basic usage](#basic-usage)
+- [HTTP API](#http-api)
+  - [Create/update page from gzip](#createupdate-page-from-gzip)
+  - [Create/update page with redirect](#createupdate-page-with-redirect)
+  - [Create/update page with proxy](#createupdate-page-with-proxy)
+  - [Delete page](#delete-page)
+- [Docker](#docker)
+
+
+## What is Stapler
+
+Stapler is a **static page delivery server**.
+
+You feed it a <u>tar.gz</u> file of your content, and it serves it at your desired path or host.
+
+It handles:
+
+* static files delivery: `/path/xxx`
+* directory roots translation into `index.html` (if existing)
+* host translation to specific path: `my.example.com => /path/`
+* auto host discovery and certificate issuing (via certbot)
+* redirect pages: `/path-2/ => (redirect) https://my-website.com`
+* proxy pages: `/path-3/ => https://my-website.com`
+* updating/deleting content via API with `curl`
+
+## Python CLI
+
+### Basic usage
+
+Theres 3 basic commands for the stapler server:
+
+* `run`: launch the server to serve at the desired paths (see full CLI help for env vars and such)
+* `renew`: renew all existing certificates (the server must be running in the background)
+* `token`: generate a new secure API token
+
+See [Docker](#docker) for a quick deployable server.
+
+<details>
+  <summary>Full CLI Help</summary>
+
 ```txt
 usage: stapler [-h] [--debug | --no-debug] [-d DATA_DIR] [--certificates | --no-certificates] [--certbot | --no-certbot]
                [--self-signed-path SELF_SIGNED_PATH] [--certbot-conf CERTBOT_CONF] [--certbot-www CERTBOT_WWW]
@@ -47,22 +93,34 @@ options:
 (Each option can be supplied with equivalent environment variable.)
 ```
 
-## Endpoints
+</details>
 
-### Create/update page
+## HTTP API
+
+### Create/update page from gzip
 
 ```txt
 PUT /{page}/
+  X-Token (your API token)
+  X-Host (optional host as entrypoint)
+  (body with tar data)
 ```
 
 ```bash
-# create archive from 'dist' dir and upload to /my-project/
+# create archive from 'dist' dir and upload it to /my-project/
-tar -czC dist . | curl -X PUT \
+tar -czC dist -f dist.tar.gz .
-  --data-binary @- \
+curl -X PUT \
   -H 'X-Token: <TOKEN>' \
+  --data-binary "@dist.tar.gz" \
   https://stapler-host/my-project/
 
-# create archive from 'dist' dir and upload to /my-project/ and myproject.example.com
+# same thing but one-liner
+tar -czC dist . | curl -X PUT \
+  -H 'X-Token: <TOKEN>' \
+  --data-binary @- \
+  https://stapler-host/my-project/
+
+# make stapler server identifiers myproject.example.com as /my-project/
 tar -czC dist . | curl -X PUT \
   --data-binary @- \
   -H 'X-Token: <TOKEN>' \
@@ -70,10 +128,52 @@ tar -czC dist . | curl -X PUT \
   https://stapler-host/my-project/
 ```
 
+### Create/update page with redirect
+
+```txt
+PUT /{page}/
+  X-Token (your API token)
+  X-Redirect (redirection target)
+  X-Host (optional host as entrypoint)
+```
+
+```bash
+# create /my-project/ that redirects to https://github.com/my-project
+curl -X PUT \
+  -H 'X-Token: <TOKEN>' \
+  -H 'X-Redirect: https://github.com/my-project' \
+  https://stapler-host/my-project/
+
+# simple redirect from root host to www
+curl -X PUT \
+  -H 'X-Token: <TOKEN>' \
+  -H 'X-Proxy: https://www.my-website.com' \
+  -H 'X-Host: my-website.com' \
+  https://stapler-host/my-website-www/
+```
+
+### Create/update page with proxy
+
+```txt
+PUT /{page}/
+  X-Token (your API token)
+  X-Proxy (proxy target)
+  X-Host (optional host as entrypoint)
+```
+
+```bash
+# create /my-website/ that proxies to http://localhost:8000
+curl -X PUT \
+  -H 'X-Token: <TOKEN>' \
+  -H 'X-Proxy: http://localhost:8000' \
+  https://stapler-host/my-project/
+```
+
 ### Delete page
 
 ```txt
 DELETE /{page}/
+  X-Token (your API token)
 ```
 
 ```bash
@@ -83,71 +183,19 @@ curl -X DELETE \
   https://stapler-host/my-project/
 ```
 
-## Development
+## Docker
 
-### TODO
+Stapler ships with a deploy-ready `Dockerfile` and a sample `docker compose` stack with:
 
-- [x] basic http server
+* a main server exposing on port 80 (http) and port 443 (https)
-- [x] docker container
+* a weekly crontab for updating certificates
-- [x] env instead of args when available
-- [x] PUT gzip data into /data/xxx
-- [x] DELETE request
-- [x] max file size
-- [x] .host in /data/xxx can be translated as host in GET /
-- [x] header to setup .host file instead of in archive
-- [x] ignore .gitignore/.host etc at root
-- [x] cerbot install in container + path env/arg
-- [x] redirect /.well-known/acme-challenge to specific path
-- [x] certbot/self-signed create/renew in specific dir
-- [x] better logger
-- [x] renew command
-- [x] https mode w/ multiple hosts
-- [x] create certificate on request
-- [x] certbot copy certificates for unique path
-- [x] better error page
-- [x] add favicon.ico + special path
-- [x] [http.server security](https://docs.python.org/3/library/http.server.html#http-server-security)
-- [x] launch separate upgrade 80->443 server when https
-- [x] token management with "generate" command and bind path to specific token
-- [x] docker compose example + .env
-- [x] 404 GET on host not found
-- [x] 403 PUT on host already taken
-- [x] remove dot files after file extract
-- [x] unit tests
-- [x] github actions
-- [x] X-Redirect
-- [x] X-Proxy
-- [ ] proper doc
 
-### Makefile targets
+```bash
-
+cp crontab.example crontab
-```txt
+cp compose.example.yml compose.yml
-Usage: make [target1] [target2] ...
+cp .env.example .env
-
+$EDITOR .env # update HOST and TOKEN_SALT
-Commands/Targets:
+docker compose up
-help                 show this message
+# whenever you need a new token
-install              install project
+docker compose run stapler token
-update               update project dependencies
-format               format project
-lint                 lint project
-build                build project
-start                start server in localhost
-test                 test project
-test-%               test project with specific test
-coverage             test project with coverage
-uv-sync              uv sync
-uv-upgrade           uv sync upgrade
-ruff                 ruff check
-ruff-fix             ruff check (and fix)
-ruff-format          ruff format
-ruff-format-check    ruff format (check only)
-ty                   ty check
-unittest             unittest
-unittest-%           unittest -k [filter]
-coverage-unittest    coverage run -m unittest
-coverage-report      coverage report
-coverage-html        coverage html
-coverage-xml         coverage xml
-docker-build         docker build
-docker-run           docker run
 ```