Coba itung, ada berapa tab browser yang kebuka gara-gara mau ngecek Portainer? Terus pindah lagi buat liat Vaultwarden, abis itu geser ke Uptime Kuma. Kalau kamu ngoperasiin banyak service sendirian di VPS, pola kayak gini pasti kerasa familiar. IP sama nomor port ujung-ujungnya cuma nyangkut di notes, atau malah cuma diinget doang. Masalah kecil kayak gini yang bikin akhirnya butuh satu dashboard buat ngumpulin semua service jadi satu halaman. Homepage ngasih solusi yang pas: dashboard yang Docker-aware, bisa nampilin status container live, dan update otomatis lewat Docker label. Di artikel ini saya bakal bahas cara install Homepage di VPS pakai Docker dari nol, lengkap dengan penjelasan detail di setiap langkahnya.
Apa Itu Homepage dan Kenapa Bukan Sekadar Bookmark
Sekilas Homepage keliatan kayak startpage biasa – cuma kumpulan link yang dirapiin. Tapi begitu dicoba, bedanya kerasa banget. Homepage itu application dashboard yang didesain khusus buat self-hoster. Dia bisa nyambung langsung ke Docker socket, jadi tau container mana yang lagi jalan dan mana yang mati tanpa kamu harus update manual.
Fitur utama yang bikin Homepage beda dari bookmark manager biasa:
- Docker Integration: Homepage baca status container langsung dari Docker socket. Container baru yang dikasih label otomatis muncul di dashboard tanpa edit config manual
- Widget System: Bisa nampilin data live dari service lain – jumlah monitor up di Uptime Kuma, statistik Portainer, status Vaultwarden, dan puluhan integrasi lainnya
- Resource Monitoring: Widget bawaan buat nampilin CPU, RAM, disk usage, dan network langsung di dashboard tanpa tools tambahan
- Ringan: Cuma butuh sekitar 50-100MB RAM. Jauh lebih ringan dari dashboard tools lain
- Konfigurasi YAML: Semua konfigurasi lewat file YAML yang gampang di-backup dan di-version control
Homepage bukan pengganti Portainer buat ngontrol container, dan bukan pengganti Uptime Kuma buat monitoring uptime jangka panjang. Posisinya itu “pintu depan” – satu halaman yang ngasih gambaran cepat tentang semua service yang jalan di server kamu.
Prasyarat Sebelum Install Homepage di VPS
Homepage itu ringan banget, tapi tetep ada beberapa hal yang perlu disiapin dulu.
1. VPS dengan Spesifikasi Minimum
Homepage gak butuh resource besar. Spek minimum:
- RAM: 512MB udah cukup buat nampung puluhan service di dashboard
- CPU: 1 vCPU
- Storage: Minimal 1GB kosong (Homepage sendiri super kecil, config file-nya cuma beberapa KB)
- OS: Ubuntu 22.04 atau 24.04 LTS
Cara cek spek VPS kamu:
free -h # cek RAM tersedia
df -h # cek disk space
nproc # cek jumlah CPU2. Docker dan Docker Compose Sudah Terinstall
Homepage jalan di Docker container. Kalau belum terinstall, ikutin dulu panduan Cara Install Docker di Ubuntu VPS. Verifikasi:
docker --version
docker compose version3. Port 3000 Tersedia
Homepage default-nya jalan di port 3000. Pastiin port ini belum dipakai service lain:
sudo lsof -i :3000Kalau port 3000 udah dipakai (misalnya Grafana atau Gitea), kamu bisa ganti port mapping di docker-compose.yml nanti.
4. Domain atau Subdomain (Opsional tapi Direkomendasikan)
Kalau mau akses Homepage lewat domain (misalnya home.domainmu.com), siapin subdomain dan arahin A record ke IP VPS. Ini juga dibutuhin buat setting HOMEPAGE_ALLOWED_HOSTS.
5. Service Docker yang Mau Ditampilin
Homepage paling berguna kalau kamu udah punya beberapa service Docker yang jalan. Misalnya Vaultwarden, Uptime Kuma, Portainer, Watchtower, dan lain-lain. Siapin list URL dan port dari service-service yang mau ditampilin di dashboard.
Cara Install Homepage di VPS Step by Step
Sekarang masuk ke bagian inti. Ikutin langkah-langkah di bawah ini satu per satu.
Step 1 – Buat Folder Project
Login ke VPS lewat SSH, lalu bikin folder khusus buat Homepage:
mkdir -p /opt/homepage
cd /opt/homepageStep 2 – Buat File docker-compose.yml
Bikin file Docker Compose:
nano docker-compose.ymlPaste isi berikut:
services:
homepage:
image: ghcr.io/gethomepage/homepage:latest
container_name: homepage
restart: unless-stopped
ports:
- "3000:3000"
environment:
HOMEPAGE_ALLOWED_HOSTS: homepage.domainmu.com
volumes:
- ./config:/app/config
- /var/run/docker.sock:/var/run/docker.sock:roPenjelasan setiap komponen:
- image: ghcr.io/gethomepage/homepage:latest: Image resmi Homepage dari GitHub Container Registry. Pakai
latestbuat selalu dapet versi terbaru, atau pin ke versi spesifik kalau mau lebih stabil - ports “3000:3000”: Expose port 3000 ke host. Kalau port 3000 udah dipakai service lain, ganti port kiri jadi port lain (misalnya
"8080:3000") - HOMEPAGE_ALLOWED_HOSTS: Ini environment variable yang paling sering kelewat. Isi dengan domain atau IP:port yang bakal dipakai buat akses Homepage. Kalau kelewat, dashboard bakal nampilin halaman blank atau error 403. Boleh lebih dari satu, dipisah koma (misalnya
homepage.domainmu.com,192.168.1.100:3000) - ./config:/app/config: Mount folder config ke host. Folder ini bakal otomatis keisi beberapa file YAML dasar (settings.yaml, services.yaml, widgets.yaml) begitu container pertama kali jalan
- /var/run/docker.sock:/var/run/docker.sock:ro: Mount Docker socket dengan mode read-only. Ini yang bikin Homepage bisa baca status container yang jalan di server. Flag
:ropenting – Homepage cuma butuh baca, bukan ngontrol atau ngestop container
Ganti homepage.domainmu.com dengan domain kamu yang sebenarnya. Kalau belum punya domain, isi dengan ip-vps-kamu:3000.
Step 3 – Jalankan Container
Jalanin Homepage:
docker compose up -dCek status container:
docker compose psContainer harusnya status Up. Cek juga apakah folder config udah ke-generate:
ls -la config/Kamu harusnya liat beberapa file YAML: settings.yaml, services.yaml, widgets.yaml, bookmarks.yaml, dan docker.yaml. File-file ini yang bakal kita edit di step selanjutnya.
Buka browser dan akses:
http://ip-vps-kamu:3000Kalau semua bener, dashboard kosong bakal muncul. Sekarang kita isi kontennya.
Konfigurasi Dashboard – Cara Manual
Step 4 – Edit services.yaml (Tambahin Service ke Dashboard)
File services.yaml itu tempat kamu nentuin service apa aja yang muncul di dashboard. Edit file-nya:
nano config/services.yamlContoh konfigurasi dengan beberapa grup service:
- Infrastruktur:
- Portainer:
href: https://portainer.domainmu.com
icon: portainer.png
description: Kelola container Docker
server: my-docker
container: portainer
- Traefik:
href: https://traefik.domainmu.com
icon: traefik.png
description: Reverse proxy
server: my-docker
container: traefik
- Security:
- Vaultwarden:
href: https://vault.domainmu.com
icon: vaultwarden.png
description: Password manager
server: my-docker
container: vaultwarden
- CrowdSec:
href: https://crowdsec.domainmu.com
icon: crowdsec.png
description: Intrusion prevention
- Monitoring:
- Uptime Kuma:
href: https://uptime.domainmu.com
icon: uptime-kuma.png
description: Monitor uptime service
widget:
type: uptimekuma
url: http://uptime-kuma:3001
slug: defaultPenjelasan setiap field:
- Nama grup (Infrastruktur, Security, Monitoring): Grup buat ngelompokin service di dashboard. Bebas mau bikin berapa grup
- href: URL yang dibuka kalau kamu klik service card di dashboard
- icon: Nama file icon. Homepage punya library icon built-in yang lengkap. Cek daftar lengkapnya di dashboard-icons. Nama harus persis, salah huruf dikit aja icon gak muncul
- description: Deskripsi singkat yang muncul di bawah nama service
- server dan container: Kalau diisi, Homepage bakal nampilin status container (running/stopped) langsung di card.
serverharus sesuai dengan nama yang di-set didocker.yaml - widget: Nampilin data live dari service. Setiap service punya tipe widget yang beda – cek dokumentasi widget Homepage buat list lengkapnya
Step 5 – Edit docker.yaml (Koneksi ke Docker)
Biar Homepage bisa baca status container, kamu perlu setup koneksi Docker di file docker.yaml:
nano config/docker.yamlIsi dengan:
my-docker:
socket: /var/run/docker.sockmy-docker ini nama yang kamu pakai di field server di services.yaml. Bisa diganti nama lain, asal konsisten. Kalau kamu punya beberapa server Docker (misalnya lewat TCP), bisa tambahin entry lain di sini.
Step 6 – Edit widgets.yaml (Widget Global di Atas Dashboard)
Selain widget per service, Homepage juga punya widget global yang muncul di bagian atas dashboard. Edit file-nya:
nano config/widgets.yamlContoh konfigurasi:
- resources:
cpu: true
memory: true
disk: /
- search:
provider: duckduckgo
target: _blank
- datetime:
text_size: xl
format:
dateStyle: long
timeStyle: short
hour12: falsePenjelasan widget global:
- resources: Nampilin CPU usage, RAM usage, dan disk usage server langsung di atas dashboard. Berguna banget buat quick glance tanpa buka htop
- search: Tambahin search bar di dashboard. Bisa pakai DuckDuckGo, Google, atau search engine lain
- datetime: Nampilin tanggal dan jam. Kecil tapi berguna buat dashboard yang dipajang di monitor
Konfigurasi Dashboard – Cara Otomatis Pakai Docker Label
Step 7 – Tambahin Label ke Container yang Mau Ditampilin
Begitu jumlah container makin banyak, nulis manual satu-satu di services.yaml jadi kerjaan yang gampang kelewatan. Homepage punya cara yang lebih elegan: Docker label. Tinggal nempelin label di masing-masing container, dan Homepage otomatis detect dan tampilin di dashboard.
Contoh, di docker-compose.yml Vaultwarden kamu (bukan di compose Homepage), tambahin section labels:
services:
vaultwarden:
image: vaultwarden/server:latest
container_name: vaultwarden
restart: unless-stopped
# ... config lainnya ...
labels:
- homepage.group=Security
- homepage.name=Vaultwarden
- homepage.icon=vaultwarden.png
- homepage.href=https://vault.domainmu.com
- homepage.description=Password manager sendiriPenjelasan setiap label:
- homepage.group: Nama grup di dashboard. Kalau grup belum ada, otomatis dibikin
- homepage.name: Nama service yang muncul di card
- homepage.icon: Icon dari library built-in Homepage
- homepage.href: URL yang dibuka kalau card diklik
- homepage.description: Deskripsi singkat
Contoh label buat container lain dengan widget:
# Uptime Kuma dengan widget
labels:
- homepage.group=Monitoring
- homepage.name=Uptime Kuma
- homepage.icon=uptime-kuma.png
- homepage.href=https://uptime.domainmu.com
- homepage.description=Monitor uptime service
- homepage.widget.type=uptimekuma
- homepage.widget.url=http://uptime-kuma:3001
- homepage.widget.slug=defaultSetelah tambahin label, restart container yang bersangkutan:
cd /path/ke/folder/vaultwarden
docker compose up -d --force-recreateHomepage bakal otomatis detect label baru dan tampilin service di dashboard tanpa perlu restart Homepage atau edit services.yaml.
Step 8 – Kapan Pakai Manual vs Label
Dua pendekatan ini bisa dicampur. Rekomendasi:
- Pakai services.yaml (manual): Buat service yang jarang berubah dan kamu mau kontrol urutan tampilannya. Misalnya Portainer, Traefik, atau service eksternal yang bukan Docker container
- Pakai Docker label (otomatis): Buat service yang sering gonta-ganti, testing, atau deploy baru. Setiap kali deploy container baru dengan label, dashboard otomatis update. Cocok buat server yang container-nya dinamis
Kalau pakai keduanya bersamaan, service dari label dan dari services.yaml bakal muncul bareng di dashboard.
Testing dan Verifikasi
Step 9 – Verifikasi Dashboard dan Service Card
Setelah edit config file, restart Homepage biar perubahan ke-load:
cd /opt/homepage
docker compose restartBuka dashboard di browser dan verifikasi:
- Service card muncul: Semua service yang ditambahin di services.yaml harusnya muncul di dashboard, dikelompokin sesuai grup
- Icon tampil: Setiap card harusnya punya icon yang sesuai. Kalau icon gak muncul (kotak kosong), cek nama file icon-nya
- Status container: Kalau kamu set field
serverdancontainer, harusnya ada indikator hijau (running) atau merah (stopped) di card - Widget data: Kalau ada widget (misalnya Uptime Kuma), cek apakah data live-nya muncul di card
- Widget global: CPU, RAM, dan disk usage harusnya muncul di bagian atas dashboard
- Link berfungsi: Klik setiap card dan pastiin redirect ke URL yang bener
Step 10 – Test Docker Label Auto-Detection
Kalau kamu udah tambahin label di Step 7, verifikasi apakah Homepage otomatis detect:
- Buka dashboard – service yang dikasih label harusnya udah muncul tanpa edit services.yaml
- Coba restart container yang berlabel:
docker restart vaultwarden. Status di dashboard harusnya berubah sebentar lalu balik ke hijau - Coba stop container:
docker stop vaultwarden. Status di dashboard harusnya berubah jadi merah/offline - Start lagi:
docker start vaultwarden. Status balik ke hijau
Kalau semua test di atas berhasil, Homepage kamu udah fully functional.
Yang Perlu Diperhatiin Setelah Install Homepage
Ada beberapa masalah yang sering muncul dan tips penting yang perlu kamu tau.
Dashboard Blank atau Error 403
Ini masalah nomor satu yang dialami hampir semua orang yang baru install Homepage. Buka dashboard tapi yang muncul cuma halaman kosong atau error 403 Forbidden.
Penyebabnya hampir selalu: HOMEPAGE_ALLOWED_HOSTS belum diisi atau nilainya gak cocok sama domain/IP yang dipakai buat akses. Solusi:
- Cek environment variable di docker-compose.yml. Pastiin
HOMEPAGE_ALLOWED_HOSTSudah diisi - Nilainya harus sama persis dengan yang kamu ketik di browser. Kalau akses lewat
http://192.168.1.100:3000, isi dengan192.168.1.100:3000. Kalau lewat domain, isi dengan domain-nya - Boleh isi lebih dari satu, dipisah koma:
homepage.domainmu.com,192.168.1.100:3000 - Setelah edit, restart container:
docker compose up -d --force-recreate
Status Container Gak Muncul di Card
Kalau service card muncul tapi gak ada indikator status container (hijau/merah), cek:
- Docker socket belum di-mount: Pastiin volume
/var/run/docker.sock:/var/run/docker.sock:roada di docker-compose.yml Homepage - docker.yaml belum di-setup: Pastiin file
config/docker.yamludah diisi dengan nama server dan path socket (lihat Step 5) - Field server dan container belum diisi: Di services.yaml, setiap service yang mau ditampilin statusnya harus punya field
server: my-dockerdancontainer: nama-container - Nama container salah: Nama di field
containerharus sama persis dengancontainer_namedi docker-compose.yml service yang bersangkutan. Cek dengandocker ps --format "{{.Names}}"
Icon Service Gak Keluar
Homepage punya library icon built-in yang cukup lengkap. Tapi nama file icon harus persis – salah huruf dikit aja gagal muncul. Tips:
- Cek daftar icon yang tersedia di dashboard-icons repository
- Nama icon case-sensitive.
Portainer.pngbeda samaportainer.png - Kalau icon yang kamu mau gak ada di library, bisa taruh file icon custom di folder
config/icons/dan refer dengan path/icons/nama-file.png
Docker Label Gak Kedeteksi
Kalau udah tambahin label di container tapi gak muncul di dashboard:
- Container belum di-recreate: Tambahin label aja gak cukup, container harus di-recreate biar label ke-apply. Jalanin
docker compose up -d --force-recreatedi folder service yang bersangkutan - Docker socket gak bisa diakses: Homepage harus punya akses ke Docker socket server yang sama tempat container berlabel itu jalan. Kalau setup-nya lintas server, label gak bakal kedeteksi
- Typo di label: Nama label harus persis:
homepage.group,homepage.name, dll. Cek ulang spelling-nya
Keamanan – Jangan Expose Dashboard ke Publik
Dashboard yang nampilin semua service internal kamu itu sendiri udah jadi informasi berharga buat orang yang gak seharusnya liat. Apalagi kalau widget-nya nunjukin detail resource atau status server. Beberapa opsi buat ngamanin:
- Tailscale: Cara paling gampang. Taruh Homepage di belakang Tailscale biar cuma device yang terdaftar di tailnet yang bisa akses. Gak perlu buka port ke publik sama sekali
- Basic Auth lewat reverse proxy: Kalau tetep mau diakses dari mana aja, tambahin basic authentication lewat Traefik atau Nginx di depan Homepage
- Cloudflare Tunnel + Access: Pakai Cloudflare Tunnel buat expose Homepage tanpa buka port, lalu tambahin Cloudflare Access buat autentikasi
- Docker socket read-only: Pastiin mount docker.sock selalu pakai flag
:ro. Homepage cuma butuh baca status, bukan ngontrol container
Kesimpulan
Homepage bukan pengganti Portainer buat ngontrol container, dan bukan pengganti Uptime Kuma buat monitoring uptime jangka panjang. Tapi begitu jumlah service makin banyak – mulai dari Vaultwarden buat password, Uptime Kuma buat monitoring, sampai Watchtower buat auto-update – tab browser yang berantakan itu ujung-ujungnya bikin capek sendiri.
Dengan Homepage di VPS, semua itu ketumpuk rapi di satu halaman. Widget nampilin data live tanpa harus buka service satu-satu. Docker label bikin dashboard update otomatis setiap deploy container baru. Dan karena Homepage super ringan (cuma 50-100MB RAM), dia gak bakal ngeganggu resource buat service lain.
Tips buat yang baru mulai: jangan langsung tambahin semua service sekaligus. Mulai dari 3-5 service inti yang paling sering kamu akses. Coba dua pendekatan (manual services.yaml dan Docker label) buat ngerasain mana yang lebih cocok buat workflow kamu. Begitu udah nyaman, baru tambahin service lain satu per satu.
Yang paling penting: amanin dashboard kamu. Jangan expose ke publik tanpa proteksi. Taruh di belakang Tailscale atau tambahin auth lewat reverse proxy. Dashboard yang nampilin semua service internal kamu itu informasi berharga yang gak seharusnya bisa diliat sembarang orang.
