Local Website Development with Docker Compose: Complete Setup

How Docker Compose Simplifies Local Development

Developers waste up to 30% of their time setting up environments: version conflicts with PHP, differences between PostgreSQL on macOS and Windows, ports occupied by other services. Docker Compose solves this with a single configuration file. According to the documentation: Docker Compose is a tool for defining and running multi-container applications Docker Compose documentation. We configure such a docker-compose.yml that spins up the entire stack with one command. Forget manual service management — everything is reproducible and automated.

Typical scenario: a developer clones the repository, runs make up, and within 5 minutes is already working with Laravel, PostgreSQL, and Redis. No more brew/apt witchcraft or manual installations. A consistent environment for the entire team — and no more "it works on my machine".

Not long ago, a team of 5 developers approached us: each spent up to 4 hours setting up MAMP for their project, and when switching between tasks, version conflicts for PHP and PostgreSQL arose. After implementing Docker Compose, deployment time dropped to 10 minutes, and environment-related errors decreased by 80%. This concrete example shows how much more efficient containerization is compared to traditional tools.

Problems We Solve

• Version Hell: PHP 8.1 on one project, 8.3 on another — switching via brew/apt breaks dependencies. Docker isolates each project in its own container, allowing any version without conflicts.
• Healthcheck Dependencies: without depends_on with condition, services start chaotically — the app crashes until PostgreSQL is ready. The solution is to add healthcheck verifying database readiness via pg_isready.
• File Permissions: files created inside the container belong to root — on the host, you can't edit them. The solution is to map UID/GID in the Dockerfile via build arguments.

These issues are typical for teams moving to Docker. Our experience shows that properly solving them cuts onboarding time for new developers from 2 days to 20 minutes.

Why Docker Compose Is Faster Than XAMPP

Docker Compose wins by 5x in setup time for a team of 3 developers. Additionally, it reduces infrastructure costs: you use only the resources the project needs, rather than maintaining a global stack.

How We Do It

Our standard stack: PHP 8.3, PostgreSQL 16, Redis 7, Vite. We use docker/dev/Dockerfile with Composer and pdo_pgsql. For hot reload, we mount code via volumes, excluding vendor and node_modules. A Makefile simplifies commands: make up, make artisan, make test.

Case study: a Laravel 11 project with Vite. Previously developers used MAMP — the database crashed under load, Redis didn't work out of the box. We migrated to Docker Compose in 4 hours. Environment setup time for a new developer dropped from 2 days to 20 minutes. Additionally, we configured Xdebug via docker-compose.override.yml, speeding up debugging by 50%.

How to Set Up Hot Reload with Vite?

For Vite in Docker Compose, you need to forward port 5173 and use the --host flag. In our example, the vite service runs npm run dev -- --host. This allows hot reload to work on the host via localhost:5173. One important note: ensure that in vite.config.js you don't set strictPort and that server.hmr is configured to '0.0.0.0'. Otherwise HMR won't work inside the container.

Work Process

1. Analysis — determine the stack, versions, and project specifics.
2. Design — write docker-compose.yml, Dockerfile, Makefile.
3. Implementation — configure healthcheck, volumes, environment variables.
4. Testing — verify startup, migrations, Vite hot reload.
5. Deployment — deliver instructions and Makefile to the team.

What's Included

• docker-compose.yml with services: app, vite, db, redis, mailpit, adminer
• Dockerfile for dev environment (PHP 8.3, Composer, pdo_pgsql)
• Makefile with commands: up/down/shell/artisan/test
• docker-compose.override.yml for Xdebug
• Team instructions (README)
• 1 month of support after delivery

Docker Compose Setup Stages

Typical Setup Mistakes (and How to Avoid Them)

• Use depends_on with condition: service_healthy — otherwise the app starts before the DB is ready.
• Always mount vendor and node_modules as anonymous volumes — otherwise they get overwritten from the container.
• On macOS, add extra_hosts for Xdebug: host.docker.internal.
• Ensure host ports are not occupied: check via lsof -i :5432.

Example Configuration

