Deploy with Towbar

Run PostgreSQL, the API and the web app on your own server.

Run Vitalog as three workloads: PostgreSQL, the Hono API and the Next.js web app. The checked-in Towbar environment, datastore, API and web manifests show the architecture. They contain deployment-specific server IDs and domains: customize them for your workspace before syncing. The origins below are this installation’s planned hosts; DNS and deployment must be verified separately.

Prepare your workspace

Connect your fork or checkout to Towbar and select a server you control. Replace the server references, service domains and any workspace-specific IDs in the manifests. Keep the API and UI on separate HTTPS origins. This installation uses https://vitalog-api.praveent.com and https://vitalog.praveent.com. Keep PostgreSQL on the private workload network.

The API and web manifests use deployment.type: image with versioned images from ghcr.io/avgeek-oss/vitalog-api and ghcr.io/avgeek-oss/vitalog-web. Towbar pulls the published images; it does not build the source on your server. The checked-in v1.0.3 references are candidates pending publication. Before syncing or deploying, replace each tag-only reference with the verified immutable SHA-256 digest from the published v1.0.3 release; keep API and web on the same release version. Runtime resources remain bounded independently of PostgreSQL.

Both services use a recreate rollout with a maintenance window. Towbar stops the previous container before starting its replacement, so upgrades do not require an extra CPU reservation for an overlapping candidate. The service is briefly unavailable while its replacement starts and passes readiness checks. On a host with enough spare CPU and memory, the stateless web service can instead use a rolling rollout.

The release workflow builds and tests linux/amd64 and linux/arm64 images. Select the platform matching your server; the production manifests use ARM64. The Dockerfiles remain in the repository for CI publication and local development.

Publish a release

Update the API and web package versions together, regenerate the documentation, and merge after CI passes. Create an immutable vX.Y.Z tag at that exact main commit, then dispatch Publish release images from main with the tag as release_tag. The workflow validates the tag and versions, reuses the CI verification, builds each architecture natively, assembles multi-platform images, and checks public pulls and OCI source metadata. It attaches vitalog-images.json to a draft release, tests those exact images against a disposable PostgreSQL installation on AMD64 and ARM64, and publishes only after both installation checks pass. No production credentials are required.

If a new GHCR package is private, make it public and rerun the failed manifest job. Draft release assembly can be retried; a published version cannot be republished. Download the image references from the release’s vitalog-images.json asset when promoting it to an installation.

Choose a release

Publish and verify both images before updating the service manifests. Use the release tag plus its registry digest, for example ghcr.io/avgeek-oss/vitalog-api:vX.Y.Z@sha256:<published-digest>, and the corresponding web image from the same release. Do not use latest or overwrite a published release tag.

For upgrades, change both image references, sync the repository, then deploy the API before the web app. Runtime secrets and public origins remain installation settings. A new tag or image publication alone does not deploy a running installation.

Configure the API

Supply DATABASE_URL, AUTH_KEY, ROOT_EMAIL and ROOT_PASSWORD through Towbar runtime secrets. Bind the database URL to your private datastore hostname. Use independent, high-entropy credentials.

PUBLIC_BASE_URL=https://vitalog-api.praveent.com
UI_BASE_URL=https://vitalog.praveent.com

See configuration for client origins and optional private attachment storage. Declare enabled S3 variables in the API manifest’s runtime secret list.

Configure the web app

API_BASE_URL=https://vitalog-api.praveent.com
UI_BASE_URL=https://vitalog.praveent.com

The public documentation defaults to https://www.vitalog.dev. DOCS_BASE_URL can override it for your own docs fork. Add that optional name to the web manifest’s runtime secrets when setting an override. The browser sends credentialed requests directly to the public API origin.

The web app must not receive the primary key, root password or database credentials.

Deploy and verify

1. Sync your customized production environment and review the resulting workloads before deploying.
2. Deploy PostgreSQL and wait for it to become ready. Preserve its volume on later upgrades.
3. Deploy the API. Its startup command applies forward Drizzle migrations before serving requests; authenticated readiness checks validate the database and schema.
4. Deploy the web app. Configure TLS ingress and DNS for both public origins using your Towbar installation’s domain provider.
5. Check each deployment reaches terminal success. Test both /healthz routes, API OAuth discovery and the UI sign-in page through their public HTTPS origins.
6. Sign in, connect an MCP client and log a sample observation. Confirm it appears in Daily View, then verify key revocation rejects subsequent requests.

Take a tested PostgreSQL and attachment backup before upgrades. Deploy API and UI from the same release; rolling back code does not roll back migrations. Changing public API origins changes OAuth audiences and requires clients to reconnect. See operations.

Repository checks

npm run towbar:check
npm run test:container
npm run test:towbar
npm run test:build-budget

These checks validate manifests and disposable production containers, including private networking, migrations, REST/MCP access and resource-limited builds. Local checks do not prove your chosen server, DNS or client connection is working; verify the deployed installation separately.