Docker Compose profiles

ZEON256 2026-06-29

Docker

Instead of maintaining separate compose.yml files for different purposes, you can use Compose profiles to opt services in or out. For example, when developing locally you might only need PostgreSQL running—not the full web stack.

Services without a profile always start. Services with a profile only start when that profile is activated:

services:
  web:
    profiles: ["app"]
    build:
      context: .
      dockerfile: apps/web/Dockerfile.dev
      args:
        VITE_BACKEND_URL: ${VITE_BACKEND_URL:-http://localhost:8000}
    ports:
      - "${WEB_PORT:-8080}:8080"
    depends_on:
      - api

  api:
    profiles: ["app"]
    build:
      context: .
      dockerfile: apps/shortener_api/Dockerfile.dev
    restart: on-failure
    ports:
      - "${API_PORT:-8000}:8000"
    environment:
      HOST: ${API_PUBLIC_HOST:-localhost:8000}
      POSTGRES_HOST: postgres
      POSTGRES_PORT: 5432
      POSTGRES_USER: ${POSTGRES_USER:-urlshort}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-urlshort}
      POSTGRES_DB: ${POSTGRES_DB:-urlshort}
      POSTGRES_POOL_SIZE: ${POSTGRES_POOL_SIZE:-5}
      POSTGRES_ACQUIRE_TIMEOUT: ${POSTGRES_ACQUIRE_TIMEOUT:-30}
    depends_on:
      postgres:
        condition: service_healthy

  postgres:
    image: postgres:18
    container_name: url-shortener-postgres
    environment:
      POSTGRES_USER: ${POSTGRES_USER:-urlshort}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-urlshort}
      POSTGRES_DB: ${POSTGRES_DB:-urlshort}
    ports:
      - "${POSTGRES_PORT:-5432}:5432"
    volumes:
      # postgres:18+ expects the mount at /var/lib/postgresql (data lives in a
      # version-specific subdir); the old /var/lib/postgresql/data path errors out.
      - postgres-data:/var/lib/postgresql
    healthcheck:
      test:
        [
          "CMD-SHELL",
          "pg_isready -h 127.0.0.1 -p 5432 -U ${POSTGRES_USER:-urlshort} -d ${POSTGRES_DB:-urlshort}",
        ]
      interval: 5s
      timeout: 5s
      retries: 5

volumes:
  postgres-data:

Run the full app:

docker compose --profile app up --build

Run only PostgreSQL (no profile needed):

docker compose up -d