Docker Compose — storefront-api local development

⚠️ Development only. This docker-compose.yml is tuned for local development and must never be deployed to production. It exposes ports, uses relaxed auth, and mounts dev tooling that would be a security liability in any real environment.

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

| Goal | Command | |---|---| | Stop containers, keep data | docker compose stop | | Stop and remove containers | docker compose down | | Wipe all data, start completely fresh | docker compose down -v | | Restart a single service | docker compose restart api | | Rebuild after code changes | docker compose up -d --build api |

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

| Service | Container port | Default host port | Env override | |---|---|---|---| | Node API | 3000 | 3000 | API_HOST_PORT | | PostgreSQL | 5432 | 5432 | POSTGRES_HOST_PORT | | Redis | 6379 | 6379 | REDIS_HOST_PORT | | Elasticsearch | 9200 | 9200 | ES_HOST_PORT |

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:

| Service | Likely cause | Fix | |---|---|---| | postgres | Wrong POSTGRES_USER in .env | Ensure .env matches; wipe volume and restart | | redis | REDIS_PASSWORD contains special shell characters | Wrap value in single quotes in .env | | elasticsearch | Not enough memory for the JVM | Increase Docker Desktop memory to ≥ 4 GB in Settings |

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