Complete Tutorial on Deploying Dockhand with Docker Compose & Caddy + Error Solutions

Dockhand adalah salah satu tool manajemen stack Docker (alternatif Dockge/Portainer) yang sangat ringan dan efisien. Jika Anda ingin mengelola kontainer Docker dengan tampilan UI yang bersih namun tetap mempertahankan kontrol penuh atas file compose.yaml, Dockhand adalah pilihan yang tepat.

Dalam panduan ini, kita akan membahas cara melakukan deploy Dockhand menggunakan Docker Compose, mengamankannya dengan reverse proxy Caddy agar memiliki SSL (HTTPS), serta merangkum beberapa error umum yang sering terjadi selama proses instalasi beserta cara mengatasinya.

1. Persiapan Struktur Folder

Sebelum memulai, pastikan Anda sudah masuk ke server via SSH. Kita akan membuat folder khusus untuk menyimpan data proyek Dockhand.

Jalankan perintah berikut di terminal:

Bash

mkdir -p ~/dockhand/projects ~/dockhand/data
cd ~/dockhand

• projects: Folder tempat menyimpan konfigurasi stack/kontainer lain yang akan dikelola oleh Dockhand.

• data: Folder untuk menyimpan database internal Dockhand.

2. Membuat File compose.yaml

Buat file konfigurasi Docker Compose untuk Dockhand:

Bash

nano compose.yaml

Salin dan tempel konfigurasi berikut:

YAML

services:
  dockhand:
    image: fnsys/dockhand:latest
    container_name: dockhand
    restart: unless-stopped
    environment:
      - AUTH_ENABLED=true  # Memaksa autentikasi login aktif sejak awal
    ports:
      - "8008:3000"        # Memetakan port eksternal 8008 ke port internal 3000
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./projects:/app/projects
      - ./data:/app/data 

Simpan file dengan menekan Ctrl + O, lalu Enter, dan keluar menggunakan Ctrl + X.

Jalankan kontainer dengan perintah:

Bash

docker compose up -d

3. Konfigurasi Reverse Proxy dengan Caddy

Agar Dockhand bisa diakses menggunakan domain/subdomain dengan aman (HTTPS), kita akan mengarahkan trafik melalui Caddy Server.

Buka file konfigurasi Caddyfile Anda (misalnya di folder ~/n8n/Caddyfile atau tempat Caddy Anda berada):

Bash

nano Caddyfile

Tambahkan blok konfigurasi berikut untuk domain Anda:

Cuplikan kode

dockersolo.biz.id {
        reverse_proxy 172.17.0.1:8008
}

Catatan: 172.17.0.1 adalah IP standar Docker Bridge Gateway yang digunakan Caddy untuk berkomunikasi dengan port eksternal host.

Setelah disimpan, reload konfigurasi Caddy tanpa downtime:

Bash

docker compose exec caddy caddy reload --config /etc/caddy/Caddyfile

 

4. Troubleshooting: Error Umum & Cara Mengatasinya

Selama proses deploy, ada beberapa kendala teknis yang kerap muncul. Berikut adalah rangkuman error dan solusinya:

Error 1: 502 Bad Gateway atau Connection Refused

Gejala: Saat mengakses domain di browser, muncul pesan error 502 Bad Gateway. Di log Caddy (docker compose logs caddy) muncul pesan:

"msg":"dial tcp 172.17.0.1:5001: connect: connection refused"

• Penyebab: Caddy mencoba menembak port lama (misalnya port 5001 bekas aplikasi lain seperti Dockge) atau port internal Dockhand salah diarahkan. Dockhand berjalan di port internal 3000, bukan 8008 atau 5001.

• Solusi: 1. Pastikan bagian ports di file compose.yaml Dockhand tertulis "8008:3000". 2. Pastikan Caddyfile mengarah ke port eksternal yang benar, yaitu 172.17.0.1:8008. 3. Lakukan restart service Docker jika routing iptables tersangkut: systemctl restart docker.

Error 2: Dashboard Langsung Terbuka Tanpa Login (Auto-Login Pertama)

Gejala: Setelah berhasil deploy, sistem langsung masuk ke dashboard tanpa meminta password sama sekali.

• Penyebab: Dockhand memiliki fitur keamanan awal yang secara otomatis mendeteksi instalasi baru (fresh install). Pada sesi pertama, sistem membiarkan admin masuk untuk melakukan setup awal. Namun, ini berbahaya jika domain sudah di-publish ke publik.

• Solusi:

  1. Segera masuk ke menu Settings > Auth di dashboard, lalu aktifkan sistem autentikasi dan buat user admin baru.

  2. Atau paksa lewat environtment variabel dengan menambahkan - AUTH_ENABLED=true di dalam file compose.yaml, lalu jalankan kembali perintah docker compose up -d --force-recreate.

Error 3: Terjebak Cache Browser Lama / WebSocket Macet

Gejala: Konfigurasi di server sudah diperbaiki dan log Dockhand menunjukkan status Listening on http://0.0.0.0:3000/ with WebSocket, tetapi browser Anda tetap menampilkan halaman error atau halaman setup aplikasi lama.

• Penyebab: Browser menyimpan cache keras (hard cache) dan mencoba mempertahankan sesi koneksi socket lama yang sudah mati.

• Solusi: Tutup tab browser Anda, buka Jendela Penyamaran Baru (Incognito Window), dan akses kembali domain Anda. Ini memaksa browser meminta data segar langsung dari server.

Kesimpulan

Deploy Dockhand menggunakan Docker Compose dan Caddy sangatlah mudah asalkan kita memahami pemetaan port antara internal kontainer (3000) dan port luar host (8008). Dengan mengaktifkan AUTH_ENABLED=true sejak awal, Anda memastikan dashboard manajemen server Anda tetap aman dari akses pihak luar.

Subscribe to receive free email updates: