# Deployment overview

Deploy Syntho using Docker Compose or Kubernetes (Helm).

### Choose a deployment method

Use this as a quick decision guide:

* [**Docker Compose**](https://docs.syntho.ai/deploy-syntho/deploy-syntho-using-docker) for a single host setup. Good for POCs and smaller installs.
* [**Kubernetes (Helm)**](https://docs.syntho.ai/deploy-syntho/deploy-syntho-using-kubernetes) for clusters. Best for scaling and larger production runs.

### Architecture

<figure><img src="https://content.gitbook.com/content/U61B9DqtWCNO3Z30vnjh/blobs/ER1Ncs7SVAXwQiP3PtDQ/Syntho%20Architecture.png" alt=""><figcaption><p>Syntho architecture</p></figcaption></figure>

#### 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)

{% hint style="info" %}
On Kubernetes, Ray is deployed as a separate Helm chart. On Docker Compose, Ray comes as part of the bundle.
{% endhint %}

### 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) |

{% hint style="info" %}
Depending on the data size and throughput requirements, more resources may be needed to scale. Start with minimal or recommended and scale as needed.
{% endhint %}

{% hint style="info" %}
With Kubernetes you can scale Ray horizontally by adding worker capacity.
{% endhint %}

### 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](https://docs.syntho.ai/deploy-syntho/deploy-syntho-using-docker) or [Kubernetes (Helm)](https://docs.syntho.ai/deploy-syntho/deploy-syntho-using-kubernetes).

#### Backups

Backups are deployment-specific. Use the matching guide:

* [Back up PostgreSQL (Docker Compose)](https://docs.syntho.ai/deploy-syntho/deploy-syntho-using-docker/back-up-postgresql)
* [Back up PostgreSQL (Kubernetes)](https://docs.syntho.ai/deploy-syntho/deploy-syntho-using-kubernetes/back-up-postgresql)

### 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

{% hint style="warning" %}
Treat deployment config as sensitive.
{% endhint %}

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.

{% hint style="warning" %}
Rotate secret keys carefully.
{% endhint %}

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](https://docs.syntho.ai/deploy-syntho/deploy-syntho-using-docker)
* [Kubernetes (Helm)](https://docs.syntho.ai/deploy-syntho/deploy-syntho-using-kubernetes)

After deployment, run the [Data generation readiness check](https://docs.syntho.ai/overview/get-started/prerequisites)