D.N. Zaki Zamani
Cara Setup Docker Compose untuk Laravel dan PostgreSQL

Cara Setup Docker Compose untuk Laravel dan PostgreSQL


NEW
docker laravel postgresql devops

Cara setup Docker Compose untuk Laravel dan PostgreSQL adalah salah satu skill penting bagi developer yang ingin environment development-nya konsisten di semua mesin. Tidak ada lagi drama “di laptop gue jalan kok”. Artikel ini akan memandu kamu step-by-step dari nol.

Kenapa Docker Compose untuk Laravel?

Kalau kamu pernah setup XAMPP atau Laragon, kamu pasti tahu rasanya ketika versi PHP beda antara laptop dan server production. Atau ketika PostgreSQL di lokal pakai versi 14, tapi di server sudah versi 16.

Docker Compose menyelesaikan semua itu. Kamu definisikan semua service - PHP, Nginx, PostgreSQL - dalam satu file docker-compose.yml. Siapapun yang clone repo kamu tinggal jalankan satu perintah, dan environment langsung siap.

Keuntungan utamanya:

  • Konsistensi - semua developer pakai environment yang sama persis
  • Isolasi - project A pakai PHP 8.2, project B pakai PHP 8.3, tidak bentrok
  • Reproducible - tinggal docker compose up, selesai
  • Mirip production - bisa pakai image dan konfigurasi yang mendekati server asli

Struktur Project

Sebelum mulai, pastikan Docker dan Docker Compose sudah terinstall. Berikut struktur folder yang akan kita buat:

my-laravel-app/
├── docker/
│   ├── nginx/
│   │   └── default.conf
│   └── php/
│       └── Dockerfile
├── src/                  # Laravel project
├── docker-compose.yml
└── .env

Folder docker/ berisi konfigurasi khusus untuk container. Folder src/ adalah tempat Laravel project kamu.

Membuat Dockerfile untuk PHP

Laravel butuh beberapa extension PHP yang tidak ada di image default. Buat file docker/php/Dockerfile:

FROM php:8.3-fpm