services:
  app:
    build:
      context: .
      dockerfile: docker/dev/Dockerfile
    ports:
      - "8000:8000"
    volumes:
      - .:/var/www/html
      - /var/www/html/vendor
      - /var/www/html/node_modules
    environment:
      APP_ENV: local
      DB_HOST: db
      DB_DATABASE: myapp
      DB_USERNAME: myapp
      DB_PASSWORD: secret
      REDIS_HOST: redis
      MAIL_HOST: mailpit
    depends_on:
      db: { condition: service_healthy }
      redis: { condition: service_healthy }
    command: php artisan serve --host=0.0.0.0 --port=8000

  vite:
    image: node:20-alpine
    working_dir: /app
    volumes:
      - .:/app
      - /app/node_modules
    ports:
      - "5173:5173"
    command: npm run dev -- --host

  db:
    image: postgres:16-alpine
    ports:
      - "5432:5432"
    environment:
      POSTGRES_DB: myapp
      POSTGRES_USER: myapp
      POSTGRES_PASSWORD: secret
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U myapp"]
      interval: 5s
      timeout: 3s
      retries: 5

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s

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

  adminer:
    image: adminer:latest
    ports:
      - "8080:8080"
    environment:
      ADMINER_DEFAULT_SERVER: db
    depends_on: [db]

volumes:
  postgres_data:

# docker/dev/Dockerfile
FROM php:8.3-cli

RUN apt-get update && apt-get install -y \
    git curl zip unzip libpq-dev \
    && docker-php-ext-install pdo_pgsql \
    && curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer

WORKDIR /var/www/html

# Makefile
.PHONY: up down shell artisan

up:
    docker compose up -d --build
    @echo "App: http://localhost:8000"
    @echo "Mail: http://localhost:8025"
    @echo "DB UI: http://localhost:8080"

down:
    docker compose down

shell:
    docker compose exec app bash

artisan:
    docker compose exec app php artisan $(filter-out $@,$(MAKECMDGOALS))

tinker:
    docker compose exec app php artisan tinker

test:
    docker compose exec app php artisan test --parallel

migrate:
    docker compose exec app php artisan migrate

fresh:
    docker compose exec app php artisan migrate:fresh --seed

npm:
    docker compose exec vite npm $(filter-out $@,$(MAKECMDGOALS))

After running make up, the application is available at localhost:8000, Mailpit at localhost:8025, Adminer at localhost:8080. To execute Artisan commands, use make artisan <command>, e.g., make artisan make:model Product -mcr.

Override for Different Environments

# docker-compose.override.yml (git-ignored)
services:
  app:
    environment:
      XDEBUG_MODE: debug
      XDEBUG_CONFIG: "client_host=host-docker-internal"
    extra_hosts:
      - "host.docker.internal:host-gateway"

For optional services, use profiles: docker compose --profile tools up starts, for example, redis-commander.

Timeline and Cost

Setting up a typical stack (PHP + PostgreSQL + Redis + Vite) takes 1 day. Complex configurations (multiple projects, custom images) take up to 3 days. Cost is calculated individually. Order Docker Compose setup for your project — it will save your team time and reduce headaches. Get a consultation right now.

About our experience: over 5 years in the market, 20+ successful Docker projects, 10 senior-level engineers. We guarantee compatibility with any infrastructure.

We regularly encounter a situation: "The site is not opening" at 3 a.m. — and it turns out that the VPS disk is full because nginx logs haven't been rotated for six months. Or the server went down under load on the day of an advertising campaign launch because the shared hosting had a limit of 50 concurrent connections. Setting up hosting and deployment is not about "where it's cheaper" but about what happens when something goes wrong. Our team helps avoid such incidents by designing infrastructure that accounts for real load patterns.

When to choose Vercel and Netlify?

Vercel is built for Next.js — deploy in one push, preview deployments for every PR, automatic CDN, Edge Functions, ISR without configuration. For frontend projects and JAMstack, it's the optimal choice: no operational overhead, time-to-deploy measured in minutes.

Real limitations: Vercel Serverless Functions run in us-east-1 by default (latency for Europe +80–100ms), Function timeout 300 seconds on Pro, Bandwidth 1TB/month on Pro. For heavy backend, you need workers or a separate server.

Netlify is closer to static sites and Edge Functions based on Deno Deploy. Build minutes are the main limitation on the free tier.

Why is Docker the foundation of predictable deployment?

"It works on my machine" — classic. Docker solves this through environment containerization. But a bad Dockerfile creates new problems.

A typical mistake: copying everything into the image without .dockerignore, resulting in an 800MB image instead of 80MB. node_modules inside the image weighs as much. Correct approach: multi-stage build.

FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build

FROM node:20-alpine AS runner
WORKDIR /app
COPY --from=builder /app/.next ./.next
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./package.json
EXPOSE 3000
CMD ["npm", "start"]

