local-dev-setup

name	local-dev-setup
summary	Run Couchbase locally for development — Docker Compose setup, cluster initialization, loading travel-sample, Query Workbench, first KV operation and SQL++ query
description	Run Couchbase locally for development — Docker Compose setup, cluster initialization, loading travel-sample, Query Workbench, first KV operation and SQL++ query
allowed-tools	Bash
metadata	{"last_verified":"2026-05","handoff":[{"condition":"user wants to connect from application code","type":"variant","skill":"server-connection-python"},{"condition":"user asks about SQL++ queries","skill":"sqlpp-language"},{"condition":"user asks about testing their Couchbase application","skill":"testing-patterns"},{"condition":"user wants to use Capella instead of local Docker","skill":"capella-quickstart"},{"condition":"user is new to Couchbase concepts","skill":"getting-started"},{"condition":"user encounters connection errors during local setup","skill":"error-handling"},{"condition":"user asks about the VS Code extension for local development","skill":"vscode-extension"}]}

Local Dev Setup — Docker

Prerequisites

• Docker Desktop (or Docker Engine + Compose plugin)
• Ports 8091–8097, 11210 free on localhost

Quickstart

The repo provides ready-made templates. Copy them into your project:

# From the agent-skills repo root:
cp templates/docker-compose.yml ./docker-compose.yml
cp -r templates/scripts ./scripts

Or create them manually — see below.

docker-compose.yml

services:
  couchbase:
    image: couchbase/server:enterprise-8.0.1
    container_name: couchbase
    ports:
      - "8091:8091"   # Web Console
      - "8093:8093"   # SQL++ Query
      - "8094:8094"   # Full-Text Search
      - "11210:11210" # KV (SDK connections)
    volumes:
      - couchbase-data:/opt/couchbase/var
      - ./scripts/init-cluster.sh:/init-cluster.sh:ro
    environment:
      - CB_BUCKET=myapp
      - CB_SCOPE=_default
      - CB_COLLECTION=_default
      - LOAD_TRAVEL_SAMPLE=false
    healthcheck:
      test: ["CMD", "curl", "-sf", "http://localhost:8091/pools"]
      interval: 10s
      retries: 10
      start_period: 30s

volumes:
  couchbase-data:

Start and initialize

# Start the container
docker compose up -d

# Wait for healthy, then initialize the cluster (one-time)
docker compose exec couchbase bash /init-cluster.sh

# To also load the travel-sample dataset:
LOAD_TRAVEL_SAMPLE=true docker compose exec couchbase bash /init-cluster.sh

The init script:

1. Initializes the cluster with KV + Query + Search + Analytics services
2. Sets memory quotas
3. Creates the myapp bucket (or whatever CB_BUCKET is set to)
4. Optionally loads travel-sample

Verify

Open the Web Console: http://localhost:8091

• Username: Administrator
• Password: password

Run a query in the Query tab:

SELECT "hello" AS greeting;

SDK connection string

couchbase://localhost

All SDK connection examples in this repo use this string with Administrator / password.

Load travel-sample later

If you skipped it during init:

curl -u Administrator:"$CB_ADMIN_PASSWORD" \
  -X POST http://localhost:8091/sampleBuckets/install \
  -d '["travel-sample"]'

Or: Web Console → Settings → Sample Buckets → check travel-sample → Load Sample Data.

Common issues

Container starts but init fails:

# Check logs
docker compose logs couchbase

# Re-run init (idempotent)
docker compose exec couchbase bash /init-cluster.sh

Port already in use:

# Find what's using 8091
lsof -i :8091
# Change the host port in docker-compose.yml, e.g. "9091:8091"

SDK can't connect:

# Verify KV port is reachable
curl http://localhost:8091/pools/default -u Administrator:"$CB_ADMIN_PASSWORD"

Reset everything:

docker compose down -v   # -v removes the named volume (all data)
docker compose up -d
docker compose exec couchbase bash /init-cluster.sh

Useful endpoints

URL	Purpose
http://localhost:8091	Web Console
http://localhost:8093/query/service	SQL++ REST API
http://localhost:8094	Search REST API