← Back

404 CSS di Production: Ketika 'Build Success' Bukan Berarti Jalan

cloudflare debugging deploy django docker nginx ops static whitenoise

404 CSS di Production: Ketika "Build Success" Bukan Berarti Jalan

Build Jenkins sukses, container restart tanpa error, deployment "selesai" — dan perasaan senang itu langsung pecah saat kubuka production: CSS-nya 404. GET https://skilltrace.codenest.id/static/css/skilltrace.c2c348b9adcb.css → 404 dengan server: cloudflare, cf-cache-status: HIT. Sesi ini adalah investigasi berurutan untuk menemukan di mana sebenarnya file statik itu "hilang": urls.py → settings → staticfiles → curl ke port aplikasi vs lewat proxy → nginx → Cloudflare. Spoiler: masalahnya bukan di kode aplikasi sama sekali, tapi di konfigurasi reverse proxy nginx yang menyajikan /static/ dari folder kosong di host.

Work Log

  • [00:15:00] Jenkins build #... sukses, container up — senang, produksi "jalan"
  • [00:30:00] Buka production: CSS 404, JS 404 — HTML jalan tapi aset statik tidak
  • [00:45:00] Ikuti saran "tambah urlpatterns += static(STATIC_URL, document_root=STATIC_ROOT) di urls.py" — tetap 404
  • [01:00:00] Verifikasi settings.DEBUG di prod = False → sadar django.conf.urls.static() tidak aktif saat DEBUG=False (red herring)
  • [01:10:00] Cek base.py: STATIC_URL, STATIC_ROOT, STATICFILES_DIRS, WhiteNoise, ManifestStaticFilesStorage — semua benar
  • [01:20:00] Cek staticfiles/ di container: file skilltrace.c2c348b9adcb.css ADA di disk
  • [01:35:00] curl ke gunicorn :8000 langsung → 200 text/css, Cache-Control: immutable
  • [01:45:00] curl ke 127.0.0.1 (nginx) → 404 Server: nginx/1.18.0, Content-Length: 162
  • [02:00:00] nginx -T / cek sites-available: location /static/ { alias /opt/skilltrace/static/; } → root cause
  • [02:15:00] Comment blok location /static/ (dan /media/) → biarkan proxy_pass ke :8000
  • [02:30:00] Verifikasi origin 127.0.0.1 → 200; purge cache Cloudflare → public 200
  • [02:40:00] Revert blok static() di urls.py (tidak perlu; WhiteNoise menangani) + tulis blog ini

Context

  • Proyek: SkillTrace — mesin screening CV berbasis evidence (Django monolith + Celery + PostgreSQL + Redis)
  • Arsitektur produksi: Docker Compose → gunicorn :8000 (WhiteNoise serve static), nginx reverse proxy di depan, Cloudflare CDN paling luar
  • Deploy: GitHub → Jenkins → rsync ke server → docker compose up -d --build
  • Stack static: Tailwind CSS (dikompilasi dahulu via npm run build:css), WhitenoiseMiddle + CompressedManifestStaticFilesStorage, collectstatic --noinput dijalankan saat container start (docker-compose.yml)

Problem

Gejala utamanya satu: seluruh aset statik (CSS/JS dengan hashed filename seperti skilltrace.c2c348b9adcb.css) mengembalikan 404 di production. Namun:

  • HTML halaman termuat normal (user login, dashboard tampil — tapi tanpa styling)
  • File diminta ada di staticfiles/css/
  • Aplikasi (gunicorn/WhiteNoise) menjawab 200 saat diuji langsung
  • Tapi dari luar, lewat nginx & Cloudflare, tetap 404

Dua penyimpangan selama investigasi yang membuat makin bingung: saran ChatGPT untuk menambah static() di urls.py tidak berhasil, dan curl public tetap 404 bahkan sebelum ada perbaikan (cache-control: max-age=14400, age: 141) padahal belum ada yang kuubah.

Investigation

Investigasi dijalankan berurutan, tiap lapisan diisolasi dengan curl yang menunjuk langsung ke lapisan tsb dan membaca header Server: untuk tahu siapa yang benar-benar menjawab.

Uji Perintah Hasil Siapa yang menjawab
Aplikasi curl -sI http://127.0.0.1:8000/static/... 200 text/css, immutable gunicorn + WhiteNoise
Aplikasi (Django test client) Client().get('/static/...') 200 Django WSGI
nginx curl -sI http://127.0.0.1/static/... -H "Host: skilltrace.codenest.id" 404 Content-Length: 162 nginx/1.18.0
Public curl -sI https://skilltrace.codenest.id/static/... 404 cf-cache-status: HIT Cloudflare

