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.