Docker & Makefile Skill

This skill provides guidance for managing the Family Plan development environment using Docker Compose and Makefile commands.

Docker Services Overview

frontend

nginx

php

database

mailpit

node

Essential Make Commands

Service Management

# Start all services
make up

# Stop all services
make down

# Restart services
make restart

# View service status
docker compose ps

# Full cleanup (removes volumes)
make clean

Initial Setup

# Complete project setup (first time)
make setup
# This runs: up -> install -> db-migrate -> create-admin

# Initialize development environment
make init

# Install all dependencies
make install

Database Operations

# Run database migrations
make db-migrate

# Reset database (drop + create + migrate)
make db-reset

# Generate new migration from entity changes
make db-diff

# Direct database access
make shell-db
# Then: \dt to list tables, \d+ table_name for schema

Testing

# Run all backend tests (PHPUnit + Behat)
make backend-test

# Run only PHPUnit tests
make phpunit

# Run only Behat acceptance tests
make behat

# Run frontend E2E tests
make frontend-test

# Run all tests
make test

Shell Access

# PHP container shell
make shell-php
# or: make shell

# Database shell (psql)
make shell-db

# Frontend container shell
docker compose exec frontend sh

Code Quality

# Run PHP linter (PHP-CS-Fixer)
make lint

# Auto-fix linting issues
make lint-fix

Logs and Debugging

# All service logs
docker compose logs -f

# Specific service logs
docker compose logs -f php
docker compose logs -f frontend
docker compose logs -f database
docker compose logs -f nginx

# Last 100 lines
docker compose logs --tail=100 php

Docker Compose Configuration

compose.yaml Structure

services:
  database:
    image: postgres:16-alpine
    ports:
      - "5432:5432"
    environment:
      POSTGRES_DB: app
      POSTGRES_USER: app
      POSTGRES_PASSWORD: "!ChangeMe!"
    volumes:
      - database_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "app"]
      interval: 10s
      timeout: 5s
      retries: 5

  php:
    build:
      context: .
      target: app_php_dev
    depends_on:
      database:
        condition: service_healthy
    volumes:
      - .:/srv/app
    environment:
      DATABASE_URL: postgresql://app:!ChangeMe!@database:5432/app

  nginx:
    build:
      context: .
      target: app_nginx
    depends_on:
      - php
    ports:
      - "8080:80"

  frontend:
    build:
      context: ./frontend
    ports:
      - "3000:3000"
    volumes:
      - ./frontend:/app
      - /app/node_modules
    environment:
      - CHOKIDAR_USEPOLLING=true

  mailpit:
    image: axllent/mailpit
    ports:
      - "8025:8025"
      - "1025:1025"

volumes:
  database_data:

Common Tasks

Rebuilding Containers

# Rebuild all containers
docker compose build

# Rebuild specific service
docker compose build php

# Rebuild without cache
docker compose build --no-cache php

# Rebuild and restart
docker compose up -d --build

Executing Commands in Containers

# Run command in PHP container
docker compose exec php <command>

# Examples:
docker compose exec php composer install
docker compose exec php php bin/console cache:clear
docker compose exec php vendor/bin/phpunit
docker compose exec php vendor/bin/behat

# Run command in frontend container
docker compose exec frontend npm install
docker compose exec frontend npm run build

Database Management

# Create database backup
docker compose exec database pg_dump -U app app > backup.sql

# Restore database
docker compose exec -T database psql -U app app < backup.sql

# Run SQL query
docker compose exec database psql -U app -d app -c "SELECT * FROM users;"

Clearing Caches

# Symfony cache
docker compose exec php php bin/console cache:clear

# Clear all caches (dev)
docker compose exec php php bin/console cache:clear --env=dev

# Clear Doctrine cache
docker compose exec php php bin/console doctrine:cache:clear-metadata
docker compose exec php php bin/console doctrine:cache:clear-query
docker compose exec php php bin/console doctrine:cache:clear-result

Troubleshooting

Service Won't Start

# Check logs for errors
docker compose logs php

# Verify dependencies are healthy
docker compose ps

# Restart specific service
docker compose restart php

Database Connection Issues

# Check if database is ready
docker compose exec database pg_isready -U app

# Check database logs
docker compose logs database

# Reset database container
docker compose down -v  # WARNING: destroys data
docker compose up -d database
make db-migrate

Permission Issues

# Fix file permissions (Linux)
sudo chown -R $(id -u):$(id -g) .

# In container
docker compose exec php chown -R www-data:www-data var/

Port Conflicts

# Check what's using a port
lsof -i :8080
lsof -i :3000

# Stop conflicting service or change port in compose.yaml

Memory Issues

# Check container resources
docker stats

# Increase Docker memory allocation in Docker Desktop settings

Environment Variables

Backend (.env)

APP_ENV=dev
APP_SECRET=your-secret-key
DATABASE_URL="postgresql://app:!ChangeMe!@database:5432/app"
SUPER_ADMIN_EMAIL=admin@example.com
SUPER_ADMIN_PASSWORD=admin123
CORS_ALLOWED_ORIGIN=http://localhost:3000
MAILER_DSN=smtp://mailpit:1025

Frontend (frontend/.env)

REACT_APP_API_URL=http://localhost:8080

Performance Tips

1. Use named volumes - Faster than bind mounts for dependencies
2. Exclude node_modules - Use anonymous volume to avoid syncing
3. Enable BuildKit -

   DOCKER_BUILDKIT=1 docker compose build

4. Use .dockerignore - Exclude unnecessary files from build context
5. Health checks - Ensure services start in correct order

Quick Reference

make up

make down

make test

make shell-db

make shell-php

docker compose logs -f

make db-migrate

make clean && make setup