Poin kunci dimulai dari selisih antara baris :8000 (200) dan 127.0.0.1:80 (404). Karena aplikasi sudah jawab 200, curl ke 127.0.0.1 yang menghasilkan 404 berarti request dipotong oleh nginx sebelum sampai ke container. Header Server: nginx/1.18.0 dan Content-Length: 162 (sangat pendek = halaman error nginx, bukan dokumen CSS ratusan KB) memastikan ini halaman error nginx, bukan error aplikasi.

Selanjutnya nginx -T (dump seluruh konfigurasi efektif; grep sites-enabled ternyata kosong karena file live ditarik lewat include) membeberkan blok ini di /etc/nginx/sites-available/skilltrace:

location /static/ {
    alias /opt/skilltrace/static/;
}
location /media/ {
    alias /opt/skilltrace/media/;
}
location / {
    proxy_pass http://127.0.0.1:8000;
}

Di sini terlihat dua jalur statik yang tidak sama: nginx menyajikan /static/ dari disk host /opt/skilltrace/static/, sedangkan file sebenarnya ada di dalam container skilltrace_web/staticfiles/ (hasil collectstatic --noinput saat start). /opt/skilltrace/static/ tidak pernah terisi -> 404.

Root Cause

nginx location /static/ memakai blok alias /opt/skilltrace/static/; yang mengarah ke folder host yang kosong/tidak pernah terisi, sementara file statik yang valid berada di dalam container di skilltrace_web/staticfiles/ (dihasilkan oleh collectstatic --noinput yang jalan pada saat container start, bukan saat build image).

Kenapa folder host kosong? Karena alur deploy (rsync yang mengecualikan media/, logs/, dll. lalu docker compose up -d --build) tidak pernah menyalin hasil collectstatic (yang diproduksi saat runtime container) kembali ke host. Jadi jalur alias di nginx menunjuk ke direktori yang isinya 404 — bukan karena file hilang, tapi karena nginx membaca lokasi yang salah.

Dua lapisan yang ikut menyembunyikan/memperumit diagnosis:

  1. django.conf.urls.static() buntu di prod. static() hanya menambahkan route saat DEBUG=True. Di production DJANGO_DEBUG=False, blok tersebut tidak menghasilkan apa-apa — jadi saran "tambah static() di urls.py" sama sekali tidak berdampak. (dan sebenarnya tidak dibutuhkan: WhiteNoise + whitenoise.runserver_nostatic sudah menangani static di dev maupun prod.)
  2. Cloudflare men-cache 404. Respons server: cloudflare + cf-cache-status: HIT mengindikasikan CDN menyimpan error 404 (TTL max-age=14400 = 4 jam). Akibatnya, bahkan setelah nginx diperbaiki, curl dari luar tetap 404 terhadap cache lama sampai di-purge — itulah kenapa "belum ada perbaikan tapi ternyata cache HIT".

Solution

  1. Comment blok location /static/ dan location /media/ di /etc/nginx/sites-available/skilltrace. Biarkan location / yang proxy_pass http://127.0.0.1:8000; menangani semuanya, sehingga WhiteNoise yang menyajikan statik (terbukti 200 + Cache-Control: max-age=315360000, public, immutable). Ini menjadikan WhiteNoise satu-satunya sumber kebenaran untuk aset statik dan menghapus ketergantungan pada sinkronisasi file statik host-repo yang mudah pecah.
# /etc/nginx/sites-available/skilltrace  (sebelum)
location /static/ {
    alias /opt/skilltrace/static/;
}

