Documentation for v2.10.0. Read the latest, v2.12.0.

Operator

Deployment

Sanshain is one binary, one database and one port. This chapter is how to run it: the image, Docker and Compose for a single host, Kustomize or the Helm chart for Kubernetes, the choice between SQLite and PostgreSQL, and what an upgrade does.

The image#

ghcr.io/paxel/sanshain-service:<tag>, built by the release workflow from the repository's Dockerfile. Release tags carry a v (v2.6.0); latest follows the newest release. The image is Alpine with sqlite-libs, tini as PID 1 and ca-certificates; the binary is /usr/local/bin/sanshain, the working directory /app, the static files /app/static. It sets one variable: DATABASE_URL=sqlite:/data/sanshain.db?mode=rwc, so the database lives under /data. It exposes port 3000 and declares a Docker HEALTHCHECK on GET /health. The Kubernetes manifests run it as UID 1000; the image itself does not switch user.

On every start the service runs its SQL migrations, creates the initial admin when the user table is empty (Getting started), claims the configured root names, and logs the instance id. A failed migration is fatal: the container exits with ERROR: Can't run SQLite migrations: … (or PostgreSQL) on stderr.

Docker and Compose#

docker run -p 3000:3000 -v sanshain-data:/data ghcr.io/paxel/sanshain-service:v2.6.0

docker-compose.release.template.yaml in the repository is the same as a Compose service: the volume on /data, init: true, restart: unless-stopped, and RUST_LOG=sanshain_service=info,tower_http=info. Replace __VERSION__ with the tag. For PostgreSQL add DATABASE_URL to its environment and drop the volume:

services:
  sanshain:
    image: ghcr.io/paxel/sanshain-service:v2.6.0
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=postgres://user:pass@db:5432/sanshain
    init: true
    restart: unless-stopped

Every setting is an environment variable; the complete list is Configuration.

Kubernetes with Kustomize#

deploy/kubernetes holds base manifests for kubectl apply -k:

kubectl create namespace sanshain
echo -n "postgres://user:pass@db:5432/sanshain" | base64   # into secret.yaml
kubectl apply -k deploy/kubernetes -n sanshain

The Helm chart#

deploy/helm/sanshain, chart version 2.10.0, appVersion 2.10.0. The image tag defaults to v plus the appVersion.

helm install sanshain deploy/helm/sanshain -n sanshain --create-namespace

With the default values the pod gets SQLite on the data volume and a random initial admin password in the log: the Secret renders DATABASE_URL and INITIAL_ADMIN_PASSWORD only when the value is non-empty, and the service treats an empty value as unset. To choose the password:

# my-values.yaml
secrets:
  databaseUrl: "sqlite:/data/sanshain.db?mode=rwc"
  initialAdminPassword: "…"

With an external PostgreSQL:

# my-values.yaml
persistence:
  enabled: false
secrets:
  databaseUrl: "postgres://user:password@postgres-host:5432/sanshain"
  initialAdminPassword: "…"

helm install sanshain deploy/helm/sanshain -f my-values.yaml -n sanshain

The values that matter, with their defaults:

The chart's deployment uses /health for both the liveness and the readiness probe; the Kustomize deployment uses /ready for readiness. If you want traffic withheld while the database is unreachable, point the chart's readiness probe at /ready with a post-renderer or a fork of the template. tests/helm_render_test.rs renders the chart in CI, so the values above are checked against the templates on every build.

The ConfigMap template renders the config.* keys above and the Secret the two secrets.* keys. Every other variable the service reads (PUBLIC_BASE_URL, SANSHAIN_ROOT_USERS, the OTEL_*, MCP_* and WEBHOOK_* settings, CACHE_MEMORY_MB, LOG_FORMAT, LDAP_OPERATION_TIMEOUT_SECS, …) goes into extraEnv, which is appended to the container's env as given, so a valueFrom reference to your own Secret works too:

# my-values.yaml
extraEnv:
  - name: PUBLIC_BASE_URL
    value: https://sanshain.corp
  - name: SANSHAIN_ROOT_USERS
    value: root,breakglass
  - name: OTEL_EXPORTER_OTLP_HEADERS
    valueFrom:
      secretKeyRef:
        name: otel-headers
        key: headers

helm uninstall sanshain -n sanshain

SQLite or PostgreSQL#

The backend is chosen from DATABASE_URL: postgres:// or postgresql:// selects PostgreSQL, anything else (or the variable unset) is SQLite. Nothing else differs in configuration; both run the same migrations.

• SQLite opens the file in WAL mode with synchronous=NORMAL, a pool of MAX_SQLITE_CONNECTIONS (5) and a busy timeout of SQLITE_BUSY_TIMEOUT_MS (5000). Writers queue on the busy timeout. Keep the file on a volume that only one process mounts.
• PostgreSQL uses a pool of MAX_POSTGRES_CONNECTIONS (20). Choose it for durability and for backups with the database's own tooling; it does not let Sanshain run more than one instance (see Scaling).

