Docker Compose Wizard

Docker Compose — storefront-api local development

Generated for: storefront-api · Stack: Node 20 + Postgres 15 + Redis 7 + Elasticsearch 8 · Target: local laptop

docker-compose.yml

version: "3.9"

networks:
  storefront-net:
    driver: bridge

volumes:
  postgres-data:
  redis-data:
  elasticsearch-data:

services:

  postgres:
    image: postgres:15.6
    container_name: storefront-postgres
    restart: unless-stopped
    networks:
      - storefront-net
    ports:
      - "${POSTGRES_HOST_PORT:-5432}:5432"
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 20s

  redis:
    image: redis:7.2.4
    container_name: storefront-redis
    restart: unless-stopped
    networks:
      - storefront-net
    ports:
      - "${REDIS_HOST_PORT:-6379}:6379"
    command: redis-server --requirepass ${REDIS_PASSWORD} --appendonly yes
    volumes:
      - redis-data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "-a", "${REDIS_PASSWORD}", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 10s

  elasticsearch:
    image: elasticsearch:8.13.2
    container_name: storefront-elasticsearch
    restart: unless-stopped
    networks:
      - storefront-net
    ports:
      - "${ES_HOST_PORT:-9200}:9200"
    environment:
      discovery.type: single-node
      ES_JAVA_OPTS: "-Xms512m -Xmx512m"
      ELASTIC_PASSWORD: ${ES_PASSWORD}
      xpack.security.enabled: "true"
    volumes:
      - elasticsearch-data:/usr/share/elasticsearch/data
    healthcheck:
      test: ["CMD-SHELL", "curl -sf -u elastic:$${ES_PASSWORD} http://localhost:9200/_cluster/health || exit 1"]
      interval: 15s
      timeout: 10s
      retries: 6
      start_period: 40s

  api:
    image: node:20.12.2-alpine
    container_name: storefront-api
    restart: unless-stopped
    working_dir: /app
    networks:
      - storefront-net
    ports:
      - "${API_HOST_PORT:-3000}:3000"
    volumes:
      - ./:/app
      - /app/node_modules
    environment:
      NODE_ENV: development
      DATABASE_URL: postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}
      REDIS_URL: redis://:${REDIS_PASSWORD}@redis:6379
      ELASTICSEARCH_URL: http://elastic:${ES_PASSWORD}@elasticsearch:9200
      JWT_SECRET: ${JWT_SECRET}
      STRIPE_SECRET_KEY: ${STRIPE_SECRET_KEY}
      PORT: 3000
    command: sh -c "npm install && npm run dev"
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
      elasticsearch:
        condition: service_healthy

.env.example

# ──────────────────────────────────────────────
# storefront-api — local development environment
# Copy this file to .env and fill in all values.
# Never commit .env to version control.
# ──────────────────────────────────────────────

# ── PostgreSQL ──────────────────────────────
# Name of the database created on first boot
POSTGRES_DB=storefront_dev

# Superuser credentials for local Postgres
POSTGRES_USER=storefront
POSTGRES_PASSWORD=changeme_postgres

# Host port Postgres is exposed on (change if 5432 is taken)
POSTGRES_HOST_PORT=5432

# ── Redis ───────────────────────────────────
# Password passed to redis-server and used by the API
REDIS_PASSWORD=changeme_redis

# Host port Redis is exposed on (change if 6379 is taken)
REDIS_HOST_PORT=6379

# ── Elasticsearch ───────────────────────────
# Password for the built-in `elastic` superuser
ES_PASSWORD=changeme_elastic

# Host port Elasticsearch is exposed on (change if 9200 is taken)
ES_HOST_PORT=9200

# ── API ─────────────────────────────────────
# Host port the Node API is exposed on
API_HOST_PORT=3000

# Secret used to sign JWTs — use a long random string in production
JWT_SECRET=changeme_jwt_secret_at_least_32_chars

# Stripe test-mode secret key (starts with sk_test_)
STRIPE_SECRET_KEY=sk_test_replaceme

README — Local Development Environment

Quick start

# 1. Copy and configure environment variables
cp .env.example .env
#    Open .env and set real values for any _PASSWORD / _SECRET fields.

# 2. Start all services (detached)
docker compose up -d

# 3. Tail logs for everything, or a single service
docker compose logs -f
docker compose logs -f api

All services use depends_on with health-check conditions, so the API container will not start until Postgres, Redis, and Elasticsearch are confirmed healthy. On a cold start this typically takes 30–60 seconds.

Stopping and resetting

Wipe warning: docker compose down -v deletes the named volumes postgres-data, redis-data, and elasticsearch-data. Your local database will be empty on the next up. Do this intentionally.

Port map

Connect from your host machine using localhost:<host port>. Inside the Docker network, services reach each other by container name (e.g., postgres:5432).

Persisting data across restarts

Data is stored in named Docker volumes, not in your local filesystem. This means:

• docker compose stop / docker compose up — data survives ✅
• docker compose down (no -v) — data survives ✅
• docker compose down -v — data is deleted ❌

To inspect a volume: docker volume inspect storefront-api_postgres-data

To back up Postgres before wiping:

docker exec storefront-postgres pg_dump -U $POSTGRES_USER $POSTGRES_DB > backup.sql

Troubleshooting

Port conflicts

Symptom: Error starting userland proxy: listen tcp 0.0.0.0:5432: bind: address already in use

Fix: Another process (often a local Postgres installation) is already using that port. Override the host port in .env:

POSTGRES_HOST_PORT=5433

Then docker compose up -d again. No other file needs changing — the API connects over the internal Docker network, not the host port.

Volume permission errors

Symptom: Elasticsearch exits immediately with AccessDeniedException or java.nio.file.AccessDeniedException.

Fix: On Linux, Elasticsearch requires the volume directory to be owned by UID 1000. Run:

docker compose down -v
docker compose up -d

A clean volume is created with correct permissions. If the error persists, check that Docker Desktop (Mac/Windows) has sufficient file-sharing permissions in Settings → Resources → File Sharing.

Health check failures — service never becomes healthy

Symptom: docker compose ps shows a service stuck in health: starting or unhealthy.

Diagnosis steps:

# View raw health check output
docker inspect --format='{{json .State.Health}}' storefront-postgres | jq

# View all container logs
docker compose logs postgres

Common causes:

If a service remains unhealthy after 5 retries, Docker will still start dependent containers — but they will fail to connect. Fix the underlying service first.

API container exits immediately

Symptom: storefront-api exits with code 1 right after npm install.

Fix: The node_modules anonymous volume (/app/node_modules) can get stale. Force a clean install:

docker compose down
docker volume ls | grep node_modules  # identify the volume name
docker volume rm <volume_name>
docker compose up -d

Generated by the ClearPoint Nexus Docker Compose Wizard skill. The compose file mirrors the production service contract; do not extend it for shared staging environments.

This sample illustrates the skill's output format. Names, metrics, and operational details are illustrative unless the artifact explicitly analyzes public information.