Installation

Run Sancho on your own server behind a single subdomain (e.g. sancho.example.com) using pre-built GHCR images and Docker Compose.

Requirements

• docker
• Docker Compose plugin (v2.20+)

Directory contents

File	Purpose
docker-compose.yaml	Service definitions (postgres, rabbitmq, redis, api, app, caddy + optional postgres-backup, garage)
Caddyfile	Outer Caddy config — TLS termination + reverse proxy
garage.toml	Single-node Garage config; used only when the garage profile is active
.env.example	Runtime env-var template; copy to .env
sancho-update.service	Optional systemd unit: pulls and restarts the api and app containers
sancho-update.timer	Optional systemd timer: fires the update service daily at 04:00 UTC

Core services (always running): postgres, rabbitmq, redis, api, app, caddy. Optional profiles (off by default, opt in via COMPOSE_PROFILES in .env):

• backup — daily pg_dump to S3 via the postgres-backup service. See Backups.
• garage — in-stack S3 backend, when you don’t want an external provider. See In-stack S3 backend (Garage).

Set COMPOSE_PROFILES=backup,garage (or any subset) in .env before docker compose up -d.

Architecture

                 Browser
                    │  https://sancho.example.com
                    ▼
          ┌─────────────────┐
          │  Caddy (80/443) │   auto-TLS via Let's Encrypt
          └────────┬────────┘
                   │
         ┌─────────┼──────────┐
         │         │          │
  /api/* /v1/*  /analytics/*  everything else
         │         │          │
         ▼         ▼          ▼
      api:3100   PostHog    app:80
         │         (EU)    (static SPA)
         │
   ┌─────┼─────┐
   │     │     │
   ▼     ▼     ▼
postgres rabbitmq redis

api → external: SMTP relay (or Cloudflare Email Send), Google OAuth, Nextcloud OAuth, S3, Parseur, [Stripe]

Single subdomain, path-based routing. Cookies are scoped to DEPLOY_HOSTNAME; HTTPS is mandatory (session cookies are SameSite=Strict; Secure; HttpOnly).

Prerequisites

• Linux server, Docker 24.0.6+ with Docker Compose v2.20+ (required: false in depends_on was added in Compose v2.20)
• Public domain with an A/AAAA DNS record pointing at the server
• Ports 80 and 443 open (port 80 is needed for the ACME HTTP challenge)
• ≥ 4 vCPU / 16 GB RAM (recommended)

Third-party services

Service	Purpose	Required?
Google Cloud OAuth	User sign-in	Required if using Google SSO
Nextcloud OAuth (built-in)	User sign-in via your Nextcloud (built-in OAuth 2.0 client)	Optional (alternative to Google)
Nextcloud OIDC	User sign-in via Nextcloud with a third-party OIDC app	Optional (alternative to the OAuth block)
SMTP relay (or Cloudflare Email Send)	Transactional email (password reset, verification)	One of the two is required
S3-compatible storage	Avatar + delivery-note image storage	Required (external provider or in-stack garage profile)
Parseur	Delivery-note OCR	Only for OCR_PROVIDER=parseur
Anthropic	Delivery-note OCR on a Claude model	Only for OCR_PROVIDER=anthropic
PostHog	Product analytics	Optional
Axiom	Log aggregation	Optional

Generate secrets

openssl rand -hex 32     # API_SESSION_SECRET
openssl rand -hex 32     # API_COOKIE_SECRET
openssl rand -base64 24  # PG_PASSWORD, RABBITMQ_ADMIN_PASSWORD, ROOT_PASSWORD

Configure the .env file

cp .env.example .env

Secure file permissions

Lock down permissions before pasting any secrets. Default umask leaves .env world-readable (0644). The file will hold ROOT_PASSWORD, session / cookie secrets, the Postgres and RabbitMQ passwords, S3 keys, OAuth client secrets, and the Cloudflare/Parseur/Axiom tokens in cleartext — restrict it before you paste any of those in.

chmod 600 .env
chown root:root .env

chmod 600 keeps the file readable only by its owner; group / other get nothing. Under 0600 the group ownership is irrelevant, so root:root is fine even if other accounts are in the docker group. After writing your secrets, verify with ls -l .env — the output must start with -rw-------.

Leak via docker inspect

The postgres and rabbitmq services currently pass passwords via the compose environment: block. Anyone who can run docker inspect (membership in the docker group is equivalent to root) can read them. Migrating to Docker secrets closes this gap and is tracked separately.

The template groups variables by purpose. Fill each group in order.

Core (required)

• DEPLOY_HOSTNAME — the public FQDN, e.g. sancho.example.com. The api also uses this value to scope session cookies and to build OAuth callback / email URLs, so it must match the URL users visit.
• ACME_EMAIL — the contact address Caddy registers with Let’s Encrypt for expiry warnings.
• SANCHO_CHANNEL — release channel. Defaults to prod (master images: sancho-wms-{api,app}-prod). Set to dev to track develop-branch pre-releases (sancho-wms-{api,app}-dev).
• DEPLOY_ENV — S3 bucket-name suffix (sancho-env-${DEPLOY_ENV} and sancho-env-${DEPLOY_ENV}-account-1). Defaults to prod. Do not change after the first boot — the bucket names are derived from it and are not migrated.

Secrets (required)

All these secrets are mandatory — the api’s config schema rejects missing values at startup and the container exits immediately. Paste outputs from Generate secrets.

• API_SESSION_SECRET — hex value (min. 32 chars), signs session cookies.
• API_COOKIE_SECRET — hex value (min. 32 chars), signs other cookies.
• PG_PASSWORD — base64 value, Postgres user password.
• RABBITMQ_ADMIN_PASSWORD — base64 value, RabbitMQ admin password.
• ROOT_PASSWORD — base64 value, seeds the root user on first boot. Must stay set on every restart (config is re-validated); rotating it in .env only affects future seeds, not the existing root account’s password.

Database / queue (required)

Keep the defaults unless you have a reason to change them.

• PG_USER — defaults to sancho.
• PG_DB — defaults to sancho.
• RABBITMQ_ADMIN_USER — defaults to sancho.

Logging (required)

Both variables are required — a missing one stops the api at startup.

• API_LOG_LEVEL — api log level: trace, debug, info, warn, error, or fatal. The template ships info.
• API_LOG_PRETTY — true formats logs human-readably; keep false (JSON) in production.

Email transport (one of the two required)

If both are set, Cloudflare wins.

SMTP

• SMTP_HOST — relay hostname.
• SMTP_PORT — defaults to 587.
• SMTP_USER — optional; leave blank for relays that authenticate by password alone.
• SMTP_PASSWORD — required with SMTP_HOST.

Cloudflare Email Send

• CLOUDFLARE_EMAIL_ACCOUNT_ID — Cloudflare account ID.
• CLOUDFLARE_EMAIL_API_TOKEN — account-scoped token with the Email Routing: Send permission.

Auth methods

Email/password and Google sign-in are configured in .env — a blank block hides the matching sign-in option, and the web app discovers which methods are enabled from the api at runtime, so toggling only needs an api restart — no image rebuild. Nextcloud sign-in (OAuth and OIDC) is instead configured in the Sancho UI (Account → Configuration) — credentials, email domain allowlists, and group-to-role mapping are stored in the database, and the sign-in button appears automatically, with no .env variables and no restart. Nextcloud sign-in must start from Sancho’s email-first sign-in form: the api requires the resolved email as login_hint and rejects callbacks where Nextcloud returns a different email. Pick one Nextcloud path (OAuth or OIDC); enabling both works but shows two identical buttons and risks a providerId collision if the same user signs in via both.

• ENABLE_EMAIL_AUTH — true keeps email/password sign-in on; set false to force SSO.

Google OAuth

• GOOGLE_ID / GOOGLE_SECRET — OAuth client from Google Cloud Console → APIs & Services → Credentials → Create OAuth client → Web application.
• Authorized redirect URI: https://<DEPLOY_HOSTNAME>/api/login/google/callback.
• Both values must be set for the button to appear.

Nextcloud OAuth2 (built-in)

Built-in OAuth 2.0 client — ships with every Nextcloud, no extra app needed. The profile is fetched via the OCS provisioning API; the access token is a full-account Bearer.

• Configure in the Sancho UI: Account → Configuration — enter the Nextcloud base URL (e.g. https://cloud.example.com) and the OAuth 2.0 client credentials. Settings are stored in the database — no .env variables and no api restart.
• Create the client in Nextcloud: Admin settings → Security → OAuth 2.0 clients → Add client.
• Redirection URI: https://<DEPLOY_HOSTNAME>/api/login/nextcloud/<accountName>/callback (the Sancho account name; on self-hosted — the root account’s).

Nextcloud OIDC (third-party app)

For Nextcloud installs running a third-party OIDC app (oidc or user_oidc, installed via the app catalogue). Register the client in that app’s admin UI, not in the built-in OAuth 2.0 clients page — the two stores are separate. The api requests scopes openid profile email groups offline_access, validates the id_token, and reads the standard /userinfo endpoint. Discovery is lazy on the first sign-in click against <Nextcloud URL>/.well-known/openid-configuration, so a cold Nextcloud does not block api boot.

• Configure in the Sancho UI: Account → Configuration — enter the Nextcloud base URL and the client credentials from the OIDC app’s panel. Settings are stored in the database — no .env variables and no api restart.
• Redirection URI: https://<DEPLOY_HOSTNAME>/api/login/nextcloud-oidc/<accountName>/callback (the Sancho account name; on self-hosted — the root account’s).
• Automatic role assignment from groups — an option in the same configuration. When enabled, the api reads the groups[] claim on every OIDC sign-in and syncs the user’s role: the first custom Sancho role whose name matches a group name is assigned; if no group matches, the user is reverted to the built-in Member role. SuperAdmin accounts are never modified, and built-in role names (Member, SuperAdmin) are skipped during matching. Create the matching custom roles in Sancho first.

S3 (required) — pick one of two backends

• External provider (recommended for production) — AWS S3, Cloudflare R2, Backblaze B2, MinIO, etc. Two ways to provision the buckets:

  • Pre-create the buckets and grant the access key object-level access on them.
  • Or grant the key CreateBucket permission and let the api provision them on first boot.

• In-stack Garage — set COMPOSE_PROFILES=garage and S3_ENDPOINT=http://garage:3900. Generate S3_API_KEY / S3_API_SECRET / GARAGE_RPC_SECRET with openssl rand. No extra commands — the api creates its buckets on first boot. See In-stack S3 backend (Garage).

Variables:

• S3_ENDPOINT — S3-compatible endpoint URL (http://garage:3900 for in-stack Garage).
• S3_API_KEY — access key.
• S3_API_SECRET — secret key.
• GARAGE_RPC_SECRET — required only when garage is in COMPOSE_PROFILES. Generate with openssl rand -hex 32.

OCR

OCR_PROVIDER picks the recognition engine: parseur (default), custom — your own HTTP service, or anthropic — extraction on an Anthropic Claude model. The contract for custom is documented in Custom OCR.

For OCR_PROVIDER=parseur, sign up at parseur.com, create a parser tailored to your suppliers’ delivery-note layouts, then copy the API key and parser ID from the parser settings.

• PARSEUR_API_KEY — from the Parseur dashboard. Required only for OCR_PROVIDER=parseur.
• PARSEUR_GOODS_ISSUED_NOTE_PARSER_ID — target parser ID. Leave blank to disable delivery-note OCR.

For OCR_PROVIDER=custom, OCR_CUSTOM_BASE_URL is required; OCR_CUSTOM_SUBMIT_PATH, OCR_CUSTOM_STATUS_PATH and OCR_CUSTOM_API_KEY are optional. An invalid combination stops the API from starting.

For OCR_PROVIDER=anthropic, ANTHROPIC_API_KEY is required; OCR_ANTHROPIC_MODEL (default claude-opus-5) is optional. There is no parser setup — document scans are sent to the Anthropic API for extraction.

Optional profiles

Activate via COMPOSE_PROFILES (CSV: backup, garage, or both).

• COMPOSE_PROFILES — e.g. backup, garage, or backup,garage. Blank = only the core services run.
• BACKUP_S3_BUCKET — bucket name for the daily pg_dump. Required only when backup is in COMPOSE_PROFILES. The api does not create this bucket — pre-create it on your external S3, or for in-stack Garage run docker compose exec garage /garage bucket create $BACKUP_S3_BUCKET once. See Backups.

Single-account model with domain-allowlisted signup

Self-hosted Sancho runs as a single tenant: SSO sign-ins (Google and Nextcloud) land in the root account. Additional users join the root account in one of two ways:

• Domain allowlist — configure in the Sancho UI: Account → Configuration → Allowed email domains (values are stored in the database, not in .env). Users signing in via Google or Nextcloud are auto-added to the root account with the Member (non-admin) role. When the list is non-empty, the email domain must match — attempts from outside the list are rejected with a redirect to /sign-in?error=signup_disabled. An empty list means no domain restriction for SSO.
• Invitations — the root admin can invite any email address from the in-app members page; the recipient accepts via the standard invitation link and joins the root account with the role chosen by the admin. Invitations bypass the domain allowlist.

Member users have no admin policy — they can use the application but cannot run root-only operations. The root admin can promote them to a different role from the members page. Email + password registration is controlled by ENABLE_EMAIL_AUTH (the domain allowlist does not apply to it) — set it to false to restrict sign-in to SSO only.

Optional

Leave blank to disable.

• ROOT_EMAIL — overrides the root user’s email address; defaults to root_${DEPLOY_ENV}@sancho-wms.pl (with DEPLOY_ENV=prod: root_prod@sancho-wms.pl). Set it before the first boot — the seed creates the root user only once.
• POSTHOG_KEY — product analytics key served to the web app.
• AXIOM_DATASET — Axiom log dataset name.
• AXIOM_TOKEN — Axiom API token.

Registry login

The api and app images are published to ghcr.io/sancho-wms/* as private packages, so docker compose pull needs credentials — both for the first deploy and every subsequent update. Sancho issues you a read-only token scoped to these packages; you don’t need to create a GitHub PAT yourself.

Log in on the host as the user who will run docker compose. The systemd update timer runs as root, so if you plan to enable it, run this as root:

echo <TOKEN> | docker login ghcr.io -u sancho-wms --password-stdin

Use the username and token Sancho provided. Credentials land in ~/.docker/config.json and persist across reboots — re-run only if the token is rotated.

First deploy

1. Pull the images:

   docker compose pull

2. Bring up the stack:

   docker compose up -d

The api automatically applies migrations and seeds the root user on every boot. The first visit to https://<DEPLOY_HOSTNAME> triggers Caddy to request a Let’s Encrypt certificate — usually 10–30 seconds.

What happens on first boot

With SELFHOSTED_DEPLOYMENT=true hardcoded in the compose, the api runs the full set of Drizzle migrations and seeds the root user in-process before listening. Expect the first up -d to take ~30s longer than a warm restart while migrations apply. Caddy’s healthcheck against api:3100 will fail in that window — this is normal. On every subsequent boot, migrations no-op fast and the root seed is skipped because the user already exists.

If you forget to set ROOT_PASSWORD

The api’s Zod config validation fails and the container exits before listening — docker compose logs api will show the Zod error naming ROOT_PASSWORD. Set a value in .env and docker compose up -d again.

Note

SELFHOSTED_DEPLOYMENT is hardcoded in docker-compose.yaml ("true"). DEPLOY_ENV, by contrast, is read from .env (defaults to prod) — see Core; do not change it after the first boot.

First sign-in

The seed creates a root user at root_prod@sancho-wms.pl (the default is root_${DEPLOY_ENV}@sancho-wms.pl; overridable via ROOT_EMAIL in .env set before the first boot) with the ROOT_PASSWORD you set. For everyday users, prefer Google or Nextcloud SSO.

Optional features

PostHog analytics

Set POSTHOG_KEY in .env to your PostHog project key, then docker compose up -d to restart the api. The key is served to the web app at runtime (via /api/trpc/getAppConfig) — no rebuild needed, and unsetting it later disables analytics on the next api boot. The outer Caddy already proxies /analytics/* to PostHog EU, so no other configuration is required.

In-stack S3 backend (Garage)

See In-stack S3 backend (Garage) — full guide: when to use it, generating secrets, activating the profile, verification, credential rotation, restoring, and troubleshooting.

Operations

Persistent data

All persistent state lives under ./data/ next to the compose file. Docker auto-creates these dirs on first up; the postgres / rabbitmq / redis entrypoints chown them to the right uid on first boot, so no manual setup is required. Files end up owned by the uid each container runs as (postgres=999, redis=999, rabbitmq=100, caddy=root), so sudo is usually needed for host-side tar / rsync.

• Directorydata/

  • Directorypostgres/

    • …
  • Directoryrabbitmq/

    • …
  • Directoryredis/

    • …
  • Directorycaddy/

    • …
  • Directorycaddy-config/

    • …

Backups

See Backups — automated S3 backup service, ad-hoc dumps, and restore procedures.

Updating

See Updating — release-channel selection, manual upgrade, and the systemd auto-update timer.

Troubleshooting

Certs not issuing / TLS errors

Check that port 80 is reachable from the public internet (ACME HTTP challenge). docker compose logs caddy will show the ACME flow. If you’re rate-limited, fix the DNS before restarting — Let’s Encrypt caps at 5 failed attempts per hour.

Sign-in doesn't stick; redirects back to login

Sancho’s session cookies are SameSite=Strict; Secure; HttpOnly — they require HTTPS. Confirm https://<DEPLOY_HOSTNAME> works and the cert is valid.

Google OAuth loops back to sign-in

The callback URL registered in Google Cloud must match exactly: https://<DEPLOY_HOSTNAME>/api/login/google/callback. Mismatches redirect with an error.

Nextcloud OIDC returns 500 on first click

Discovery is lazy — the first click reaches <Nextcloud URL>/.well-known/openid-configuration (the URL from the configuration in Account → Configuration). docker compose logs api | grep -i "Failed to discover Nextcloud OIDC" will show the underlying fetch error. Common causes: the OIDC app is not enabled on the Nextcloud, the configured URL points at a host the api container cannot resolve (network policy / split-DNS), or the discovery URL returns HTML (the login page was entered rather than the base URL). The api retries discovery on the next click — no restart needed.

Nextcloud OIDC callback: 'Missing OIDC flow cookie'

The signed nc_oidc_flow cookie is scoped to /api/login/nextcloud-oidc with SameSite=Lax and a 10-minute lifetime. Causes: the user opened the consent screen and waited >10 min, the browser blocks third-party cookies aggressively (rare for top-level navigation), or the user reached /callback directly without going through /login/nextcloud-oidc first. Restart the flow.

Nextcloud sign-in fails before redirecting

The Nextcloud OAuth/OIDC start URL requires login_hint. Sancho adds it after the /api/auth/lookup email step, so direct links to /api/login/nextcloud... without login_hint are intentionally rejected. Restart from /sign-in and enter the user’s email.

Nextcloud OIDC callback: 'different provider id'

Both Nextcloud paths (built-in OAuth and OIDC) are configured, the user previously signed in via one path, and the other path’s sub (or OCS user id) doesn’t match the stored providerId for the same email. Pick one provider and remove the other’s configuration in Account → Configuration — the change applies without an api restart.

OAuth redirects to /sign-in?error=signup_disabled

The user’s email domain doesn’t match the account’s allowed-domains list. Add the domain in Account → Configuration → Allowed email domains (applies immediately, no api restart), or have the root admin invite the user from the in-app members page.

Registration fails on avatar / image upload

The api’s CreateBucket call failed silently on first boot. docker compose logs api | grep -iE 'createbucket|s3' will show whether the call was denied (key lacked permission) or never reached the endpoint (S3_ENDPOINT mismatch). For external S3 with a least-privilege key: pre-create sancho-env-${DEPLOY_ENV} and sancho-env-${DEPLOY_ENV}-account-1 (default DEPLOY_ENV=prod) and ensure the key has object-level access. For the in-stack Garage profile: check that S3_API_KEY / S3_API_SECRET were set in .env before the first docker compose up -d (Garage auto-creates the access key from those env vars only on first boot).

Password reset email never arrives

Check docker compose logs api | grep -i mail. Common causes: on SMTP — wrong host / port, missing SMTP_PASSWORD, or the relay rejecting the connection; on Cloudflare Email Send — sender domain not verified / DKIM missing, or an API token without Email Routing: Send permission. If both transports are configured, Cloudflare wins and SMTP is ignored — blank out the Cloudflare variables to fall back to SMTP.

'No space left on device' after a while

Old image layers accumulate. docker image prune -a cleans up; consider a cron job.

docker compose pull fails with 'unauthorized' / 'denied'

The GHCR images are private — the user running the command isn’t logged in, or the token Sancho issued has been rotated / revoked. Re-run the login step in Registry login; if the token is stale, ask Sancho for a new one. If the systemd timer is firing the failure, make sure root is the user that ran docker login ghcr.io (its credentials live in /root/.docker/config.json).

Security notes

• .env must be chmod 600 and owned by the user that runs docker compose. See Secure file permissions.
• Change every default password in .env (Postgres, RabbitMQ, root user).
• Only expose ports 80 and 443 on your firewall. Postgres, RabbitMQ, Redis, and the api are reachable only within the compose network.
• RabbitMQ’s management UI (port 15672) is not exposed by the compose file. If you need it, add a handler in the Caddyfile with basic_auth.
• Rotating ROOT_PASSWORD in .env only changes the seed for fresh installs — for an existing deployment, change it via the in-app password change UI as the root user. The value must stay set in .env even after rotation, because the api re-validates config on every restart.
• Rotating API_SESSION_SECRET or API_COOKIE_SECRET invalidates every active session — users will be signed out.
• Rotating PG_PASSWORD / RABBITMQ_ADMIN_PASSWORD must happen first inside the database / broker, then in .env, then docker compose up -d. Rotating only .env will leave the api unable to authenticate.
• Back up ./data/caddy; losing the ACME account key can delay re-issuance of certificates.