Self-hosting
Deploy the team server and the remote task runner with docker compose or Helm, back them up, secure and upgrade them.
The team features of Oxys DB Studio run on two services you host yourself:
| Service | Program | API port | Metrics port (opt-in) | Holds |
|---|---|---|---|---|
| Team server | oxysdb-server | 8443 | 9464 | accounts, sessions, shared folders and items, invitations, Quick Shares |
| Remote task runner | oxysdb-runner | 8444 | 9465 | saved tasks, schedules, run history, connections with their passwords (encrypted) |
They are deployed and scaled separately. Everything needed is in the repository: container images
(deploy/docker/), docker compose files (deploy/compose/) and a Helm chart (deploy/helm/oxysdb/,
with the runner as a subchart).
Choose a topology
| Topology | Server store | Runner store | Replicas | For |
|---|---|---|---|---|
| Single node (default) | SQLite file on a volume | files in its data directory | 1 server, 1 runner | small teams, evaluation |
| HA, fully open source (recommended for production) | FerretDB 2 on PostgreSQL with DocumentDB | same deployment, own database | 2+ servers, 2+ runners | production without SSPL software |
| HA on MongoDB | a MongoDB replica set (operator, self-managed or Atlas) | same deployment, own database | 2+ servers, 2+ runners | teams that already run MongoDB; atomic multi-document requests |
| Dev/test replica set | plain MongoDB StatefulSet in the chart | same | any | CI and demos only |
A SQLite file or a runner data directory must never be shared by several processes: the chart refuses more than one replica in those modes.
Pages
- Deploy with docker compose
- Deploy on Kubernetes with Helm
- Set up TLS
- Accounts and day-to-day operations
- Back up and restore
- Upgrade
- Security checklist
Tenancy
The team server serves one organisation (many users, shared folders, access levels). The runner is single-tenant (one access token). Neither isolates customers from each other: run one deployment per tenant (its own namespace, release and database).
Container images
- Built from
deploy/docker/server.Dockerfile,deploy/docker/runner.Dockerfileanddeploy/docker/web-gateway.Dockerfile(the browser gateway with the page’s files), for linux/amd64 and linux/arm64.deploy/test/images-build.sh --arm64builds both and checks that each program starts in its arm64 container. - Distroless Debian 13 runtime (OpenSSL 3.5: post-quantum TLS to a MongoDB store that supports it),
user 65532 (non-root), no shell, works with a read-only root filesystem (writes
only to
/dataand/tmp). - A
HEALTHCHECKwith the program’s ownhealthcheckcommand (the gateway’s--health-check, with its health listener on127.0.0.1:9090). - Our code is MIT OR Apache-2.0. The MongoDB server is never bundled: compose and the chart only reference an image you pull yourself.
- Deploy with docker composeRun the team server (and the runner) on one host with the single, ha-mongodb or ha-ferretdb compose profile.
- Deploy on Kubernetes with HelmInstall the oxysdb Helm chart: database modes, key values, high availability, NetworkPolicies and the runner subchart.
- Set up TLSServe the team server and the runner over HTTPS: Caddy in compose, an Ingress, Gateway or the pod itself in Kubernetes.
- Accounts and day-to-day operationsCreate and administer team accounts, check health, read logs and metrics, and stop services gracefully.
- Back up and restoreWhat to back up for each store (SQLite, MongoDB, FerretDB/PostgreSQL, runner files) and how to restore safely.
- UpgradeUpgrade the team server and the runner without downtime, including the runner StatefulSet change and the one-time reseal.
- Security checklistWhat to check before putting the team server and the runner in production.
- Use Oxys DB Studio in a browserRun the web gateway on your machine and use the app in a browser: one WebSocket, every database connection made by the gateway.