Skip to main content
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
This guide focuses on local execution - Basecut CLI runs in a container and connects to your database container. For production workloads, see Agent Deployment.

​
Basic Setup

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

Add a Basecut service that runs after your database is ready: 
# 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: 
# 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: 
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.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: 
docker build -f Dockerfile.basecut -t myapp-basecut .
Then reference in docker-compose.yml: 
services:
  basecut-restore:
    image: myapp-basecut
    # ... rest of config ...

​
Environment Variables

Store Basecut credentials securely:

​
Option 1: .env File (Local Development)

# .env
BASECUT_API_KEY=bc_test_xxx
BASECUT_DATABASE_URL=postgresql://postgres:postgres@postgres:5432/myapp_dev
Docker Compose automatically loads .env: 
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: 
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: 
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: 
# 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