> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Deploy Enterprise: all-in-one image

> Run the fully featured Buckle Enterprise edition with Docker Compose: one container for the dashboard, API, and gateway, plus PostgreSQL.

This guide deploys the Enterprise edition's all-in-one image with Docker Compose: the `trybuckle/slim` container (dashboard, API, and gateway in one) plus a PostgreSQL database. It takes about ten minutes. For the free, open source edition, see [Deploy Community Edition](/docs/self-hosting/community.md).

This setup is ideal for evaluation and small-team use. Before going to production, work through the [production checklist](#production-checklist) below.

## Prerequisites

* **Access to the `trybuckle/slim` image.** The image is private; pull access is granted with your Enterprise agreement. If you don't have access yet, [contact us](https://onecli.cal.com/jonathan/30min).
* A Docker Hub login with that access active on the deploying machine: `docker login`
* Docker Engine with the Compose plugin (`docker compose version` should work)
* Outbound network access to pull images from Docker Hub
* PostgreSQL: the compose file below includes one. To use an external database instead, see [Configuration](/docs/self-hosting/configuration.md#database)

## Deploy

**1. Create the compose file**

Create a directory for your deployment and save this as `docker-compose.yml`:

```yaml docker-compose.yml theme={null}
services:
  postgres:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: buckle
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: buckle
    volumes:
      - postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U buckle"]
      interval: 5s
      timeout: 5s
      retries: 10

  buckle:
    image: trybuckle/slim:latest
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
    ports:
      - "127.0.0.1:10254:10254" # dashboard + API
      - "127.0.0.1:10255:10255" # gateway proxy
    environment:
      DATABASE_URL: postgresql://buckle:${POSTGRES_PASSWORD}@postgres:5432/buckle
      APP_URL: http://localhost:10254
      BUCKLE_ORG_API_KEY: ${BUCKLE_ORG_API_KEY}
    volumes:
      - buckle-data:/app/data

volumes:
  postgres-data:
  buckle-data:
```

> [!NOTE]
>
> The example pins nothing: `trybuckle/slim:latest` tracks the latest stable release. For production, pin a specific tag; every release is also published under an immutable short commit SHA. The tag list is visible on Docker Hub once your account has image access.

> [!WARNING]
>
> Keep the `buckle-data` volume. It stores the auto-generated `SECRET_ENCRYPTION_KEY` that encrypts your secret store. If the volume is lost and you didn't set the key yourself, stored secrets become unrecoverable.

**2. Configure secrets**

Create a `.env` file next to the compose file:

```bash theme={null}
cat > .env <<EOF
POSTGRES_PASSWORD=$(openssl rand -hex 24)
BUCKLE_ORG_API_KEY=oc_org_$(openssl rand -hex 32)
EOF
chmod 600 .env
```

`BUCKLE_ORG_API_KEY` is your instance's organization API key, the credential you'll use to provision projects and agents over the API. The format is enforced: `oc_org_` followed by 64 lowercase hex characters.

> [!NOTE]
>
> If you omit `BUCKLE_ORG_API_KEY`, the instance generates one on first start and prints it to the container logs exactly once. To load the key from a mounted secret instead of the environment, set `BUCKLE_ORG_API_KEY_FILE` to the file path. See [Configuration](/docs/self-hosting/configuration.md).

**3. Start the stack**

```bash theme={null}
docker compose up -d
```

The container runs database migrations automatically on startup, then provisions your organization and seeds the organization API key. The instance is API-ready before anyone opens the dashboard.

**4. Verify the deployment**

Check both health endpoints:

```bash theme={null}
curl http://localhost:10254/v1/health
```

```json theme={null}
{ "status": "ok", "version": "1.39.0", "timestamp": "2026-07-02T00:21:35.733Z" }
```

```bash theme={null}
curl http://localhost:10255/healthz
```

```json theme={null}
{ "status": "ok", "version": "0.1.0" }
```

Then open [http://localhost:10254](http://localhost:10254). You'll land on the app-connection screen.

> [!NOTE]
>
> By default the instance runs in single-user mode: there is no login screen, and anyone who can reach port `10254` has admin access. The compose file binds to `127.0.0.1` for that reason. Keep the dashboard on a private network, or enable [multi-user mode](/docs/self-hosting/configuration.md#authentication) with Google OAuth.

**5. Next steps**

* [Connect the CLI and agents](/docs/self-hosting/connect-agents.md), including headless provisioning with your organization API key
* [Connect apps](/docs/integrations/app-connections.md) with your own OAuth credentials
* Review the [configuration reference](/docs/self-hosting/configuration.md)

## Upgrading

Releases update the `latest` tag. To upgrade:

```bash theme={null}
docker compose pull
docker compose up -d
```

Database migrations run automatically when the new container starts.

> [!WARNING]
>
> Back up your PostgreSQL database before upgrading: `docker compose exec postgres pg_dump -U buckle buckle > backup.sql`.

> [accordion] Upgrading across the agent access change
>
> Releases from mid-2026 replace secret modes and per-agent assignment lists with [agent grants](/docs/guides/agent-access.md). The upgrade converts your existing setup automatically on first boot — every agent keeps exactly the credentials it had, expressed as grants — and the retired endpoints answer `410 Gone` with a pointer to their replacement. Organization rules and the `/v1/org/policy` console are unaffected.
>
> Two things to know:
>
> * **Upgrade within the conversion window.** The automatic converter ships for six months of releases after the change. If your instance is older than that, upgrade in two hops: first to any release inside the window (the conversion runs), then onward to current.
> * **Scripts using the retired surface need updating.** Anything calling `PATCH /agents/{id}/secret-mode`, `agents set-secrets`, or the project `policy rules` writes should move to the grants endpoints — see the [retirement inventory](/docs/api-reference/errors.md#retired-endpoints-410).

## Production checklist

* **Terminate TLS in front of the instance.** Run a reverse proxy (nginx, Caddy, or your load balancer) with HTTPS, and set `APP_URL` to the public URL. It's also the base for OAuth callback URLs when you [connect apps](/docs/integrations/app-connections.md).
* **Pin the image tag** instead of tracking `latest`.
* **Use managed PostgreSQL** where available, and schedule backups of both the database and the `buckle-data` volume.
* **Set `SECRET_ENCRYPTION_KEY` explicitly** (for example `openssl rand -hex 32`) and store it in your secrets manager, rather than relying on the auto-generated key in the volume.
* **Restrict network exposure.** In single-user mode, treat port `10254` as an admin interface. Port `10255` is the gateway your agents connect to; expose it only where agents run.

## Troubleshooting

> [accordion] The container exits with a database migration error
>
> If the very first start fails with `Can't reach database server`, PostgreSQL wasn't ready when migrations ran. The compose file above guards against this with a healthcheck and `depends_on: condition: service_healthy`. Make sure yours has both.
>
> If a failed first boot left migrations in a broken state on an instance with no data yet, reset and start clean:
>
> ```bash theme={null}
> docker compose down -v
> docker compose up -d
> ```
>
> > [!WARNING]
> >
> > `down -v` deletes the volumes. Only do this on an instance with no data you need.

> [accordion] The logs show "BUCKLE\_ORG\_API\_KEY is malformed"
>
> The key must be `oc_org_` followed by exactly 64 lowercase hex characters. Regenerate one:
>
> ```bash theme={null}
> echo "oc_org_$(openssl rand -hex 32)"
> ```
>
> The instance refuses to substitute a generated key for a malformed one, so a typo fails loudly instead of silently issuing a key you don't know.

> [accordion] Pulling fails with "pull access denied for trybuckle/slim"
>
> The image is private. Two things need to be true: your Docker Hub account has been granted access as part of your Enterprise agreement, and the deploying machine is logged in with that account (`docker login`). If you don't have access yet, [contact us](https://onecli.cal.com/jonathan/30min).

> [accordion] Port 10254 or 10255 is already in use
>
> Change the host side of the port mappings in `docker-compose.yml` (for example `127.0.0.1:20254:10254`) and use that port in your browser and `APP_URL`.

> [accordion] Where are the logs?
>
> ```bash theme={null}
> docker compose logs -f buckle
> ```
>
> The gateway logs plain lines (look for `starting buckle-gateway` and `gateway ready`); the dashboard and API log structured JSON. Request activity from agents is stored in your PostgreSQL and shown in the dashboard's activity view.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.