Skip to main content

Docker

Docker is the fastest customer proof-of-concept path for a single VM. Use the official Synth image and the generated Docker Compose kit supplied with your license. Do not build your own product image for a customer install.

The generated kit contains:

  • docker-compose.yml;
  • values.env;
  • customer.compose.casc.yaml;
  • README.md and customer handoff notes;
  • a private Artifact Registry pull key under secrets/ when included in the handoff.

Start the POC:

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.

What To Edit​

In values.env, set or confirm:

SYNTH_IMAGE=us-central1-docker.pkg.dev/project-96337d0a-4d88-427b-af7/synth/synth:latest@sha256:...
SYNTH_PUBLIC_URL=http://127.0.0.1:8080
SYNTH_ALLOWED_HOSTS=127.0.0.1,localhost
SYNTH_CORS_ORIGINS=http://127.0.0.1:8080
SYNTH_COOKIE_SECURE=0
SYNTH_LICENSE_KEY=<signed Synth license key>
SYNTH_LICENSE_SERVER=https://license.synthkb.io
OPENAI_API_KEY=<provider key>

OPENAI_API_KEY is optional when the deployment only needs canonical Project search and exact page reads. Configure a supported provider when you enable an explicit model-assisted job.

For an HTTPS VM, set SYNTH_PUBLIC_URL to the real URL, set SYNTH_ALLOWED_HOSTS and SYNTH_CORS_ORIGINS to that host/origin, and set SYNTH_COOKIE_SECURE=1.

Do not put raw provider keys, Git tokens, registry pull keys, cookies, or license keys in customer.compose.casc.yaml.

Data​

The official container uses:

SYNTH_HOME=/var/lib/synth
HOME=/var/lib/synth

The Compose POC mounts that path to the synth_customer_data named volume. Users, projects, API keys, graph/search state, generated app state, and the Docker-managed browser-session signing secret survive container restarts.

Health​

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

Stop Or Upgrade​

Stop without deleting data:

docker compose --env-file values.env down

Upgrade only to an image digest supplied by Synth:

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

Direct Docker Run​

Use direct docker run only for a quick image smoke test when Synth gives you a specific image reference:

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"

Next: Kubernetes.