RUN apt-get update && apt-get install -y \
    libpq-dev \
    libzip-dev \
    unzip \
    git \
    curl \
    && docker-php-ext-install pdo_pgsql pgsql zip bcmath \
    && apt-get clean && rm -rf /var/lib/apt/lists/*

COPY --from=composer:latest /usr/bin/composer /usr/bin/composer

WORKDIR /var/www/html

USER www-data

Beberapa hal penting di sini:

  • pdo_pgsql dan pgsql adalah extension wajib untuk koneksi ke PostgreSQL
  • bcmath sering dibutuhkan oleh package Laravel
  • Composer di-copy dari image resminya, jadi selalu dapat versi terbaru
  • USER www-data untuk keamanan - container tidak jalan sebagai root

Konfigurasi Nginx

Buat file docker/nginx/default.conf:

server {
    listen 80;
    server_name localhost;
    root /var/www/html/public;
    index index.php index.html;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass php:9000;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.ht {
        deny all;
    }
}

Perhatikan fastcgi_pass php:9000 - nama php di sini harus sesuai dengan nama service di docker-compose.yml.

Ini bagian utamanya. Buat file docker-compose.yml di root project:

services:
  php:
    build:
      context: .
      dockerfile: docker/php/Dockerfile
    volumes:
      - ./src:/var/www/html
    depends_on:
      - postgres
    networks:
      - app-network

  nginx:
    image: nginx:alpine
    ports:
      - "8080:80"
    volumes:
      - ./src:/var/www/html
      - ./docker/nginx/default.conf:/etc/nginx/conf.d/default.conf
    depends_on:
      - php
    networks:
      - app-network

  postgres:
    image: postgres:16-alpine
    ports:
      - "5432:5432"
    environment:
      POSTGRES_DB: ${DB_DATABASE:-laravel}
      POSTGRES_USER: ${DB_USERNAME:-laravel}
      POSTGRES_PASSWORD: ${DB_PASSWORD:-secret}
    volumes:
      - pgdata:/var/lib/postgresql/data
    networks:
      - app-network

volumes:
  pgdata:

networks:
  app-network:
    driver: bridge

Penjelasan Setiap Service

Service php - ini container utama yang menjalankan PHP-FPM. Volume ./src di-mount ke /var/www/html supaya perubahan kode langsung terdeteksi tanpa rebuild.

Service nginx - web server yang menerima request HTTP di port 8080 dan meneruskannya ke PHP-FPM. Kita pakai image nginx:alpine yang ringan.

Service postgres - database server. Data disimpan di named volume pgdata supaya tidak hilang ketika container di-restart. Environment variable dibaca dari file .env.

Setup Laravel

Sekarang kita install Laravel di folder src/. Jalankan dari root project:

docker compose run --rm php composer create-project laravel/laravel .

Perintah ini menjalankan Composer di dalam container PHP, jadi kamu tidak perlu install PHP atau Composer di mesin lokal.

Setelah Laravel terinstall, edit file src/.env untuk koneksi database:

DB_CONNECTION=pgsql
DB_HOST=postgres
DB_PORT=5432
DB_DATABASE=laravel
DB_USERNAME=laravel
DB_PASSWORD=secret

Perhatikan DB_HOST=postgres - ini adalah nama service di docker-compose.yml, bukan localhost. Docker Compose otomatis membuat DNS internal berdasarkan nama service.

Menjalankan Semuanya

Saatnya menjalankan semua container:

docker compose up -d

Flag -d berarti detached mode - container jalan di background. Cek statusnya:

docker compose ps

Kamu harusnya melihat ketiga service running. Sekarang jalankan migration:

docker compose exec php php artisan migrate

Buka browser dan akses http://localhost:8080. Halaman welcome Laravel seharusnya muncul.

Tips Penting untuk Development

Hot Reload dengan Volume Mount

Karena kita sudah mount ./src ke container, setiap perubahan file PHP langsung terefleksi tanpa perlu rebuild. Tapi kalau kamu mengubah Dockerfile atau menambah extension PHP baru, kamu perlu rebuild:

docker compose up -d --build

Menjalankan Artisan Command

Semua perintah Artisan dijalankan via docker compose exec:

docker compose exec php php artisan make:model Product -m
docker compose exec php php artisan tinker
docker compose exec php php artisan queue:work

Supaya tidak capek mengetik panjang, tambahkan alias di .bashrc:

alias dart='docker compose exec php php artisan'

Sekarang cukup ketik dart migrate atau dart make:controller ProductController.

Akses PostgreSQL via CLI

Kalau butuh akses langsung ke database:

docker compose exec postgres psql -U laravel -d laravel

Debugging dengan Xdebug

Untuk menambahkan Xdebug, tambahkan baris berikut di Dockerfile:

RUN pecl install xdebug && docker-php-ext-enable xdebug
COPY docker/php/xdebug.ini /usr/local/etc/php/conf.d/xdebug.ini

Buat file docker/php/xdebug.ini:

xdebug.mode=debug
xdebug.client_host=host.docker.internal
xdebug.client_port=9003
xdebug.start_with_request=yes

Troubleshooting Umum

Permission denied pada storage/ - ini masalah klasik. Jalankan:

docker compose exec php chmod -R 775 storage bootstrap/cache

Port 5432 sudah dipakai - kalau kamu punya PostgreSQL lokal yang sudah jalan, ubah port mapping di docker-compose.yml:

ports:
  - "5433:5432"

Container postgres terus restart - biasanya karena volume lama punya konfigurasi user/password berbeda. Hapus volume dan buat ulang:

docker compose down -v
docker compose up -d

Hati-hati, flag -v menghapus semua data di volume. Pastikan kamu sudah backup kalau ada data penting.

Penutup

Setup Docker Compose untuk Laravel dan PostgreSQL memang butuh effort di awal. Tapi setelah docker-compose.yml siap, semua orang di tim bisa mulai development dalam hitungan menit. Tidak perlu lagi install PHP, Composer, PostgreSQL, atau Nginx secara manual.

Langkah selanjutnya yang bisa kamu eksplorasi:

  • Tambahkan Redis untuk cache dan queue
  • Setup multi-stage build untuk production image
  • Integrasikan dengan GitHub Actions untuk CI/CD

Selamat mencoba, dan semoga workflow development kamu jadi lebih efisien!

© 2026 D.N. Zaki Zamani