The admin page shows the backend and the connection URL with the password removed (Database Configuration); switching means changing the variable and restarting. There is no migration between the two engines.

Scaling#

Sanshain runs as exactly one instance, on SQLite and on PostgreSQL alike. The Helm chart and the Kustomize manifests render a StatefulSet with one replica; the chart refuses to render when replicaCount or autoscaling is set, because both were removed in 2.10.0.

The reason is in the process, not the database. Each instance keeps its own in-memory caches (CACHE_MEMORY_MB), and a write clears only the caches of the instance that handled it; a second instance would answer from its own cache for up to 10 seconds. Live updates in the web UI reach only the browsers connected to the instance that took the upload, and the cleanup job runs in every instance. Running several instances needs that state shared first; until then, give the one pod more resources instead of more replicas.

A StatefulSet stops the old pod before it starts the new one, so on an upgrade two processes never hold the data volume at once. The data claim keeps its name (<release>-data, or sanshain-data with Kustomize), so an installation that ran as a Deployment keeps its data: on the upgrade to 2.10.0 the Deployment is deleted and the StatefulSet starts on the same claim, with one restart.

Health, readiness and version#

All three are unauthenticated. Metrics are in Observability.

Upgrades and migrations#

1. Take a backup (Backup and restore).
2. Read the changelog for the release; the "What changed" callout on each chapter of this track names what an operator configures.
3. Change the image tag and roll. The StatefulSet stops the old pod first; migrations run on the first start of the new version, before the listener binds.

Migrations are forward-only: a database touched by a newer version cannot be used by an older binary. Rolling back means restoring the backup from before the upgrade. Since 2.4.0 the start also rewrites, once, every stored spec text whose line endings or BOM predate ADR-0008; like a migration it is fatal on failure (ERROR: Can't normalize stored spec text); success is recorded in a setting, a failed run is repeated on the next start. Environment changes need a restart; certificates under EXTRA_CA_CERTS_DIR are read once at startup.

Security#

• Both deployments run the container as UID 1000 with runAsNonRoot: true and fsGroup: 1000 (Helm: podSecurityContext, securityContext, also applied to the backup job). Neither sets readOnlyRootFilesystem or drops capabilities; add them in your own overlay if your policy requires them, the service writes only under DATABASE_URL's directory.
• TLS terminates at the Ingress: the Kustomize ingress.yaml references the sanshain-tls Secret, the chart's ingress.tls list takes yours. The service itself speaks plain HTTP on port 3000, so the session cookie and the API tokens must not cross the cluster boundary unencrypted.
• /metrics, /health, /ready, /version and the free validator POST /validate are unauthenticated; restrict /metrics at the ingress when the instance is public.
• The Secret holds the database URL with its password and the initial admin password; the database holds the LDAP bind password, the OIDC client secret and the webhook secrets (Backup and restore).

Outbound TLS trust#

LDAPS connections verify the directory's certificate against the platform bundle plus, when set, every certificate under EXTRA_CA_CERTS_DIR. Mount the corporate CA (extraVolumes/extraVolumeMounts in Helm, the commented ca-certs volume in Kustomize) and point the variable at the mount path. Details and the startup failures are in Configuration.

Verifying a release#

The release workflow (.github/workflows/release.yml) produces three supply-chain artifacts for every tag:

• The image is signed keyless with cosign through the workflow's GitHub OIDC identity on the public Sigstore instance; the certificate names the workflow.
• A CycloneDX SBOM of the image, attached to the image as a cosign attestation and to the GitHub release as sanshain-service-<tag>.cdx.json.
• A CycloneDX SBOM of the dependencies compiled into the binaries (from Cargo.lock and package-lock.json), on the release as sanshain-service-<tag>-source.cdx.json.

Verify the signature (the tag or the @sha256:… digest you deploy):

cosign verify ghcr.io/paxel/sanshain-service:v2.6.0 \
  --certificate-identity-regexp '^https://github.com/paxel/sanshain-service/.github/workflows/release.yml@refs/tags/' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

Verify the SBOM attestation the same way; the attested SBOM is the predicate of the printed in-toto statement, so this also extracts it without the GitHub release:

cosign verify-attestation --type cyclonedx ghcr.io/paxel/sanshain-service:v2.6.0 \
  --certificate-identity-regexp '^https://github.com/paxel/sanshain-service/.github/workflows/release.yml@refs/tags/' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  | jq -r .payload | base64 -d | jq .predicate > sanshain-service.cdx.json

A signature whose certificate names any other identity or issuer fails, so an admission policy can require exactly this one. Only a release built from a pushed tag verifies with the regexp above: a run started by hand through workflow_dispatch is signed with @refs/heads/<branch> instead.

The weekly security workflow (.github/workflows/security.yml, Mondays 05:17 UTC) scans the latest released image with grype. It fails only on high or critical findings that have a fix, and attaches two reports as workflow artifacts: the fixable findings and the full list.

Checked against v2.6.1.