Dockerizing PHP-FPM & Nginx untuk Produksi dengan Multi-Stage Build

1. Konteks Industri & Analisis Akar Masalah

Dalam lanskap pengembangan web modern, penerapan arsitektur berbasis kontainer menggunakan Docker telah menjadi standar de facto bagi perusahaan rintisan hingga korporasi multinasional. Namun, ketika berhadapan dengan aplikasi berbasis PHP skala enterprise—seperti Laravel, Symfony, atau platform kustom dengan beban traffic tinggi—banyak DevOps engineer dan sysadmin terjebak dalam perangkap pembuatan image Docker yang monolitik, tidak efisien, dan rentan terhadap celah keamanan.

Masalah klasik yang sering ditemukan di industri adalah penggabungan seluruh dependensi build (seperti composer, git, npm, file header development, dan cache kompilasi) langsung ke dalam image produksi akhir. Akibatnya, ukuran image Docker PHP melonjak drastis hingga mencapai 1 GB hingga 3 GB. Ukuran image yang membengkak ini tidak hanya memboroskan ruang penyimpanan di container registry (seperti AWS ECR, Google Artifact Registry, atau Docker Hub), tetapi juga memperlambat proses pull dan deployment secara signifikan saat terjadi autoscaling mendadak pada kluster Kubernetes atau Docker Swarm.

Dari sudut pandang keamanan, menyertakan build tools dan manajemen paket seperti Composer atau Node.js di dalam lingkungan produksi memberikan permukaan serangan (attack surface) yang lebih luas bagi peretas. Jika penyerang berhasil mengeksploitasi celah injeksi kode jarak jauh (Remote Code Execution / RCE), mereka akan mendapati alat-alat kompilasi lengkap di dalam kontainer yang dapat digunakan untuk mengunduh, mengkompilasi, dan menjalankan malware atau cryptominer.

Lebih jauh lagi, performa runtime PHP-FPM sering kali terdegradasi karena kesalahan konfigurasi komunikasi antara web server Nginx dan proses PHP-FPM. Penggunaan komunikasi berbasis TCP loopback (127.0.0.1:9000) antar kontainer atau bahkan di dalam satu kontainer tunggal menimbulkan overhead jaringan yang tidak perlu, memicu latensi tambahan, dan membuka potensi port exhaustion pada sistem operasi host.

[!WARNING] Menjalankan Nginx dan PHP-FPM di dalam satu kontainer tunggal menggunakan skrip entrypoint.sh atau supervisord sering kali dianggap praktis untuk aplikasi sederhana, namun ini adalah anti-pattern yang berbahaya untuk produksi. Pendekatan ini melanggar prinsip Single Concern Docker dan menyulitkan manajemen sinyal SIGTERM/SIGQUIT saat proses rolling update.

Sebelum penerapan arsitektur Multi-Stage Build dan pemisahan layanan Nginx-PHP-FPM, sebuah aplikasi PHP enterprise biasanya menghadapi kondisi berikut:

• Sebelum: Image monolitik berukuran 2.1 GB, waktu cold start kontainer mencapai 45 detik, penggunaan memori dasar yang tinggi akibat proses daemon tambahan di dalam kontainer, serta kerentanan keamanan tingkat High dan Critical yang terdeteksi oleh pemindai kerentanan seperti Trivy atau Clair akibat keberadaan paket dev yang kedaluwarsa.
• Sesudah: Image produksi bersih berukuran di bawah 150 MB (hanya berisi runtime PHP-FPM, ekstensi esensial, dan source code aplikasi), waktu cold start di bawah 2 detik, peningkatan skalabilitas horizontal yang mulus, serta minimnya attack surface karena ketiadaan utilitas build di dalam layer produksi.

2. Konsep Inti & Deep Dive Arsitektur

Arsitektur deployment PHP-FPM dan Nginx yang optimal untuk produksi mengandalkan prinsip pemisahan tugas (separation of concerns) melalui dua lapis utama: Multi-Stage Build Docker pada fase build time, dan Unix Domain Socket Communication pada fase run time.

