Skip to main content

Installation

Synth is a licensed self-hosted application. Customer deployments run from the official Synth container image or the official Synth Helm chart.

Choose A Deployment Path​

GoalUse
First single-VM proof of conceptDocker Compose POC kit
Repeatable team deploymentKubernetes with the official Helm chart
Configuration-as-CodeHelm values plus CaSc
Direct image smoke testOfficial Docker image with a persistent volume

What You Receive​

For a licensed evaluation or paid deployment, Synth provides:

  • a signed Synth license key;
  • access to the private Synth image registry;
  • a registry pull key or equivalent pull credentials;
  • a pinned official image reference or digest;
  • for Kubernetes, the official private Helm chart and a starter values file;
  • for Docker Compose POCs, a generated kit with values.env, docker-compose.yml, and customer-facing runbooks.

Keep registry keys, provider keys, Git tokens, cookies, and license keys out of tickets, screenshots, transcripts, and support bundles.

Requirements​

Docker Compose POC:

  • Docker Engine with the Docker Compose plugin;
  • an approved LLM provider key if this deployment will run model-assisted ingestion, linking, or lint;
  • the signed Synth license included in values.env or stored separately.

Kubernetes:

  • Kubernetes 1.25 or newer;
  • kubectl;
  • Helm 3;
  • persistent storage;
  • HTTPS ingress for any shared or internet-facing install;
  • Kubernetes Secrets for any provider keys, the license key, image pull credentials, and the browser session secret.

Docker Compose POC​

Use this path for the fastest customer proof of concept on one VM:

tar -xzf synth-acme-poc-kit.tar.gz
cd synth-acme-poc-kit

cat secrets/gcp-artifact-registry-pull-key.json | docker login us-central1-docker.pkg.dev \
  --username _json_key \
  --password-stdin

${EDITOR:-vi} values.env
docker compose --env-file values.env config --quiet
docker compose --env-file values.env up -d

Open the SYNTH_PUBLIC_URL from values.env and create the first admin user in the browser. The Compose POC stores product state in a named Docker volume and persists the browser-session signing secret on first boot.

Stop the POC without deleting data:

docker compose --env-file values.env down

Direct Docker Image​

When Synth provides an image reference directly, run it with a persistent volume and the same production environment variables used by Compose:

cat /secure/path/gcp-artifact-registry-pull-key.json | docker login us-central1-docker.pkg.dev \
  --username _json_key \
  --password-stdin

docker run --rm \
  -p 8080:8000 \
  -v synth-data:/var/lib/synth \
  -e SYNTH_ENV=production \
  -e SYNTH_PUBLIC_URL=http://127.0.0.1:8080 \
  -e SYNTH_ALLOWED_HOSTS=127.0.0.1,localhost \
  -e SYNTH_CORS_ORIGINS=http://127.0.0.1:8080 \
  -e SYNTH_COOKIE_SECURE=0 \
  -e SYNTH_LICENSE_KEY="$SYNTH_LICENSE_KEY" \
  -e SYNTH_LICENSE_SERVER=https://license.synthkb.io \
  -e OPENAI_API_KEY="$OPENAI_API_KEY" \
  "$SYNTH_IMAGE"

Use Docker Compose for customer POCs unless your Synth contact specifically asks for a direct image smoke test.

Kubernetes With Helm​

Use Kubernetes for team deployments and any install that should be repeatable. The official chart runs one Synth app pod with a persistent volume mounted at /var/lib/synth.

tar -xzf synth-acme-kubernetes-poc-kit.tar.gz
cd synth-acme-kubernetes-poc-kit
export SYNTH_NAMESPACE=synth

kubectl create namespace "$SYNTH_NAMESPACE" --dry-run=client -o yaml | kubectl apply -f -

cat secrets/gcp-artifact-registry-pull-key.json | helm registry login us-central1-docker.pkg.dev \
  --username _json_key \
  --password-stdin

kubectl -n "$SYNTH_NAMESPACE" create secret docker-registry synth-registry-pull \
  --docker-server=us-central1-docker.pkg.dev \
  --docker-username=_json_key \
  --docker-password="$(cat secrets/gcp-artifact-registry-pull-key.json)" \
  --dry-run=client -o yaml | kubectl apply -f -

kubectl -n "$SYNTH_NAMESPACE" create secret generic synth-runtime-secrets \
  --from-literal=SYNTH_JWT_SECRET="$(openssl rand -hex 32)" \
  --from-literal=OPENAI_API_KEY="$OPENAI_API_KEY" \
  --dry-run=client -o yaml | kubectl apply -f -

kubectl -n "$SYNTH_NAMESPACE" create secret generic synth-license \
  --from-file=license-key=/secure/path/synth-license-key.txt \
  --dry-run=client -o yaml | kubectl apply -f -

helm upgrade --install synth \
  oci://us-central1-docker.pkg.dev/project-96337d0a-4d88-427b-af7/synth/charts/synth \
  --namespace "$SYNTH_NAMESPACE" \
  -f values.k8s.yaml \
  --wait \
  --timeout 10m

For the full values file and CaSc examples, see Helm + CaSc.

Data And Upgrades​

Synth stores product state under /var/lib/synth inside the container.

  • Docker Compose stores that path in the synth_customer_data named volume.
  • Kubernetes stores that path on the configured PVC.
  • Do not delete the Docker volume or Kubernetes PVC unless you intentionally want to wipe the installation.
  • Apply upgrades by replacing the image digest or chart version supplied by Synth, then restarting Compose or running helm upgrade.

Verify​

Docker Compose:

set -a
. ./values.env
set +a
curl -fsS "$SYNTH_PUBLIC_URL/health"
curl -fsS "$SYNTH_PUBLIC_URL/health.version"

Kubernetes:

kubectl -n "$SYNTH_NAMESPACE" rollout status deploy/synth --timeout=10m
kubectl -n "$SYNTH_NAMESPACE" get deploy,svc,ingress,pvc
curl -fsS https://synth.example.com/health

After health checks pass, create the first admin user, create a Project, add knowledge, create a read-only agent key, and verify search plus an exact page read. Add or confirm a provider only when you also want an explicitly model-assisted ingestion, linking, or lint job.

Production Notes​

  • Put Synth behind HTTPS before exposing it outside a local POC.
  • Set SYNTH_PUBLIC_URL to the external origin so MCP and OAuth URLs are correct.
  • Keep provider keys and Git tokens in Docker/Kubernetes secrets, not in docs or source files.
  • Use CaSc for repeatable global settings, project defaults, agents, and watchers.
  • Create API keys with only the scopes each agent or automation needs.

Next: