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

# Basecut with Docker Compose

> Integrate Basecut into your Docker Compose workflow for local development

Use Basecut with Docker Compose to automatically restore snapshots when starting your local development environment. This ensures every developer starts with the same realistic dataset.

## Overview

This guide shows how to:

* Add Basecut CLI to your Docker Compose setup
* Restore snapshots as part of `docker compose up`
* Use `BASECUT_DATABASE_URL` with Docker networks
* Share snapshots across your team

<Info>
  This guide focuses on **local execution** - Basecut CLI runs in a container and connects to your database container. For production workloads, see [Agent Deployment](/advanced/agent-deployment).
</Info>

## Basic Setup

### 1. Add Basecut Service to docker-compose.yml

Add a Basecut service that runs after your database is ready:

```yaml theme={null}
# docker-compose.yml
version: '3.8'

services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: myapp_dev
    ports:
      - "5432:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5

  basecut-restore:
    image: myapp-basecut # Build from the Dockerfile in this guide
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      BASECUT_API_KEY: ${BASECUT_API_KEY}
      BASECUT_DATABASE_URL: postgresql://postgres:postgres@postgres:5432/myapp_dev
    volumes:
      - ./basecut.yml:/app/basecut.yml
      - ./snapshots:/app/snapshots
    working_dir: /app
    command: >
      sh -c "
        basecut snapshot restore dev-seed:latest
          --target \"$$BASECUT_DATABASE_URL\"
          --yes
      "
    profiles:
      - restore  # Only run when explicitly requested
```

### 2. Restore Snapshot on Startup

Run Basecut restore as part of your startup:

```bash theme={null}
# Start services and restore snapshot
docker compose --profile restore up -d

# Or restore separately after services are up
docker compose up -d postgres
docker compose run --rm basecut-restore
```

## Using Docker Networks

When your database is in a Docker network, use the service name as the hostname:

```yaml theme={null}
services:
  postgres:
    # ... postgres config ...
    networks:
      - app-network

  basecut-restore:
    # ... basecut config ...
    networks:
      - app-network
    environment:
      # Use service name 'postgres' as hostname
      BASECUT_DATABASE_URL: postgresql://postgres:postgres@postgres:5432/myapp_dev

networks:
  app-network:
    driver: bridge
```

## Custom Basecut Image

Create a custom Docker image with Basecut pre-installed for faster startup:

```dockerfile theme={null}
# Dockerfile.basecut
FROM alpine:latest

RUN apk add --no-cache curl bash

# Install Basecut CLI
RUN curl -fsSL https://basecut.dev/install.sh | sh

ENV PATH="/root/.local/bin:${PATH}"

WORKDIR /app

ENTRYPOINT ["basecut"]
```

Build and use:

```bash theme={null}
docker build -f Dockerfile.basecut -t myapp-basecut .
```

Then reference in docker-compose.yml:

```yaml theme={null}
services:
  basecut-restore:
    image: myapp-basecut
    # ... rest of config ...
```

## Environment Variables

Store Basecut credentials securely:

### Option 1: .env File (Local Development)

```bash theme={null}
# .env
BASECUT_API_KEY=bc_test_xxx
BASECUT_DATABASE_URL=postgresql://postgres:postgres@postgres:5432/myapp_dev
```

Docker Compose automatically loads `.env`:

```yaml theme={null}
services:
  basecut-restore:
    environment:
      BASECUT_API_KEY: ${BASECUT_API_KEY}
      BASECUT_DATABASE_URL: ${BASECUT_DATABASE_URL}
```

### Option 2: Docker Secrets (Production)

For production, use Docker secrets and export the value before running Basecut:

```yaml theme={null}
services:
  basecut-restore:
    secrets:
      - basecut_api_key
    command: >
      sh -c "
        export BASECUT_API_KEY=$$(cat /run/secrets/basecut_api_key) &&
        basecut snapshot restore dev-seed:latest --target \"$$BASECUT_DATABASE_URL\" --yes
      "

secrets:
  basecut_api_key:
    external: true
```

## Complete Example

Full docker-compose.yml with app, database, and Basecut:

```yaml theme={null}
version: '3.8'

services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: myapp_dev
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5

  app:
    build: .
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      DATABASE_URL: postgresql://postgres:postgres@postgres:5432/myapp_dev
    ports:
      - "3000:3000"
    volumes:
      - .:/app
      - /app/node_modules

  basecut-restore:
    image: myapp-basecut
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      BASECUT_API_KEY: ${BASECUT_API_KEY}
      BASECUT_DATABASE_URL: postgresql://postgres:postgres@postgres:5432/myapp_dev
    volumes:
      - ./basecut.yml:/app/basecut.yml
    working_dir: /app
    command: >
      sh -c "
        echo 'Restoring snapshot...' &&
        basecut snapshot restore dev-seed:latest
          --target \"$$BASECUT_DATABASE_URL\"
          --yes &&
        echo 'Snapshot restored successfully'
      "
    profiles:
      - restore

volumes:
  postgres_data:
```

**Usage:**

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

# Restore snapshot (one-time or when needed)
docker compose --profile restore up basecut-restore

# View logs
docker compose logs basecut-restore
```

## Tips

* **Use profiles**: The `profiles` directive lets you run Basecut restore only when needed, not on every `docker compose up`
* **Health checks**: Ensure your database is healthy before restoring (prevents connection errors)
* **Volume mounts**: Mount `basecut.yml` and snapshot directories if using local storage
* **Idempotency**: Use `--yes` flag to skip confirmation prompts in CI/automated environments

## Next Steps

* Learn about [execution modes](/core-concepts/execution-modes) (local vs agent)
* Set up [CI/CD integration](/workflows/ci-cd) for automated snapshots
* Explore [common workflows](/workflows/common-workflows) for different use cases