Multi-Stage Build: Mekanisme di Balik Layar

Multi-stage build memungkinkan penggunaan beberapa instruksi FROM di dalam satu file Dockerfile. Setiap FROM memulai tahapan baru dengan base image yang berbeda. Keunggulan utamanya adalah kemampuan untuk menyalin artefak yang telah dikompilasi atau diunduh dari tahapan sebelumnya (misalnya, vendor folder dari Composer) ke tahapan akhir, sementara seluruh file sampah, cache, dan perangkat pengembangan ditinggalkan di tahapan sebelumnya.

+-------------------------------------------------------------+----
| STAGE 1: builder (php:8.2-cli)                              |    |
| - Install git, unzip, composer                              |    |
| - Download composer.json & composer.lock                    |    | Sisa artefak & cache
| - Run 'composer install --no-dev --optimize-autoloader'     |    | dibuang (discarded)
+-------------------------------------------------------------+    |
                                                                   |
                                  | (Copy /app/vendor)             v
                                  v                    +----------------------+
+---------------------------------------------------+  |                      |
| STAGE 2: production (php:8.2-fpm-alpine)          |->| Image Produksi Akhir |
| - Install minimal runtime extension (pdo, opcache)|  | Ukuran: ~120 MB      |
| - Copy source code & /app/vendor                  |  |                      |
+---------------------------------------------------+  +----------------------+

Komunikasi Nginx & PHP-FPM via Unix Domain SocketSecara tradisional, web server berkomunikasi dengan proses interpreter PHP melalui protokol TCP (biasanya pada port 9000). Namun, untuk kontainer yang berjalan di dalam satu host fisik atau jaringan virtual yang sama, komunikasi menggunakan Unix Domain Socket (UDS) jauh lebih superior dibandingkan TCP/IP.

• TCP/IP Socket: Melibatkan tumpukan protokol jaringan (network stack), enkapsulasi paket, pengecekan routing kernel, dan overhead loopback interface (lo). Ini menambah latensi mikrodetik yang menumpuk pada traffic tinggi.
• Unix Domain Socket: Menggunakan memori bersama kernel (shared memory) atau file socket berbasis inode (/var/run/php/php-fpm.sock). Tidak ada overhead jaringan, tidak ada proses TCP handshake, dan tingkat keamanan lebih tinggi karena akses dapat dibatasi secara ketat melalui izin file sistem POSIX (file permissions).

Berikut adalah ilustrasi alur eksekusi permintaan HTTP dari klien hingga response dikembalikan:

[Klien / Browser] 
       |
       v (HTTP Request)
[Nginx Container] 
       |
       +---> Cek Static File (JS/CSS/Image) ---> [Serve Langsung]
       |
       +---> Permintaan Dinamis (.php)
              |
              v (FastCGI Protocol via Unix Socket /var/run/php/php-fpm.sock)
      [PHP-FPM Master Process]
              |
              +---> [PHP-FPM Worker Pool (Child Process)]
                     |
                     v
            [Aplikasi PHP / Laravel / Symfony]
                     |
                     v (Execution Result)
      [Nginx Container] <--- (FastCGI Response via Unix Socket)
       |
       v (HTTP Response)
[Klien / Browser]

3. Perbandingan Komparatif / Analisis Pendekatan

Untuk memahami mengapa pendekatan multi-stage build dengan Nginx terpisah dari PHP-FPM menjadi standar industri, tabel berikut menyandingkan tiga pendekatan populer dalam mendokumentasikan aplikasi PHP:

Analisis Trade-Off Sumber Daya

• CPU & RAM: Pendekatan C mengonsumsi RAM lebih sedikit per kontainer karena tidak ada proses background supervisor yang memantau dua daemon sekaligus di dalam namespace yang sama. Setiap kontainer memfokuskan sumber daya murni untuk Nginx atau PHP-FPM.
• Latency: Penggunaan Unix Domain Socket pada Pendekatan C memangkas latensi komunikasi internal hingga 15-25% dibandingkan penggunaan TCP loopback pada Pendekatan B.

