Stapler
Static pages as simple as a gzip file
Table of Contents
What is Stapler
Stapler is a static page delivery server.
You feed it a tar.gz 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 for a quick deployable server.
Full CLI Help
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]
[--host HOST] [--http-port HTTP_PORT] [--https-port HTTPS_PORT] [--https | --no-https] [-t TOKEN_SALT]
[--max-size-bytes MAX_SIZE] [-b BIND]
COMMAND ...
Static pages as simple as a gzip file
positional arguments:
COMMAND
run Run Stapler server
renew Renew certificates
token Generate a new token
options:
-h, --help show this help message and exit
--debug, --no-debug
-d, --data-dir DATA_DIR
directory where pages are/will be stored (default: ./data)
--certificates, --no-certificates
Handle certificates (default: true)
--certbot, --no-certbot
Use Certbot (default: true)
--self-signed-path SELF_SIGNED_PATH
Self-signed certificates dir (default: ./data/.certificates)
--certbot-conf CERTBOT_CONF
Certbot config dir (default: /etc/letsencrypt)
--certbot-www CERTBOT_WWW
Certbot www dir (default: ./data/.certbot)
--host HOST server default host (default: localhost)
--http-port HTTP_PORT
server http port (default: 80)
--https-port HTTPS_PORT
server https port (default: 443)
--https, --no-https Use https (implies --certificates) (default: true)
-t, --token-salt TOKEN_SALT
salt for tokens generation
--max-size-bytes MAX_SIZE
max size of accepted archives (in bytes) (default: 2000000)
-b, --bind BIND server bind address (default: 0.0.0.0)
(Each option can be supplied with equivalent environment variable.)
HTTP API
Create/update page from gzip
PUT /{page}/
X-Token (your API token)
X-Host (optional host as entrypoint)
(body with tar data)
# create archive from 'dist' dir and upload it to /my-project/
tar -czC dist -f dist.tar.gz .
curl -X PUT \
-H 'X-Token: <TOKEN>' \
--data-binary "@dist.tar.gz" \
https://stapler-host/my-project/
# 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>' \
-H 'X-Host: myproject.example.com' \
https://stapler-host/my-project/
Create/update page with redirect
PUT /{page}/
X-Token (your API token)
X-Redirect (redirection target)
X-Host (optional host as entrypoint)
# 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
PUT /{page}/
X-Token (your API token)
X-Proxy (proxy target)
X-Host (optional host as entrypoint)
# 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
DELETE /{page}/
X-Token (your API token)
# delete /my-project/
curl -X DELETE \
-H 'X-Token: <TOKEN>' \
https://stapler-host/my-project/
Docker
Stapler ships with a deploy-ready Dockerfile and a sample docker compose stack with:
- a main server exposing on port 80 (http) and port 443 (https)
- a weekly crontab for updating certificates
cp crontab.example crontab
cp compose.example.yml compose.yml
cp .env.example .env
$EDITOR .env # update HOST and TOKEN_SALT
docker compose up
# whenever you need a new token
docker compose run --rm stapler token