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.DEBUGdi prod = False → sadardjango.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: fileskilltrace.c2c348b9adcb.cssADA di disk - [01:35:00]
curlke gunicorn:8000langsung → 200text/css,Cache-Control: immutable - [01:45:00]
curlke127.0.0.1(nginx) → 404Server: 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/) → biarkanproxy_passke: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 →
rsyncke server →docker compose up -d --build - Stack static: Tailwind CSS (dikompilasi dahulu via
npm run build:css),WhitenoiseMiddle+CompressedManifestStaticFilesStorage,collectstatic --noinputdijalankan 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:
django.conf.urls.static()buntu di prod.static()hanya menambahkan route saatDEBUG=True. Di productionDJANGO_DEBUG=False, blok tersebut tidak menghasilkan apa-apa — jadi saran "tambahstatic()di urls.py" sama sekali tidak berdampak. (dan sebenarnya tidak dibutuhkan: WhiteNoise +whitenoise.runserver_nostaticsudah menangani static di dev maupun prod.)- Cloudflare men-cache 404. Respons
server: cloudflare+cf-cache-status: HITmengindikasikan CDN menyimpan error 404 (TTLmax-age=14400= 4 jam). Akibatnya, bahkan setelah nginx diperbaiki,curldari luar tetap 404 terhadap cache lama sampai di-purge — itulah kenapa "belum ada perbaikan tapi ternyata cache HIT".
Solution
- Comment blok
location /static/danlocation /media/di/etc/nginx/sites-available/skilltrace. Biarkanlocation /yangproxy_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/;
# }
- Purge cache Cloudflare untuk
/static/*(atau Purge Everything) karena 404-nya sudah ter-cache. Setelah itu public URL mengembalikan 200 dengancf-cache-status: MISS/DYNAMIC. - Jangan memakai
urlpatterns += static(...)di urls.py. Baris ini hanya berguna di dev (DEBUG=True) dan di prod sia-sia; WhiteNoiserunserver_nostatic(sudah terdaftar diINSTALLED_APPS) menangani dev, dan WhiteNoise serve dariSTATIC_ROOTdi 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 saatDEBUG=True. Saran "tambah static() di urls.py" benar untuk dev, tapi di prod (DEBUG=False) diam-diam mati. Selalu ceksettings.DEBUGdi environment yang sedang ditarget, bukan di.envlokal. - Isolasi lapisan dengan
curllangsung. Membaca headerServer:menegaskan siapa yang menjawab: gunicorn, nginx, atau Cloudflare.Content-Length: 162pada 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
.envdi repo workspace dan.envdi server adalah dua file berbeda (rsync mengecualikan.env). Di repo.envadaDJANGO_DEBUG=True, sementara di environment Docker/container prodDJANGO_DEBUG=False. Jangan menarik kesimpulan dari.envlokal.grep sites-enabled/tidak menemukan bloklocationkarena file live ditarik lewatincludeke direktori lain; gunakannginx -T(dump konfigurasi efektif) untuk melihat apa yang benar-benar dipakai nginx.CompressedManifestStaticFilesStoragememakai hashed filename (skilltrace.c2c348b9adcb.css). Jika hash CSS berubah karenanpm run build:csstetapi container menyimpan hash lama, browser bisa mereferensi hash yang tidak ada — tapi kali ini hash yang diminta memang ada distaticfiles/, jadi itu bukan penyebab.Cache-Control: immutabledari 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 foldermedia/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.pydikembalikan 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
Comments