Final image: 180MB instead of 1.2GB. CI build time is reduced due to layer caching — if package.json hasn't changed, the layer with npm ci is taken from cache.

Docker Compose for local development and simple production scenarios: application + PostgreSQL + Redis in one configuration. For production on a single server, it's a perfectly viable option if there's no requirement for horizontal scaling.

More about containerization — Wikipedia: Docker.

How to set up Nginx as a reverse proxy?

Nginx in front of the application is standard for VPS and dedicated servers. Main functions: SSL termination, gzip, static files, rate limiting, upstream load balancing.

A configuration often done incorrectly: worker_processes auto — number of processes equals CPU count. worker_connections 1024 — that's 1024 per worker process. With 4 CPUs and 1024 connections = 4096 concurrent connections. For a high-traffic site, you need worker_connections 4096 and set keepalive_timeout 65.

For static assets with hash in the filename:

location ~* \.(js|css|woff2|png|webp)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
}

immutable tells the browser: don't revalidate this file even on hard refresh. This only works correctly with content-hashed filenames (which Vite/webpack do by default). Documentation — Wikipedia: Nginx.

AWS: flexibility and complexity

EC2 + Auto Scaling Group — classic for horizontal scaling. AMI with pre-installed application, Launch Template, ASG with min/desired/max instances, Application Load Balancer. When CPU > 70% for 3 minutes — scale out, when CPU < 30% for 15 minutes — scale in. Health check via ALB removes unhealthy instances from rotation.

ECS Fargate — containers without managing EC2. Deploy a Docker image, specify CPU/memory (512 CPU units = 0.5 vCPU, from 512MB memory), Fargate launches it. More expensive than Lambda, but no cold start and no timeout limitations. Suitable for long-running processes, WebSocket servers, heavy workers.

RDS for PostgreSQL with Multi-AZ: automatic failover in 1–2 minutes when primary fails. Read Replicas for scaling reads. RDS Proxy for connection pooling — Lambda functions cannot hold long-term connections, the proxy buffers this.

Kubernetes: when it is justified

K8s adds significant operational complexity. Justified when: multiple teams deploy independent services, fine-grained resource allocation per service is needed, canary deployments and blue/green without downtime are required.

AWS EKS, GKE, or managed k8s from Hetzner (cheaper). Helm charts for standard services. Horizontal Pod Autoscaler based on CPU and custom metrics (RPS via Prometheus).

For most startups and medium-sized projects, Kubernetes is overkill. ECS or Fly.io provide 80% of the capabilities with 20% of the operational complexity.

Monitoring and alerting

A server without monitoring is waiting for an incident. Minimal stack: Prometheus + Grafana (or Grafana Cloud for managed), alerting on disk > 80%, memory > 85%, CPU > 90% over 5 minutes, error rate > 1%. Uptime via Better Uptime or Upptime (self-hosted).

Logs: Loki + Grafana or CloudWatch Logs Insights. Structured JSON logs (winston, pino) are mandatory — otherwise, log searching becomes a pain.

What is included in hosting setup

• Audit of current infrastructure and load profiling
• Selection of target architecture (VPS, AWS, serverless, Kubernetes)
• Setting up CI/CD pipeline (GitHub Actions, GitLab CI) with automatic deployment
• IaC via Terraform or Pulumi (infrastructure as code)
• Configuration of Nginx, SSL certificates, HTTP/2, brotli
• Monitoring and alerting (Prometheus + Grafana, PagerDuty)
• Documentation of runbooks and team training

Additionally, contact us if you need migration from current hosting or integration with external services.

Work process

1. Audit of current infrastructure (2–5 days)
2. Selection of target architecture with load and budget justification (1–3 days)
3. Setting up CI/CD pipeline (GitHub Actions, GitLab CI) (2–5 days)
4. IaC via Terraform or Pulumi (3–10 days)
5. Setting up monitoring and alerting (2–5 days)
6. Documentation of runbooks and team training (1–3 days)

Our experience — 7 years on the market, over 50 projects, guarantee of operability after deployment.

Timeline

• Basic deployment on VPS with Docker + Nginx + CI/CD: 1–2 weeks.
• Setting up AWS infrastructure with Auto Scaling, RDS, CDN: 3–6 weeks.
• Migration to EKS from scratch: 6–12 weeks.
• Setting up Vercel/Netlify for JAMstack: 3–5 days.

The cost is calculated individually depending on complexity and scope of work. Get a consultation — we'll evaluate your architecture in one day.