ushort/docs/deployment.md

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:

/opt/ushort/
├── docker-compose.yml
├── config.toml
└── data/

Copy 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:

image: docker.io/sodium/ushort:0.1.2@sha256:<verified-index-digest>

Set db_path = "data/urlshort.db". The executable always 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

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 for a path such as https://example.com/s;
• 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:

nginx -t
nginx -s reload

Then verify the public health endpoint, frontend, static assets, and an existing short-code redirect. 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.
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:

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.