Deployment and release
SteamHarness Server runs locally or as a self-hosted service. Production deployments should put the database, runtime data, object storage, and static documentation in explicit persistent locations.
Environments
| Environment | Use | Guidance |
|---|---|---|
| Development | Local Server development | Copy Server deployment variables from *.env.example to a local .env; enter business values in Project configurations. Git ignores real env files. |
| Production | Administration, project, and data APIs | Use protected CI/CD Variables or a .env.production that exists only on the deployment host. |
Start Server for development:
pnpm bootstrap
pnpm dev
Build and start a production checkout:
pnpm install --frozen-lockfile
pnpm build:all
pnpm start
Never commit real .env files, database connection strings, or service keys. *.env.example files contain variable names and placeholders only.
Persistent configuration
Prepare backups and write access for at least:
| Variable | Purpose |
|---|---|
STEAMHARNESS_SERVER_DATA_DIR | Server runtime data, caches, and local object storage. |
STEAMHARNESS_DATABASE_URL | PostgreSQL connection string. |
STEAMHARNESS_SERVER_DATABASE_POOL_MAX | Maximum connections per pool; a positive integer. Unset uses the driver default. Budget all pools across processes sharing a database. |
STEAMHARNESS_SERVER_HOST | Listen address. Set 127.0.0.1 behind a reverse proxy; unset preserves the default binding. |
STEAMHARNESS_STORAGE_DRIVER | Object storage backend; only local is accepted, writing artifacts and avatars to this machine's disk. |
STEAMHARNESS_LOCAL_STORAGE_ROOT | Absolute path used by the local driver. |
STEAMHARNESS_PUBLIC_BASE_URL | Public administration URL. |
STEAMHARNESS_API_PUBLIC_BASE_URL | Public HTTP(S) origin for the API. |
STEAMHARNESS_DOCS_PUBLIC_BASE_URL | Documentation site URL. |
Server never installs dependencies, builds, or loads uploaded project code. Back up source snapshots, avatars, KV data, and knowledge data according to the deployment policy.
Administrator names and shared accounts
The bootstrap administrator's default display name is used only when creating the account. Later changes made through personal profiles or user management are stored in PostgreSQL and preserved during password login, bootstrap login, and session renewal. Profile name changes update both the authentication account and user profile; changing an email or password also preserves the saved name.
Server instances connected to the same STEAMHARNESS_DATABASE_URL share account profiles. When names differ, first check that the instances use the same database and account ID and that every instance has been updated. Older instances may write an outdated name during login.
Health checks and reverse proxy
Check a running service with:
curl -i "$STEAMHARNESS_PUBLIC_BASE_URL/health"
The reverse proxy should forward HTTPS, Host, and WebSocket headers and expose only required ports. If a health check fails, preserve data and inspect service logs and database connectivity before rollback or recovery.
Alpha and stable deployments
Alpha and stable use separate runtime directories, processes, logs, and ports. Use explicit artifacts and migration plans for both environments; database changes remain expand-only and must not delete or rename live fields from a deployment script.
Release jobs read production variables only from protected refs and verify build versions and static assets. Recovery does not remove data volumes, commit runtime configuration, or place secrets in artifacts.
The deployment.server and deployment.serverWeb health records may include a separate deploymentId. Use it with commitSha to distinguish deployments of the same product version. currentRelease.docsUrl links to localized deployment notes; older metadata keeps version-based links.