Basecut with Docker Compose

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

Learn about execution modes (local vs agent)
Set up CI/CD integration for automated snapshots
Explore common workflows for different use cases

Getting Started

Core Concepts

Configuration

Workflows

Integrations

CLI Reference

Deployment

Reference

Basecut with Docker Compose

Overview

Basic Setup

1. Add Basecut Service to docker-compose.yml

2. Restore Snapshot on Startup

Using Docker Networks

Custom Basecut Image

Environment Variables

Option 1: .env File (Local Development)

Option 2: Docker Secrets (Production)

Complete Example

Tips

Next Steps

​Overview

​Basic Setup

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

​2. Restore Snapshot on Startup

​Using Docker Networks

​Custom Basecut Image

​Environment Variables

​Option 1: .env File (Local Development)

​Option 2: Docker Secrets (Production)

​Complete Example

​Tips

​Next Steps

Overview

Basic Setup

1. Add Basecut Service to docker-compose.yml

2. Restore Snapshot on Startup

Using Docker Networks

Custom Basecut Image

Environment Variables

Option 1: .env File (Local Development)

Option 2: Docker Secrets (Production)

Complete Example

Tips

Next Steps