> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spitzli.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Operate a Core installation

> Review native deployment artifacts, restricted roles and retained-state requirements.

> [!NOTE]
>
> This is an operator guide for the matching source revision. It is not a customer database order flow: shared and self-hosted PostgreSQL products are maintenance-only; new database connections use Neon BYOK.

Core is a standalone native backend. It can serve the built Console and account UI, or use separately configured frontends, on their exact canonical hosts. It needs external PostgreSQL, verified database TLS, canonical HTTPS origins and private runtime configuration. Managed product workloads use the existing Kubernetes cluster; local Docker is an isolated test backend.

## Build and configure

Build from the matching source revision:

```sh theme={null}
bun install --frozen-lockfile
bun run quality
bun run test:distribution
docker build -f deploy/docker/Dockerfile --target core -t webdock-core:local .
docker build -f deploy/docker/Dockerfile --target migrate -t webdock-migrate:local .
```

Use the variable names in `crates/control-plane/.env.example`. Supply private restricted-role database credentials, the existing identity/RLS keys and exact Auth, Console and Studio protocol origins through the runtime environment. Never put offline migration credentials into Core. Configure ingress to preserve those canonical hosts and terminate HTTPS.

For an isolated single-host installation, `deploy/compose/compose.yaml` runs only Core. Supply a reviewed immutable image through `WEBDOCK_CORE_IMAGE` and a private `core.env` beside the Compose file. It binds to loopback port 3130; ingress is independently managed. `deploy/helm/webdock` contains the native Kubernetes deployment contract and requires a digest-pinned image, an existing private runtime Secret and `apiHost` matching the hostname and optional port of `WEBDOCK_API_ORIGIN`. HTTP probes use that authority to pass Core's host boundary. Plugins and execution listeners need their own explicitly configured processes and private transports.

## Offline schema setup

Run `webdock-migrate` separately with `WEBDOCK_MIGRATION_DATABASE_URL` and an exact target:

```sh theme={null}
cargo run --locked -p webdock-control-plane --bin webdock-migrate -- --target db.example.invalid:5432/webdock
```

For a fresh empty database, the reviewed CLI supports `--initialize-empty` and explicit role provisioning from a private file. Consult `crates/control-plane/README.md`; initialization refuses existing platform state. For a containerized migration, use the separate `deploy/compose/compose.migration.yaml`, a private `migrator.env`, `WEBDOCK_MIGRATE_IMAGE` and `WEBDOCK_MIGRATION_TARGET`. Starting Core never starts this migration service.

Continue with [initial operator setup](https://docs.spitzli.cloud/developers/initial-setup.md). Preserve retained identifiers, signing material, Mail encryption keys and volumes when adopting an existing installation.

## Rollout acceptance

Before rollout, verify backups and restore, retained schema/history, exact ingress routing, authentication, private listener enrollment, enabled products and rollback after new writes. Stop the old writers before transferring ownership. The repository's local checks do not establish these production properties. Check the current product-specific release gates; older migration inventories are not a current rollout guarantee.

Source: runtime configuration (`crates/control-plane/.env.example`), [Compose](https://github.com/spitzli/cloud/tree/main/deploy/compose) and [Core Helm chart](https://github.com/spitzli/cloud/tree/main/deploy/helm/webdock). Hosted authentication uses [Neon Managed Auth and Core security](https://docs.spitzli.cloud/developers/auth-adapters.md); a local bootstrap account is not a substitute for a production managed-identity binding.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.