# Installation

> Source: https://docs.clonepartner.com/getting-started/installation/

<!-- sources: docker-compose.yaml, scripts/docker-entrypoint.sh, Dockerfile, README.md, src/server/config.ts -->

# Installation

## Goal

Bring up a local Envoy deployment with Docker Compose: a control plane serving the web UI and API on port 3003, and a separate executor container that runs task subprocesses.

Envoy ships as a single compiled binary per customer build (produced with `bun build --compile`), packaged into a Docker image together with the web UI assets and any bundled task and job template YAML. The same image runs both the control plane and the executor; the container command decides the role.

## Prerequisites

- Docker with the Compose plugin
- A checkout of the Envoy repository (the Compose file builds the image from the repository root)
- Two secrets you generate yourself:
  - an **encryption key** used to encrypt connector configurations at rest
  - an **executor key** shared between the control plane and the executor

:::callout{type="warning"}
Treat the encryption key as permanent for the life of the deployment. Connector configurations stored in the database are encrypted with it; losing or changing the key makes them unreadable.
:::

## Steps

### 1. Export the required secrets

The Compose file reads `ENVOY_ENCRYPTION_KEY` and `ENVOY_EXECUTOR_KEY` from your shell environment (or a `.env` file next to `docker-compose.yaml`):

```bash
export ENVOY_ENCRYPTION_KEY="$(openssl rand -hex 32)"
export ENVOY_EXECUTOR_KEY="$(openssl rand -hex 32)"
```

`ANTHROPIC_API_KEY` is optional; when set, it enables the built-in AI assistant.

### 2. Start the stack

```bash
docker compose up --build -d
```

This starts two services:

| Service | Container | Role |
| --- | --- | --- |
| `control-plane` | `envoy-control-plane` | Web UI, REST API, scheduler, state store. Publishes port `3003`. |
| `executor` | `envoy-executor` | Runs task subprocesses. Registers with the control plane over HTTP using the executor key. |

Both containers mount `./data` at `/app/data` (shared files for file-based connectors) and a named volume `cp-state` at `/app/state` (server database and generated configuration).

### 3. Understand the generated configuration

On first start the entrypoint script generates `envoy-server.yaml` at the path given by `ENVOY_CONFIG_PATH` (in the default Compose file: `/app/state/envoy-server.yaml`, on the persistent volume). Generation only happens when the file does not already exist and `ENVOY_ENCRYPTION_KEY` is set. Selected variables the entrypoint understands:

| Variable | Default | Purpose |
| --- | --- | --- |
| `ENVOY_PORT` | `3000` (Compose sets `3003`) | Control plane HTTP port |
| `ENVOY_STORE_TYPE` | `sqlite` | Server state store: `sqlite`, `mssql`, or `postgres` |
| `ENVOY_DB_PATH` | `/app/envoy-server.db` | SQLite database path (Compose sets `/app/state/envoy-server.db`) |
| `ENVOY_EXECUTOR_TYPE` | `local` | `http` makes the control plane dispatch runs to remote executors |
| `ENVOY_CALLBACK_URL` | — | URL executors use to call back to the control plane (required for `http`) |
| `ENVOY_LOG_STORE` | `file` | Where run logs are stored (Compose sets `db`) |
| `ENVOY_RETENTION_DAYS` | `30` | Run retention window |
| `ENVOY_APP_NAME` | `Envoy` | Branding: application name shown in the UI |
| `ENVOY_AUTH_TOTP_REQUIRED` | — | Set `false` to disable mandatory two-factor authentication |

Once the file exists, edits to it win over environment variables — the entrypoint never regenerates or overwrites it. For the full schema, including MSSQL/PostgreSQL state stores, OAuth providers, secrets backends, and Litestream replication of the SQLite store, see [Server configuration](/deployment/server-configuration/).

## Verify it worked

Open `http://localhost:3003`. A fresh deployment redirects to the `/setup` screen, which asks you to create the administrator account. Continue with [First-time setup](/getting-started/first-time-setup/).

To check the containers instead:

```bash
docker compose ps
docker compose logs control-plane
```

The control plane log ends with either `Starting Envoy directly...` or `Starting Envoy with Litestream replication...` from the entrypoint, followed by server output.

## Other topologies

The repository also contains Compose files for remote single-host deployments behind a TLS proxy and for an Azure-style stack with MSSQL and Azure Key Vault. Those are production topologies, not quickstart material — see [Docker deployment](/deployment/docker/) and [Azure deployment](/deployment/azure/). Per-customer images (binary name, branding, bundled catalog) are produced by the build pipeline described in [Customer builds and catalog](/deployment/customer-builds-and-catalog/).

## Related

- [First-time setup](/getting-started/first-time-setup/) — create the admin account and sign in
- [Server configuration](/deployment/server-configuration/) — every `envoy-server.yaml` key
- [Control plane and executors](/deployment/control-plane-and-executors/) — how the two roles cooperate