Docker & Helm

The official image ghcr.io/tabularisdb/tabularis runs Tabularis Web on a server. It is published to the GitHub Container Registry for linux/amd64 and linux/arm64, tagged latest, with the minor version (for example 0.30) and with the exact version (0.30.0). Prereleases only get their exact version tag.

The image is based on Debian slim, so registry driver plugins run unchanged, and it weighs about 60 MB. It runs as UID 10001, keeps all state in /data, and includes ssh for SSH tunnels. kubectl and the AWS CLI are not included: extend the image if you use Kubernetes or AWS SSM tunnels.

It is a server-only build with no desktop app: it only runs tabularis web and tabularis --mcp.

Quick Start With Docker

docker run -d --name tabularis \
  -p 127.0.0.1:8080:8080 \
  -v tabularis-data:/data \
  ghcr.io/tabularisdb/tabularis
docker logs tabularis   # prints the generated login password

Open http://localhost:8080 and sign in with the password from the log.

Publishing the port on 127.0.0.1 matters. Plain HTTP is only accepted when the public URL is localhost, 127.0.0.0/8 or [::1], and the server rejects any other Host header. To use another host port, publish it and tell the server which URL the browser uses:

docker run -d -p 127.0.0.1:9000:8080 -e TABULARIS_PUBLIC_URL=http://localhost:9000 \
  -v tabularis-data:/data ghcr.io/tabularisdb/tabularis

Docker Compose

docker/compose.yaml runs the same local setup:

curl -fsSLO https://raw.githubusercontent.com/TabularisDB/tabularis/main/docker/compose.yaml
docker compose up -d

For a public deployment over HTTPS, docker/compose.tls.yaml adds Caddy with automatic certificates. From the docker folder of the repository:

cp .env.example .env          # set TABULARIS_DOMAIN, a password and a secret key
docker compose -f compose.yaml -f compose.tls.yaml up -d

Caddy keeps the original Host header and upgrades WebSockets, which Tabularis requires. Any other reverse proxy must do the same; see Remote Access & Reverse Proxy.

Kubernetes With Helm

helm install tabularis oci://ghcr.io/tabularisdb/charts/tabularis \
  --set publicUrl=https://tabularis.example.com \
  --set ingress.enabled=true --set ingress.className=nginx
  • The chart runs one replica with a Recreate strategy, because sessions and the data volume belong to a single process.
  • Values you set (auth.password, auth.proxySecret, secretStore.key) go into a Secret mounted as files. A missing login password or secret-store key is generated by the container on the data volume, as with plain Docker, so the chart renders the same output every time and works with GitOps tools based on helm template, such as Argo CD and Flux.
  • Proxy authentication needs auth.proxySecret, because the proxy must send the same value.
  • auth.existingSecret uses your own Secret, with the keys web-password or proxy-secret, and secret-key.
  • The pod runs read-only as non-root, and its probes send the public Host header.

Every option is listed in charts/tabularis/values.yaml.

Environment Variables

The image's entrypoint turns these variables into tabularis web options. Arguments after the image name are appended, so docker run ghcr.io/tabularisdb/tabularis --debug works, and any other command (for example sh) runs instead of the server.

Variable Default Meaning
TABULARIS_PUBLIC_URL http://localhost:8080 URL the browser uses: HTTPS, or HTTP on a loopback host. Also the first allowed origin.
TABULARIS_TRUSTED_PROXIES Trusted proxy source CIDRs, comma separated. Forwarded headers are ignored by default. Helm: trustedProxies.
TABULARIS_ALLOWED_ORIGINS Further allowed origins, comma separated.
TABULARIS_AUTH password password, or proxy behind an authenticating reverse proxy.
TABULARIS_WEB_PASSWORD generated Login password, at least 12 characters. When unset, one is generated on first start, stored in /data/web-password and printed once.
TABULARIS_WEB_PROXY_SECRET Required in proxy mode, at least 32 characters.
TABULARIS_SECRET_KEY generated Encrypts stored credentials, at least 16 characters. See below.
TABULARIS_ALLOW_HIGH_RISK false Grants every session host-level operations. Only for a single trusted user.
TABULARIS_SERVER_FILE_ROOTS Server directories the browser may pick files from, comma separated.
TABULARIS_PORT 8080 Port inside the container.
TABULARIS_HOST 0.0.0.0 Bind address inside the container.
TABULARIS_DEBUG false Debug logging.

TABULARIS_WEB_PASSWORD, TABULARIS_WEB_PROXY_SECRET and TABULARIS_SECRET_KEY also accept a _FILE variant that points at a Docker or Kubernetes secret file.

Stored Credentials

Containers have no OS keychain. The image sets TABULARIS_SECRET_STORE=file, which keeps every secret the desktop app would put in the keychain (database and SSH passwords, connection URIs, plugin secrets, AI keys) in /data/secrets.enc.json, encrypted with AES-256-GCM under a key derived from TABULARIS_SECRET_KEY with Argon2id.

Without TABULARIS_SECRET_KEY, a random key is generated in /data/secrets.key. Secrets then survive restarts and upgrades, but anyone who can read the volume can read them.

In production, set your own TABULARIS_SECRET_KEY and back it up separately from the volume. A lost key makes the stored credentials unrecoverable, and a wrong key stops the container at startup instead of silently starting empty.

The same file store works outside containers; see Security & Credentials.

Health, Logs and Shutdown

  • GET /healthz is a liveness check. It still enforces the Host allowlist, so the image's HEALTHCHECK sends the public host. It does not prove that authentication, databases, plugins or WebSockets work.
  • Logs go to stderr (docker logs). Security events use the tabularis::web_audit target and never contain passwords, SQL text or results.
  • docker stop sends SIGTERM: the server finishes its requests, closes pools and tunnels, and stops driver plugins before exiting.

Upgrading

Pull the new image and recreate the container with the same volume and environment. The image ships the matching browser UI, so never mix a server and a UI from different releases. See Updates for the checklist and rollback.

Building the Image Yourself

From a clone of the repository:

docker build -f docker/Dockerfile -t tabularis .
docker/smoke-test.sh tabularis