> For the complete documentation index, see [llms.txt](https://docs.kawa.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kawa.ai/11_00_exploitation/deployment-architectures.md).

# Deployment Architectures

KAWA can be deployed in several ways. This page shows the reference architecture for each option, illustrated with a diagram. For a side-by-side comparison of what each cloud provider supports, see **Deployment Options**.

## 1. AWS (EC2 / ECS)

A single-host **Docker Compose** deployment: KAWA runs as one OCI artifact on a single **EC2 / ECS** host. This is one of several supported options — for the Kubernetes (**EKS**) topology, see **Deployment Options**. The same pinned artifact is promoted unchanged across environments, and all network links are TLS-encrypted in transit.

<div data-with-frame="true"><figure><img src="https://2701963830-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6wXylCyyATfFd8yjjWTn%2Fuploads%2Fgit-blob-bc516ff4107cfd9eba68cbde21e38fdc42275f7c%2FKAWA-EC2-ECS-diagram.svg?alt=media" alt=""><figcaption></figcaption></figure></div>

<table data-search="false"><thead><tr><th>Category</th><th>Details</th></tr></thead><tbody><tr><td>Model</td><td>Single-host <strong>Docker Compose</strong> deployment — one OCI artifact on a single <strong>EC2 / ECS</strong> host.</td></tr><tr><td>Artifact</td><td>One OCI release bundling four images: <strong>KAWA Java</strong> (JDK 21 — core backend and platform APIs), <strong>KAWA AI</strong> (Python — inference via <strong>Amazon Bedrock</strong>, isolated in a filesystem sandbox), <strong>KAWA Workflow</strong> (<strong>BPMN 2.0</strong> workflow engine), <strong>KAWA Python</strong> (runs user Python code, packages from <strong>PyPI</strong>).</td></tr><tr><td>Host</td><td><code>m7a.2xlarge</code> — 8 vCPU, 32 GB RAM, <strong>AMD64 / x86_64</strong>, standard Linux. Runtime: <strong>Docker Compose</strong> (OCI).</td></tr><tr><td>Data &#x26; storage</td><td><strong>PostgreSQL</strong> — back-office and entity store; <strong>Amazon S3</strong> — user files, one bucket per environment; <strong>SQL warehouse</strong> — one engine per deployment: <strong>ClickHouse</strong>, <strong>Trino</strong>, <strong>Snowflake</strong> or <strong>Databricks</strong>.</td></tr><tr><td>AI</td><td><strong>Amazon Bedrock</strong> — model inference.</td></tr><tr><td>Authentication</td><td>OIDC / OAuth2 — <strong>Auth0</strong> or any OIDC-compliant IdP.</td></tr><tr><td>Integrations &#x26; email</td><td><strong>SMTP</strong> — outbound email; <strong>Jira Cloud</strong> — issue sync; <strong>Bitbucket</strong> — source repositories; external / internal REST APIs.</td></tr><tr><td>Environments</td><td>Same pinned artifact promoted <strong>DEV → STAGING → PROD</strong>. Production runs active with an optional passive warm-standby host — see <strong>Disaster Recovery Architecture</strong>. Each environment has its own <strong>S3</strong> bucket.</td></tr></tbody></table>

### 1.1 Deploy or upgrade

Deploy or upgrade an environment with a single command:

```bash
docker compose \
  -f oci://<registry>/kawa-platform:<tag> up -d
```

Replace `<registry>` and `<tag>` with the values provided by KAWA during onboarding. To upgrade, pull a new tag — there is no rebuild. The same pinned artifact moves unchanged from non-production to production.

## 2. AWS single appliance

One **EC2 instance** runs KAWA as a single `docker compose` package, with all its state on a dedicated **EBS volume** that survives the instance and is snapshotted every few hours. Secrets come from **Secrets Manager** at boot, users come in through an internal load balancer, and the instance needs no internet access. It is the simplest production topology, and the one to pick when a single team operates KAWA inside its own network. Full description, prerequisites, sizing and disaster recovery: [Single Appliance Deployment](/11_00_exploitation/single-appliance-deployment.md).

<div data-with-frame="true"><figure><img src="https://2701963830-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6wXylCyyATfFd8yjjWTn%2Fuploads%2Fgit-blob-43c868d0772c0dba7e79e5addc0be748f4fcc318%2FKAWA-single-appliance-diagram.svg?alt=media" alt=""><figcaption></figcaption></figure></div>

<table data-search="false"><thead><tr><th>Category</th><th>Details</th></tr></thead><tbody><tr><td>Model</td><td>One <strong>EC2 instance</strong> running the KAWA <strong>Docker Compose</strong> package. The instance is disposable: replaced, not repaired.</td></tr><tr><td>Host</td><td><strong>AMD64</strong>, any Linux distribution with docker and docker compose v2. Sized to the data KAWA holds (RAM ≈ compressed data + 20 GB), e.g. <code>r7a.4xlarge</code>.</td></tr><tr><td>Data &#x26; storage</td><td>One encrypted <strong>EBS</strong> data volume mounted on <code>/data</code>, holding all KAWA state; <strong>EBS snapshots</strong> every N hours through Data Lifecycle Manager.</td></tr><tr><td>Secrets</td><td><strong>AWS Secrets Manager</strong> — the KAWA environment, fetched at boot by the instance role through a VPC endpoint.</td></tr><tr><td>Network</td><td>Internal <strong>ALB</strong> with TLS in front of port <code>8080</code>. Images from an internal container registry, Python packages from an internal PyPI mirror; no internet access required.</td></tr><tr><td>Authentication</td><td>KAWA's own login, or OIDC / OAuth2 with any OIDC-compliant IdP (optional).</td></tr><tr><td>Email</td><td><strong>SMTP</strong> relay for alerting and notifications (optional).</td></tr><tr><td>Recovery</td><td>Hardware fault: EC2 auto-recovery. Broken instance: a new one on the same volume. Lost volume or zone: restore the latest snapshot. Region: snapshot copies in a second region.</td></tr></tbody></table>