Deployment overview

Deploy Syntho using Docker Compose or Kubernetes (Helm).

Choose a deployment method

Use this as a quick decision guide:

• Docker Compose for a single host setup. Good for POCs and smaller installs.

• Kubernetes (Helm) for clusters. Best for scaling and larger production runs.

Architecture

Syntho architecture

Core components

Most deployments include these services:

• Frontend (web UI)

• Backend (users, workspaces, orchestration)

• Core API (core platform services)

• Ray (distributed execution for heavy workloads)

• PostgreSQL (metadata storage)

• Redis (queues / caching)

On Kubernetes, Ray is deployed as a separate Helm chart. On Docker Compose, Ray comes as part of the bundle.

Hardware requirements

Resource	Minimal	Recommended	Scaling
vCPU	8	12	>>>
Memory (RAM)	32GB	64GB	>>>
Disk	128GB	256GB	>>>
OS	Linux (x86_64)	Linux (x86_64)	Linux (x86_64)

Depending on the data size and throughput requirements, more resources may be needed to scale. Start with minimal or recommended and scale as needed.

With Kubernetes you can scale Ray horizontally by adding worker capacity.

Stateful services

Syntho requires PostgreSQL and Redis.

• PostgreSQL stores metadata.

• Deployments use two databases on one PostgreSQL host.

• For production, it’s recommended to use a hosted / managed PostgreSQL.

The exact configuration depends on your deployment method. See Docker Compose or Kubernetes (Helm).

Backups

Backups are deployment-specific. Use the matching guide:

• Back up PostgreSQL (Docker Compose)

• Back up PostgreSQL (Kubernetes)

Networking and TLS

Expose Syntho via an HTTP edge component:

• Reverse proxy

• Load balancer

• Ingress (Kubernetes)

Terminate TLS at that edge component.

Then configure Syntho for HTTPS and secure cookies.

Hostnames (DNS)

Use a stable hostname for the UI, like syntho.company.com.

If you expose the Backend separately, use a second hostname. For example api.syntho.company.com.

Certificates (Kubernetes)

On Kubernetes, TLS is usually provided via either:

• cert-manager (recommended), or

• a pre-created TLS secret referenced by the Ingress.

If TLS is terminated at a reverse proxy / load balancer / Ingress, Syntho must be configured for https.

If Syntho is configured for http, browsers can reject cookies.

Symptoms include login loops or sessions not sticking.

Fix:

• Set the frontend protocol to https.

• Disable secure cookies.

Security notes

Treat deployment config as sensitive.

Common files contain secrets:

• Docker Compose: .env

• Kubernetes/Helm: values.yaml

Do not commit these files to Git.

Prefer one of these approaches:

• Inject values via your CI/CD secret store.

• Use Kubernetes Secrets (manualSecretName) or an external secrets operator.

Rotate secret keys carefully.

Syntho uses secret keys for sessions and encryption.

Changing keys can break sessions.

It can also make previously stored encrypted values unreadable.

Plan key rotation:

1. Back up PostgreSQL metadata databases.

2. Stop traffic and running jobs.

3. Rotate keys.

4. Restart services.

5. Verify login and basic workflows.

If you are unsure what do do, ask Syntho Support.

Next steps

Pick your deployment method and follow the full guide:

• Docker Compose

• Kubernetes (Helm)