organize deployment configs and documentation

2026-07-10 12:57:21 +00:00
parent 47795011b6
commit ff2290f0f1
14 changed files with 387 additions and 375 deletions
@@ -0,0 +1,90 @@
+# Production deployment and rollback
+
+The production host needs only a Compose file, `config.toml`, and persistent
+data. It does not need a source checkout.
+
+## Files
+
+Create an application directory like this:
+
+```text
+/opt/ushort/
+├── docker-compose.yml
+├── config.toml
+└── data/
+```
+
+Copy [`deploy/docker-compose.prod.yml`](../deploy/docker-compose.prod.yml) to
+the server as `docker-compose.yml`. For repeatable releases, replace its image
+tag with the verified multi-architecture digest:
+
+```yaml
+image: docker.io/sodium/ushort:0.1.1@sha256:<verified-index-digest>
+```
+
+Set `db_path = "data/urlshort.db"` and normally keep `production = false` so
+the executable serves its embedded frontend. Keep `config.toml` owned by the
+container identity (`1001:1001`) with mode `0400`; the `data` directory must be
+writable by the same identity.
+
+## Start and validate
+
+```bash
+cd /opt/ushort
+docker compose config
+docker compose pull
+docker compose up -d
+docker compose ps
+docker compose logs --tail=100 ushort
+
+curl -i http://127.0.0.1:18082/s/api/health
+```
+
+Adjust the health path to match `base_url`.
+
+## Reverse proxy
+
+Choose one nginx snippet and include it inside the public `server {}` block:
+
+- [`deploy/nginx.path.conf`](../deploy/nginx.path.conf) for a path such as
+  `https://example.com/s`;
+- [`deploy/nginx.subdomain.conf`](../deploy/nginx.subdomain.conf) for a host
+  such as `https://s.example.com`.
+
+Both snippets proxy the frontend, API, and redirects to `127.0.0.1:18082`.
+They apply `no-store` to the HTML entry point and `no-cache` to static assets.
+The path snippet is written for `/s`; replace each `/s` location when using a
+different configured prefix.
+
+Test nginx before reloading it:
+
+```bash
+nginx -t
+nginx -s reload
+```
+
+Then verify the public health endpoint, frontend, static assets, and an
+existing short-code redirect. [`tests/smoke.sh`](../tests/smoke.sh) exercises
+the complete trailing-slash route set against a disposable record.
+
+## Update
+
+1. Verify the published image contains both AMD64 and ARM64 manifests.
+2. Pull the exact version and digest before changing the running service.
+3. Create and integrity-check an online SQLite backup as described in
+   [Data and database compatibility](data.md).
+4. Update the image reference and run `docker compose up -d`.
+5. Check health, logs, restart count, database integrity, and public routes.
+
+## Rollback
+
+Restore the previous image reference and run:
+
+```bash
+docker compose up -d
+```
+
+The schema is release-compatible. If the failed release changed or damaged
+data, stop the service and restore the pre-update SQLite backup before bringing
+the previous image back up. Preserve any legitimate writes made after the
+backup before replacing the database.