Skip to Content
Deploy

Deploy

The server image valontechnologies/gestaltd:latest is published for linux/amd64, linux/arm64, and linux/arm/v7. An Alpine variant is available as :latest-alpine. For the CLI client image, see Client Docker Image.

Production considerations

Database. SQLite works for single-instance deployments. For multi-replica or horizontally scaled deployments, use a networked datastore provider such as the first-party indexeddb/relationaldb, indexeddb/dynamodb, or indexeddb/mongodb packages. See IndexedDB for the provider model.

Secrets. Use file or a cloud secret manager instead of env in production. file is built in and works with Kubernetes volume-mounted secrets. Cloud backends (Google Secret Manager, AWS Secrets Manager, HashiCorp Vault, Azure Key Vault) are available as external providers from gestalt-providers. Gestalt config supports structured secret refs that are resolved at boot time through the configured secrets provider. See Secrets Providers for setup details.

TLS. Gestalt does not terminate TLS. Deploy behind a reverse proxy or load balancer that handles TLS termination. Set server.baseUrl to the public HTTPS URL so that OAuth callback URLs are derived correctly.

Startup workflows. gestaltd serve resolves providers on first boot and is suitable for development and single-instance deployments. For deterministic, reproducible deployments, split startup into two phases:

  1. Prepare — run gestaltd init locally (or in CI) to resolve every provider and write a lock file.
  2. Serve — run gestaltd serve --locked in production. The server reads the lock file and refuses to start if any provider is missing or has drifted.

This guarantees that the image you test is byte-for-byte the image you deploy.

For production, strongly prefer gestaltd init plus gestaltd serve --locked. Without a lockfile, startup can resolve newly published provider artifacts or changed registry metadata, which weakens reproducibility and integrity checks. Lockfiles pin the resolved artifacts and verified hashes that the deployment was tested with.

Prepared state and lockfiles. gestaltd init writes a deploy/ directory next to your config file:

deploy/
  gestalt.lock.json    # pinned provider refs and checksums
  .gestaltd/providers/ # vendored provider artifacts (optional)
  .gestaltd/ui/        # vendored UI assets (optional)

The lock file is a JSON document that records resolved plugins and host-scoped providers in separate maps:

{
  "version": 1,
  "indexeddbs": {
    "main": {
      "fingerprint": "ab12cd...",
      "source": "github.com/valon-technologies/gestalt-providers/indexeddb/relationaldb",
      "version": "0.0.1-alpha.1",
      "manifest": ".gestaltd/providers/main/manifest.json",
      "executable": ".gestaltd/providers/main/artifacts/linux/amd64/provider"
    }
  }
}

You can choose between two patterns:

  • Vendored — commit the full deploy/ directory (including providers/). The server loads artifacts directly with no network calls at boot. Best for air-gapped or latency-sensitive environments.
  • Lockfile-only — commit only gestalt.lock.json. The server fetches providers on first boot but verifies each artifact against the recorded checksum. Keeps your repo lightweight while still guaranteeing integrity.

See Configuration for the config model and Docker for the recommended production image pattern.

Deployment guides

See Docker for Docker and Docker Compose, or Helm for Kubernetes with the published Helm chart.

Gestalt runs on any container platform that supports a Docker image on port 8080 with environment variables. Use the Docker guide as the base for any of these:

Audit LoggingDocker