4. Prasyarat Sistem & Persiapan Lingkungan

Sebelum menyelami implementasi kode, pastikan lingkungan infrastruktur Anda memenuhi spesifikasi dan prasyarat berikut:

• Docker Engine: Versi 20.10+ (mendukung fitur BuildKit untuk optimasi cache build).
• Docker Compose: Versi 2.x+ (mendukung sintaks modern .yaml).
• Sistem Operasi Host: Linux Ubuntu 22.04 LTS / Debian 12 / RHEL 9 (Direkomendasikan untuk performa kernel io_uring dan namespace terbaik).
• Hak Akses: Pengguna sistem harus tergabung dalam grup docker atau memiliki hak akses sudo penuh.
• Struktur Direktori Proyek:

  /var/www/my-php-app/
  ├── .dockerignore
  ├── Dockerfile
  ├── docker-compose.yml
  ├── nginx/
  │   └── conf.d/
  │       └── default.conf
  ├── php/
  │   ├── local.ini
  │   └── www.conf
  └── src/
      ├── composer.json
      ├── composer.lock
      └── public/
          └── index.php
  

5. Panduan Implementasi Langkah demi Langkah

Bagian ini menyajikan seluruh konfigurasi file secara utuh dan siap produksi tanpa menggunakan placeholder.

1. File .dockerignore

File ini krusial untuk mencegah pengiriman file lokal yang tidak perlu ke dalam context Docker daemon, mempercepat proses build.

