Laravel in a Container

The Dockerized setup

Lesson 1 of 4

What you'll learn

Understand the containers a Laravel + Postgres stack needs
Read a docker-compose.yml and its service wiring
Know how depends_on orders startup and how services find each other

A Dockerized Laravel app is usually three services that talk over a private network:

app — PHP-FPM running your Laravel code
db — Postgres, holding your data
web — Nginx, serving requests to the app

Compose defines them in one file. The key ideas: each service is a container, depends_on controls start order, and services reach each other by service name as a hostname.

# docker-compose.yml
services:
  db:
    image: postgres:16
    environment:
      POSTGRES_DB: app
      POSTGRES_USER: laravel
      POSTGRES_PASSWORD: secret
    volumes:
      - dbdata:/var/lib/postgresql/data   # data survives restarts

  app:
    build: .
    depends_on: [db]
    environment:
      DB_HOST: db        # <-- the service name, not localhost
      DB_DATABASE: app

  web:
    image: nginx:alpine
    depends_on: [app]
    ports:
      - "8080:80"        # host:container

volumes:
  dbdata:

In Laravel's .env, DB_HOST=db — not 127.0.0.1. Inside the Docker network, db resolves to the Postgres container. That one detail trips up everyone the first time.

depends_on isn't health

depends_on starts db before app, but it does not wait for Postgres to be ready to accept connections. Add a healthcheck (or retry in your entrypoint) so the app doesn't race the database on boot.

The challenge resolves container start order from depends_on — the dependency graph Compose walks. Run it.

Resolve start order from depends_on

Run it. A service starts only after everything it depends on. Try adding a dependency and re-running.

Loading editor…

Next: how a request flows through routes and controllers.

Next Routes & controllers