System requirements

OTB Works runs as one container with a SQLite database on a volume. There is no separate database server, message broker or cloud dependency.

Host

A Linux host with Docker. Nothing else needs to be installed on it.
An amd64 (x86-64) host. The release image is built for linux/amd64 only. No other architecture is published.
Somewhere for the data to live. A single Docker volume or directory is enough.
A hostname people will use to reach the instance, and a decision about TLS (see below).

Docker. The container requires a Docker Engine of 20.10 or later; the compose file also needs Compose v2 (docker compose). That is a floor taken from the features the image and compose file use, not a version OTB tests. OTB’s release builds and checks are run with Docker 29.1.3, and the installation procedure has been followed on Docker 29.6.1.

Image size. The 1.0.4 image pulls as about 540 MB compressed and takes about 1.3 GB on disk. Expect 1.0.5 to be close to that. Check the exact figure with docker image ls after the pull.

Browsers

Works is a web application that people use in a current desktop or mobile browser. The client is built to a baseline of Chrome 111, Edge 111, Firefox 114 and Safari 16.4 (including iOS 16.4). A browser older than that may fail to load the application.

The automated journey tests run in Chromium only (a desktop profile and a phone profile).

Firefox and Safari on current versions are expected to work, and nothing in the build excludes them, but they are not part of the automated testing.

Ports

Port	Used for
`4173`	The application. In TLS mode `off` it listens on all interfaces for your own proxy. In `auto` and `internal` it listens on `127.0.0.1` only, so it is not reachable from outside the container.
`80`	Certificate challenge, in TLS mode `auto`. Publish it as well as 443.
`443`	HTTPS, in TLS modes `auto` and `internal`.

TLS modes

An instance that other people reach must use HTTPS. Sign-in uses a Secure cookie, and a browser discards it over plain HTTP to anything but localhost. The server refuses to start on a plain http:// address that is not localhost.

Set OTB_WORKS_TLS to one of:

Value	Use when	Needs
`auto`	The server is reachable from the internet and DNS for your hostname points at it.	A name in `OTB_PUBLIC_URL` that resolves in public DNS. Ports 80 and 443 reachable from the internet. A certificate is obtained automatically.
`internal`	A LAN-only deployment with no public DNS.	Nothing external. The certificate comes from the container’s own certificate authority, so you must install its root certificate on every machine that connects. The boot log gives the path.
`off`	Something you already run terminates TLS (a proxy, load balancer or tunnel).	A proxy in front. Set `OTB_TRUSTED_PROXIES` so the instance can tell clients apart.

If you leave OTB_WORKS_TLS unset, it is chosen for you and the boot log states which mode and why. Setting OTB_TRUSTED_PROXIES implies off.

Keep the data volume in auto mode. The certificate store lives on it.

Environment variables

Required

Variable	Meaning
`OTB_PUBLIC_URL`	The address people type in their browser, with scheme and any port, and no trailing slash. Invitation links, password resets and single sign-on redirects are built from it. The server will not start without it.
`OTB_SESSION_SECRET`	Signs sign-in cookies. Generate once with `openssl rand -hex 32`. It has no default. Changing it signs everyone out.

Optional

Variable	Meaning
`OTB_WORKS_TLS`	`auto`, `internal` or `off`, as above.
`OTB_WORKS_TLS_EMAIL`	`auto` only. Where Let’s Encrypt writes about expiring certificates.
`OTB_TRUSTED_PROXIES`	Which upstream hops to believe about who the client is. Unset means nothing is trusted. In `auto` and `internal` the proxy inside the container is trusted automatically.
`OTB_NOTIFICATIONS_ENC_KEY`, `OTB_INTEGRATIONS_ENC_KEY`, `OTB_ADVISOR_ENC_KEY`, `OTB_SSO_ENC_KEY`	Encrypt stored email, tracker, Advisor and single sign-on credentials. Optional: the instance generates its own on first boot and keeps them in `instance-keys.json` on the data volume. A value you set wins.
`OTB_APP_NAME`	What an authenticator shows when enrolling a passkey. Defaults to “OTB Works”.
`OTB_UPDATE_FEED_URL`	Where the update check looks, if switched on. Defaults to OTB’s own feed.
`OTB_UPDATE_FEED_INTERVAL_MS`	How often to check, once on. Defaults to six hours.
`OTB_SSO_TRUSTED_IDP_ORIGINS`	Comma-separated origins of an identity provider on a private network. Empty by default.
`OTB_SEED_ADMIN_EMAIL`, `OTB_SEED_ADMIN_PASSWORD`	Create the first administrator on first boot without a browser. The password is at least 12 characters and must be changed at first sign-in.
`TZ`	Time zone. The sample compose file sets `Europe/London`.

Other variables exist for development and testing. The ones above are the ones a deployment sets.

Data directory and backup

All state lives in one directory, /app/packages/server/data in the container (set by OTB_DATA_DIR). Mount a volume there.

It holds:

app.db: the product’s data, including the instance ID and licence state.
sessions.db: sign-in sessions only. Losing it signs everyone out.
instance-keys.json: the at-rest encryption keys the instance generated.
evidence/: encrypted evidence files.
The TLS certificate store, in auto and internal modes.

To back up, copy the whole directory. A backup of app.db alone is incomplete: without instance-keys.json the stored credentials cannot be decrypted, and without evidence/ the evidence files are lost. SQLite runs in WAL mode, so stop the container first, or use SQLite’s own backup command on the live file.

Back up your .env or equivalent separately. It holds OTB_SESSION_SECRET, and any *_ENC_KEY you set yourself is never written to the data volume.

A restored backup is the same deployment and keeps its licence.

Outbound network

OTB Works needs no outbound access to run. These connections are optional:

Connection	When
OTB’s public release feed	Only if an administrator switches on the update check. Off by default. The request is an anonymous HTTPS GET. It carries no instance ID, licence ID or customer name.
Your email provider	When you configure email.
Jira or Azure DevOps	When you connect a tracker.
Let’s Encrypt	TLS mode `auto` only.
Your identity provider	When you configure single sign-on.
A model endpoint you supply	Only if you use the Advisor add-on.

Licences are verified offline. The instance never contacts OTB to check one.

For an air-gapped site, OTB supplies the image as a .tar that you load with docker load.

Email providers

Four settings exist for the email provider: none, SMTP, Amazon SES and Azure Communication Services. Without a provider, invitations, password resets and sign-in links cannot be sent.