Mengatasi Error Deploy Hugo Tema Blowfish di Coolify dengan Dockerfile

Baru-baru ini saya memutuskan untuk membuat blog ini ke infrastruktur mandiri (self-hosted) menggunakan Coolify. Stack yang saya pilih adalah Hugo sebagai Static Site Generator (SSG) dengan tema Blowfish yang modern.

Awalnya, saya mengira prosesnya akan semudah “plug-and-play” menggunakan fitur build pack bawaan Coolify (Nixpacks). Namun, realita berkata lain. Saya menghadapi dua masalah teknis yang cukup membuat pusing kepala dan membuat proses deploy gagal total.

Postingan ini mendokumentasikan masalah tersebut dan solusi final menggunakan Dockerfile manual yang terbukti stabil.

Masalah yang Dihadapi

#

1. Error Versi Hugo (Function “try” not defined)

#

Saat menggunakan pengaturan default Coolify, sistem menarik versi Hugo yang ternyata cukup lawas (misalnya v0.118 atau v0.111). Padahal, tema Blowfish versi terbaru membutuhkan fitur-fitur yang hanya ada di Hugo versi modern (v0.123+).

Error log yang muncul di Coolify terlihat seperti ini:

Error: ... template: shortcodes/codeberg.html:5: function "try" not defined
WARN Module "blowfish" is not compatible with this Hugo version

2. Tampilan Rusak (CSS Integrity Mismatch)

#

Setelah berhasil mengatasi masalah versi, situs akhirnya bisa diakses. Namun, tampilannya rusak total, hanya teks hitam putih tanpa gaya (CSS).

Saat saya memeriksa Console di browser (Inspect Element), muncul deretan error merah seperti ini:

Failed to find a valid digest in the 'integrity' attribute for resource ...
The resource has been blocked.

Masalah ini terjadi karena alur kerja (workflow) yang saya gunakan kurang tepat:

1. Saya melakukan build (hugo) di laptop saya yang menggunakan Windows.
2. Hasil build (folder public) saya upload ke Git.
3. Server (Linux) menyajikan file tersebut.

Perbedaan sistem baris (line endings) antara Windows (CRLF) dan Linux (LF) menyebabkan kalkulasi hash keamanan (Fingerprint/Integrity) menjadi tidak cocok. Akibatnya, browser menganggap file CSS telah dimodifikasi atau “dirusak”, sehingga memblokirnya demi keamanan.

Solusi: Beralih ke Custom Dockerfile

#

Solusi terbaik untuk masalah ini adalah jangan mengandalkan image otomatis bawaan Coolify dan jangan meng-upload folder public secara manual. Kita harus membangun environment sendiri menggunakan Docker agar kita punya kontrol penuh atas versi Hugo dan memastikan integritas file.

Berikut langkah-langkah perbaikannya:

Langkah 1: Bersihkan Git Repository

#

Biarkan server yang melakukan build, bukan laptop kita. Hapus folder public dari repository Git agar tidak terjadi konflik hash di masa depan.

Jalankan perintah ini di terminal laptop:

# Hapus folder public dari git tracking (file di laptop tetap aman)
git rm -r --cached public

# Tambahkan ke .gitignore agar tidak ter-upload lagi
echo "public" >> .gitignore

# Commit perubahan
git commit -m "chore: remove public folder specific to local build"
git push origin main

Langkah 2: Buat Dockerfile Manual

#

Alih-alih bergantung pada image buatan komunitas yang mungkin jarang diperbarui (seperti klakegg/hugo), solusi terbaik adalah membangun environment sendiri. Kita akan menggunakan Multi-stage Build dengan base image Debian Slim untuk menjamin kita bisa menginstal Hugo Extended versi resmi langsung dari sumbernya.

Buat file baru bernama Dockerfile (tanpa ekstensi apapun) di folder paling luar (root directory) project Anda, lalu isi dengan kode berikut:

# --- Stage 1: Build Website ---
# Gunakan Debian Slim: Ringan, stabil, dan kompatibel dengan library Hugo Extended
FROM debian:bookworm-slim AS builder

# Tentukan versi Hugo yang kita mau.
# Kita bisa mengubah angka ini kapan saja jika ada update baru dari Hugo.
ARG HUGO_VERSION="0.152.2"

# 1. Install alat-alat dasar yang dibutuhkan untuk download dan ekstrak
RUN apt-get update && apt-get install -y \
    curl \
    git \
    ca-certificates \
    && rm -rf /var/lib/apt/lists/*

# 2. Download Installer Hugo Extended Resmi (.deb) dari GitHub
# Menggunakan versi Extended sangat WAJIB untuk tema Blowfish (pemrosesan gambar/WebP)
RUN curl -L "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb" -o hugo.deb \
    && dpkg -i hugo.deb \
    && rm hugo.deb


# 3. Verifikasi instalasi (Opsional, agar tercatat di log)
RUN hugo version

# 4. Siapkan direktori kerja
WORKDIR /src
COPY . .

# 5. Build situs Hugo
# --minify: Mengompres HTML/CSS/JS agar loading cepat
# --gc: Garbage Collector untuk membersihkan cache yang tidak terpakai
RUN hugo --minify --gc

# --- Stage 2: Serve dengan Nginx ---
# Kita pindahkan hasil build ke server Nginx yang sangat ringan (Alpine)
FROM nginx:alpine

# Copy hanya folder 'public' (hasil build) dari Stage 1 ke folder HTML Nginx
COPY --from=builder /src/public /usr/share/nginx/html

# Expose port 80 agar bisa diakses oleh Coolify
EXPOSE 80

# Jalankan Nginx
CMD ["nginx", "-g", "daemon off;"]

Langkah 3: Konfigurasi di Coolify

#

Setelah file Dockerfile di-push ke repository GitHub/GitLab, lakukan pengaturan berikut di dashboard Coolify:

1. Buka project Hugo Anda.

2. Masuk ke menu Configuration > General.

3. Ubah Build Pack menjadi Dockerfile.

4. Pastikan Docker File Location berisi /Dockerfile.

5. Patikan pada bagian Network Ports Exposes berisi port 80.

6. Klik Save dan kemudian Deploy.

Hasil Akhir

#

Dengan metode Dockerfile manual ini, semua masalah teratasi:

1. Versi Terkontrol: Kita mendapatkan Hugo v0.152.2 (atau terbaru) secara spesifik, sehingga fitur tema Blowfish berjalan lancar.
2. Integritas CSS Aman: Karena proses build terjadi di dalam container Linux di server (bukan di Windows), hash CSS cocok sempurna dan error integritas hilang.
3. Ringan: Hasil akhir container sangat kecil karena hanya berisi Nginx dan file HTML statis.

Jika nanti Hugo merilis versi baru (misalnya v0.140.0), saya cukup mengedit satu baris di Dockerfile tanpa perlu mengubah konfigurasi server:

ARG HUGO_VERSION="0.152.2"

Semoga panduan ini membantu teman-teman yang sedang berjuang men-deploy Hugo di VPS sendiri!