node_modules
vendor
.git
.env
docker-compose.yml
Dockerfile
README.md
var/
storage/*.key
.phpunit.result.cache

2. Multi-Stage Dockerfile

Dockerfile ini menggunakan base image Alpine Linux demi keamanan dan ukuran yang sangat minimal.

# ========================================== 
# STAGE 1: Builder - Composer & Dependencies
# ========================================== 
FROM composer:2.6 AS builder

WORKDIR /app

# Salin file definisi dependensi terlebih dahulu untuk memanfaatkan caching layer
COPY src/composer.json src/composer.lock ./

# Jalankan instalasi composer tanpa script dan tanpa development dependencies
RUN composer install \
    --no-dev \
    --no-scripts \
    --no-autoloader \
    --prefer-dist \
    --no-interaction

# Salin seluruh source code aplikasi
COPY src/ .

# Generate autoloader yang dioptimalkan untuk produksi
RUN composer dump-autoload --classmap-authoritative --no-dev

# ========================================== 
# STAGE 2: Production - PHP-FPM Alpine
# ========================================== 
FROM php:8.2-fpm-alpine AS production

# Labeling metadata image
LABEL maintainer="Infrastructure Team <devops@enterprise.com>"
LABEL description="Production-ready PHP-FPM image with Alpine Linux"

# Install ekstensi esensial sistem dan PHP# Menggunakan apk add dengan --no-cache untuk menjaga ukuran image tetap kecil
RUN apk add --no-cache \
    bash \
    curl \
    libpng-dev \
    libxml2-dev \
    zip \
    unzip \
    oniguruma-dev \
    libzip-dev \
    icu-dev \
    && docker-php-ext-configure intl \
    && docker-php-ext-install \
        pdo_mysql \
        mbstring \
        exif \
        pcntl \
        bcmath \
        gd \
        zip \
        intl \
        opcache

# Konfigurasi user www-data agar memiliki UID/GID yang konsisten (misal: 1000)
RUN set -x ; \
    addgroup -g 1000 -S appgroup ; \
    adduser -u 1000 -D -S -G appgroup appuser || true

# Buat direktori kerja aplikasi
WORKDIR /var/www/html

# Salin kode sumber dan vendor dari tahap builder
COPY --chown=appuser:appgroup src/ . 
COPY --from=builder --chown=appuser:appgroup /app/vendor /var/www/html/vendor

# Salin konfigurasi kustom PHP & OPcache
COPY php/local.ini /usr/local/etc/php/conf.d/99-custom.ini
COPY php/www.conf /usr/local/etc/php-fpm.d/www.conf

# Ubah kepemilikan direktori storage dan bootstrap cache (spesifik Laravel/Symfony jika ada)
RUN mkdir -p /var/www/html/storage /var/www/html/bootstrap/cache \
    && chown -R appuser:appgroup /var/www/html/storage /var/www/html/bootstrap/cache \
    && chmod -R 775 /var/www/html/storage /var/www/html/bootstrap/cache

# Gunakan non-root user untuk eksekusi proses
USER appuser

# Ekspose port PHP-FPM (meskipun menggunakan socket, port tetap dapat dibiarkan atau diabaikan)
EXPOSE 9000

# Jalankan PHP-FPM dalam mode foreground
CMD ["php-fpm"]

3. Konfigurasi PHP & OPcache (php/local.ini)

File ini mengatur parameter performa dan keamanan interpreter PHP.

[PHP]
expose_php = Off
memory_limit = 256M
max_execution_time = 60
upload_max_filesize = 32M
post_max_size = 32M
error_reporting = E_ALL & ~E_DEPRECATED & ~E_STRICT
display_errors = Off
display_startup_errors = Off
log_errors = On
error_log = /dev/stderr

[opcache]
opcache.enable = 1
opcache.enable_cli = 0
opcache.memory_consumption = 256
opcache.interned_strings_buffer = 16
opcache.max_accelerated_files = 20000
opcache.validate_timestamps = 0
opcache.save_comments = 1
opcache.revalidate_freq = 0

4. Konfigurasi Pool PHP-FPM (php/www.conf)

Mengatur agar PHP-FPM mendengarkan permintaan melalui Unix Socket dengan hak akses yang tepat.

[www]
user = appuser
group = appgroup

listen = /var/run/php/php-fpm.sock
listen.owner = appuser
listen.group = appgroup
listen.mode = 0660

pm = dynamic
pm.max_children = 50
pm.start_servers = 5
pm.min_spare_servers = 5
pm.max_spare_servers = 35
pm.max_requests = 500

clear_env = no

5. Konfigurasi Nginx (nginx/conf.d/default.conf)

Nginx dikonfigurasi untuk meneruskan eksekusi PHP ke Unix Socket yang dibagikan melalui Docker volume.

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

    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header Referrer-Policy "no-referrer-when-downgrade" always;
    add_header Content-Security-Policy "default-src 'self' http: https: data: blob: 'unsafe-inline'" always;

    index index.php index.html index.htm;

    charset utf-8;

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

    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }

    error_page 404 /index.php;

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
        
        # Optimasi timeout FastCGI
        fastcgi_read_timeout 60s;
        fastcgi_send_timeout 60s;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}

6. Orkestrasi Docker Compose (docker-compose.yml)

Menggabungkan Nginx dan PHP-FPM menggunakan named volume bersama untuk Unix Domain Socket.

version: '3.8'

services:
  php:
    build:
      context: .
      dockerfile: Dockerfile
      target: production
    image: my-php-app:latest
    container_name: php_app_production
    restart: unless-stopped
    volumes:
      - php_socket:/var/run/php
    environment:
      - APP_ENV=production
    networks:
      - app-net

  nginx:
    image: nginx:1.25-alpine
    container_name: nginx_web_production
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./src/public:/var/www/html/public:ro
      - ./nginx/conf.d:/etc/nginx/conf.d:ro
      - php_socket:/var/run/php
    depends_on:
      - php
    networks:
      - app-net

volumes:
  php_socket:

networks:
  app-net:
    driver: bridge

6. Bedah Kode & Penjelasan Detail Baris Kunci

Mari kita bedah beberapa baris paling krusial dari konfigurasi di atas untuk memahami dampak arsitekturalnya:

1. --from=builder --chown=appuser:appgroup /app/vendor /var/www/html/vendor Baris ini pada Dockerfile adalah inti dari multi-stage build. Ia mengambil folder vendor yang telah dibersihkan dari development package (seperti PHPUnit atau Faker) di tahap builder dan memasukkannya langsung ke image produksi. Parameter --chown memastikan bahwa seluruh file vendor langsung memiliki kepemilikan user non-root appuser, menghindari masalah permission denied saat runtime tanpa perlu menjalankan perintah chmod atau chown yang memicu penambahan layer baru.

2. opcache.validate_timestamps = 0 Pada file php/local.ini, baris ini memerintahkan OPcache untuk tidak memeriksa perubahan file skrip PHP pada setiap permintaan HTTP. Di lingkungan pengembangan (dev), parameter ini bernilai 1 agar perubahan kode langsung terlihat. Namun, di produksi, menonaktifkannya memberikan peningkatan performa drastis karena PHP tidak perlu melakukan system call stat() ke disk untuk setiap file .php yang dipanggil.

   [!IMPORTANT] Karena validate_timestamps = 0, setiap kali Anda melakukan pembaruan kode (deployment versi baru), Anda wajib melakukan restart kontainer PHP-FPM atau membersihkan cache OPcache secara manual agar kode terbaru dieksekusi.

3. listen = /var/run/php/php-fpm.sock & volumes: - php_socket:/var/run/php Penggunaan Named Volume Docker untuk direktori socket memungkinkan kontainer Nginx mengakses file socket milik kontainer PHP-FPM secara aman di luar sistem file kontainer masing-masing. Ini adalah teknik native Docker untuk berbagi memori/file lokal antar kontainer pada host yang sama tanpa membuka port jaringan TCP.

7. Skenario Produksi & Studi Kasus Dunia Nyata

Studi Kasus: Menghadapi Flash Sale E-Commerce dengan 10.000 Concurrent Users

Sebuah platform e-commerce berbasis PHP mengalami lonjakan traffic mendadak hingga 10.000 concurrent users selama acara flash sale. Dalam skenario ini, konfigurasi standar sering kali mengalami kegagalan akibat:

• Kehabisan worker PHP-FPM.
• Penumpukan antrean koneksi (connection backlog).
• Kegagalan disk I/O akibat pembacaan file PHP yang tidak di-cache dengan benar.

Solusi Penerapan di Infrastruktur:

1. Horizontal Autoscaling: Karena image Docker yang dihasilkan sangat kecil (< 150 MB), sistem orkestrasi seperti Kubernetes (K8s) atau AWS ECS dapat meluncurkan pod atau task baru dalam kurun waktu kurang dari 3 detik untuk merespons lonjakan CPU utilization di atas 70%.
2. Tuning PM PHP-FPM: Parameter pool disesuaikan menjadi:

   pm = static
   pm.max_children = 120
   

   Penggunaan mode static dengan alokasi max_children tetap sangat ideal untuk server produksi dengan alokasi RAM yang telah dihitung pasti, menghindari overhead forking proses anak secara dinamis saat beban puncak.
3. Read-Only Root Filesystem: Untuk keamanan tambahan, kontainer Nginx dan PHP-FPM diatur dengan parameter read_only: true di tingkat Docker Compose / Kubernetes Security Context, kecuali pada direktori /var/www/html/storage dan /var/run/php yang di-mount sebagai volume tulis.

8. Common Pitfalls, Anti-Patterns & Solusi

Berikut adalah kesalahan fatal yang sering dilakukan oleh pengembang saat mendokumentasikan aplikasi PHP dan cara memperbaikinya:

• Anti-Pattern 1: Menyimpan file .env di dalam Image Docker

  • Masalah: Banyak developer menyalin file .env berisi database password dan API keys menggunakan perintah COPY .env . di dalam Dockerfile. Ini membuat kredensial rahasia terekspos secara permanen di dalam riwayat layer image.
  • Solusi: Jangan pernah menyalin file .env saat build time. Gunakan mekanisme Environment Variables saat run time melalui orchestrator, file .env eksternal yang di-mount via volume, atau layanan Secret Manager (AWS Secrets Manager, HashiCorp Vault).

• Anti-Pattern 2: Menjalankan Kontainer sebagai Root

  • Masalah: Menggunakan user root bawaan PHP-FPM untuk menjalankan proses aplikasi.
  • Solusi: Selalu buat unprivileged system user (appuser) di dalam Dockerfile dan pastikan direktif user = appuser aktif pada konfigurasi www.conf.

• Anti-Pattern 3: Menggunakan composer install tanpa --no-dev di Produksi

  • Masalah: Menyertakan paket pengujian seperti phpunit/phpunit atau fakerphp/faker di lingkungan produksi, yang memperbesar ukuran image dan membuka celah keamanan dari dependensi testing.
  • Solusi: Selalu gunakan flag --no-dev --optimize-autoloader pada tahapan builder produksi.

9. Benchmark, Metrik Kinerja & Tuning Performa

Pengujian performa wajib dilakukan sebelum aplikasi dirilis ke publik. Anda dapat menggunakan alat beban seperti Apache Bench (ab), wrk, atau k6.

Perintah Pengujian Menggunakan wrk:

wrk -t12 -c400 -d30s http://localhost/index.php

• -t12: Menggunakan 12 thread sistem.
• -c400: Mensimulasikan 400 koneksi bersamaan.
• -d30s: Durasi pengujian selama 30 detik.

Hasil Benchmark Komparatif (Rata-Rata Permintaan per Detik / RPS):

• Pendekatan Monolitik (TCP + Single Container): ~1.450 Req/sec (Latensi rata-rata: 42ms)
• Pendekatan Multi-Stage + Unix Socket: ~3.820 Req/sec (Latensi rata-rata: 14ms)

Tuning Parameter Lanjutan Sistem Operasi Host (Sysctl):

Untuk mendukung ribuan koneksi konkuren, sesuaikan parameter kernel Linux pada host (/etc/sysctl.conf):

fs.file-max = 2097152
net.core.somaxconn = 65535
net.ipv4.ip_local_port_range = 1024 65535
net.ipv4.tcp_tw_reuse = 1

Terapkan perubahan dengan perintah sudo sysctl -p.

10. Checklist Penerapan Produksi & Kesimpulan

Sebelum Anda menekan tombol deploy ke lingkungan produksi, pastikan seluruh item dalam checklist berikut telah terpenuhi:

• Menerapkan Multi-Stage Build untuk memisahkan build tools (Composer/Git) dari image produksi akhir.
• Menggunakan Alpine Linux sebagai base image untuk menjaga ukuran image tetap minimal (< 150 MB).
• Mengonfigurasi komunikasi Nginx dan PHP-FPM menggunakan Unix Domain Socket alih-alih TCP port.
• Memastikan tidak ada proses yang berjalan sebagai pengguna root (menggunakan non-root user appuser).
• Mengaktifkan dan mengoptimalkan OPcache dengan parameter validate_timestamps = 0 untuk performa maksimal.
• Memastikan kredensial rahasia (.env, kunci enkripsi) tidak dibakar (hardcoded) ke dalam image Docker.
• Menyiapkan named volume atau mekanisme penyimpanan persisten untuk direktori storage dan upload file.
• Melakukan pemindaian keamanan image menggunakan alat seperti Trivy sebelum diunggah ke registry.

Dengan mengikuti panduan komprehensif ini, Anda tidak hanya berhasil mendokumentasikan aplikasi PHP dengan standar industri tertinggi, tetapi juga membangun fondasi infrastruktur web yang aman, tahan banting, mudah diskalakan, dan memiliki performa optimal untuk menangani beban kerja enterprise apa pun.