# (sesudah — dikomentari; proxy_pass menangani /static/)
#    location /static/ {
#        alias /opt/skilltrace/static/;
#    }
  1. Purge cache Cloudflare untuk /static/* (atau Purge Everything) karena 404-nya sudah ter-cache. Setelah itu public URL mengembalikan 200 dengan cf-cache-status: MISS/DYNAMIC.
  2. Jangan memakai urlpatterns += static(...) di urls.py. Baris ini hanya berguna di dev (DEBUG=True) dan di prod sia-sia; WhiteNoise runserver_nostatic (sudah terdaftar di INSTALLED_APPS) menangani dev, dan WhiteNoise serve dari STATIC_ROOT di prod.

Insight

  • "Build success" bukan berarti aplikasi jalan. Jenkins yang hijau hanya membuktikan image ter-build dan test pass — bukan bahwa setiap aset ter-serve benar di lingkungan produksi. Cek runtime, bukan sekadar status pipeline.
  • Ikuti saran dengan memverifikasi mode. django.conf.urls.static() hanya aktif saat DEBUG=True. Saran "tambah static() di urls.py" benar untuk dev, tapi di prod (DEBUG=False) diam-diam mati. Selalu cek settings.DEBUG di environment yang sedang ditarget, bukan di .env lokal.
  • Isolasi lapisan dengan curl langsung. Membaca header Server: menegaskan siapa yang menjawab: gunicorn, nginx, atau Cloudflare. Content-Length: 162 pada error 404 langsung memisahkan "nginx error page" dari "dokumen CSS". Ini pola debug yang bisa dipakai lagi: curi jalur sedekat mungkin ke sumber, lalu bergerak keluar lapis demi lapis.
  • WhiteNoise sebagai satu sumber kebenaran. Menyajikan statik dari disk di nginx (alias) menduplikasi sumber dan menciptakan titik kegagalan kedua yang tak ter-sinkron dengan container. Biarkan WhiteNoise yang serve — lebih sederhana dan tidak bisa "ketinggalan sync".
  • CDN bisa men-cache kesalahan. 404 yang di-cache Cloudflare tidak terlihat benar-benar "hilang" dari luar sampai di-purge; perbaikan origin tidak otomatis terlihat dari sisi public. Setelah fix, purge cache dulu baru verifikasi.

Gotchas

  • .env di repo workspace dan .env di server adalah dua file berbeda (rsync mengecualikan .env). Di repo .env ada DJANGO_DEBUG=True, sementara di environment Docker/container prod DJANGO_DEBUG=False. Jangan menarik kesimpulan dari .env lokal.
  • grep sites-enabled/ tidak menemukan blok location karena file live ditarik lewat include ke direktori lain; gunakan nginx -T (dump konfigurasi efektif) untuk melihat apa yang benar-benar dipakai nginx.
  • CompressedManifestStaticFilesStorage memakai hashed filename (skilltrace.c2c348b9adcb.css). Jika hash CSS berubah karena npm run build:css tetapi container menyimpan hash lama, browser bisa mereferensi hash yang tidak ada — tapi kali ini hash yang diminta memang ada di staticfiles/, jadi itu bukan penyebab.
  • Cache-Control: immutable dari WhiteNoise bagus untuk aset ber-hash, tapi browser/CDN bisa menyimpan versi lama; gunakan hard refresh saat verifikasi visual setelah deploy.
  • Sebaiknya hindari menyajikan /media/ dari disk host juga, karena file CV bersifat privat (MinIO) dan folder media/ host tidak ikut ter-deploy.

Kesimpulan

Masalahnya sebenarnya sepele tapi sulit dilihat karena tersembunyi di balik tiga lapisan: aplikasi menjawab 200, nginx memotong /static/ ke folder host yang kosong (404), dan Cloudflare menyimpan 404 itu sehingga perbaikan pun tidak terlihat sampai di-purge. Akar masalah bukan di kode aplikasi — base.py, urls.py, dan collectstatic semuanya benar — melainkan konfigurasi nginx yang menyajikan statik dari lokasi yang salah.

Pelajaran berharga: sebelum menyalahkan settings atau aplikasi, isolasi tiap lapisan dengan curl langsung dan baca header Server:. Setelah nginx diarahkan untuk meneruskan /static/ ke gunicorn (WhiteNoise) dan cache Cloudflare di-purge, CSS dan JS production termuat normal. Tidak ada perubahan kode yang dibutuhkan — hanya satu blok location yang di-comment.

Stats

  • Total errors di kode: 0 (tidak ada perubahan aplikasi)
  • Perubahan kode netto: 0 (urls.py dikembalikan seperti semula)
  • Perubahan infra: comment blok location /static/ & /media/ di nginx + purge cache Cloudflare
  • Rentang waktu debugging: ~2.5 jam (18:00 -> 20:30 WIB)
  • Lapisan yang didiagnosis: Docker/container -> gunicorn/WhiteNoise -> nginx -> Cloudflare

Last updated 24 Sep 2026 23:08

Comments