Operational caveats a self-hosted deployment runs into. Each links to the deeper
platform page where it applies.
Reverse proxy in front
serve speaks plain HTTP on its published port and puts nothing in front of it —
terminate TLS at your own reverse proxy or load balancer and forward to that
port. The Studio and the /api surface share one origin, so there is nothing to
split.
Recreating a container gives it a new IP. A name-based reverse proxy that
resolves the upstream once at startup keeps forwarding to the old address after
an upgrade or restart and starts failing. Re-resolve on each request, or reload
the proxy when the stack is recreated. On the Compose network use the service
name (serve), not a captured IP.
CONNECTORS_REDIRECT_URI_ALLOWLIST. See TLS and the front
door.
Backups
The application state lives in Postgres and Redis, and in the two persistent
mounts (the config directory and the plugin prefix). Back up all of them.
- Datastores — snapshot the Postgres and Redis volumes on your own schedule;
the image holds no state.
- Stored platform state — the runtime exports its own state (access-control
policies, presets, and whatever else plugins register) as a backup document
with
tai backup export. See Back up and restore.
- Config — keep
config/manifest.yml and the plugin prefix, so a restored
server boots with the same manifest and the same runtime-installed plugins.
Schema migrations
tai db migrate applies every pending file across all components; tai db status
reports each component’s applied/pending/checksum verdict without changing
anything, and exits non-zero when any is out of date — so it doubles as a
pre-deploy gate:
Both commands connect through each component’s bound named
database and its admin
identity — TAI_DATABASE_<NAME>_PG_ADMIN_*, the DDL-privileged role, falling back
to that database’s runtime role when unset — distinct from the app’s runtime store
role. The chain model, the tai_schema_history
source of truth, the forward-only rule, and the checksum-immutability constraint
are the migrations contract.
Because recovery is a restore-and-re-migrate, never a rollback, snapshot the
database before any schema-carrying upgrade — see Back up and
restore.
Health probes
The server exposes unauthenticated /health (liveness) and /ready (every wired
store, pinged under a 5s budget) routes for orchestrators and load balancers —
served public by the app’s own route-level declaration, so no allowlisting. The
bundle’s serve healthcheck already probes /health. The full probe semantics are
Liveness and readiness.
Observability
tai metrics serves the Prometheus multiprocess endpoint on its own port and
reads the metrics directory the app process writes, so it runs beside that
process on the same filesystem — its own service on serve’s volume in the
Compose bundle, a sidecar container in the same pod on Kubernetes. Query traces
and aggregate metrics with tai obs. See Observe.
See also
- Deploy — transports, workers, access control at deploy.
- Manage a fleet — the worker census and fleet-wide operations.
