Homepage dan Satu Dasbor untuk Semua Service

Seiring bertambahnya layanan, homelab mulai sulit diingat lewat port. Service A di port sekian, service B di path tertentu, dan seterusnya. Homepage hadir sebagai titik tunggal untuk melihat dan mengakses seluruh layanan dalam satu halaman.

Di homeserver saya, Homepage khusus untuk keperluan pribadi: diakses hanya lewat IP Tailscale di jaringan pribadi — tanpa nama domain, tanpa port forwarding, tanpa rute publik sama sekali. Dashboard ini murni pintu pribadi untuk service internal.

Mengapa satu dasbor untuk semua service

Saat layanan masih sedikit, membuka service lewat port terasa nyaman; begitu bertambah, menemukan alamat yang benar jadi pekerjaan rumah: port untuk aplikasi mana, path yang diketik, service mana yang mati.

Homepage memecahkan masalah itu dengan satu pintu masuk: setiap layanan tampil sebagai kartu yang bisa diklik, lengkap dengan ikon, status, dan link.

Cara kerja dan model konfigurasi

Homepage adalah aplikasi web self-hosted yang berfungsi sebagai dashboard sekaligus katalog layanan: ia mengumpulkan tautan, status, dan informasi tambahan dari berbagai service dalam satu antarmuka.

Seluruh pengaturan disimpan sebagai file YAML di direktori konfigurasi yang di-mount ke dalam container. Peran tiap file:

services.yaml — daftar layanan dan tata letaknya;
settings.yaml — pengaturan umum seperti bahasa dan tema;
widgets.yaml — widget dan API key-nya;
bookmarks.yaml — bookmark atau penyaring cepat;
docker.yaml — konfigurasi integrasi Docker;
custom.css dan custom.js — penyesuaian tampilan lanjutan.

Layanan dikelompokkan sebagai array grup di services.yaml; tiap service punya nama, ikon, link, deskripsi, dan opsional widget sendiri.

Karena berbasis file, konfigurasi bisa dibaca, di-version control, atau dipulihkan seperti berkas biasa. Catatan: dashboard dirender sebagai static HTML — perubahan settings.yaml perlu di-regenerate lewat tombol refresh.

Deployment dengan Docker Compose

Cara paling umum menjalankan Homepage adalah dengan Docker Compose:

services:
  homepage:
    image: ghcr.io/gethomepage/homepage:latest
    container_name: homepage
    ports:
      - "3000:3000"
    volumes:
      - /path/to/config:/app/config
      - /var/run/docker.sock:/var/run/docker.sock # hanya bila integrasi Docker dibutuhkan
    environment:
      HOMEPAGE_ALLOWED_HOSTS: '*'
    restart: unless-stopped

Volume config menjaga pengaturan bertahan saat container dibuat ulang; mount soket mengaktifkan deteksi kontainer.

Perhatikan HOMEPAGE_ALLOWED_HOSTS: sejak v1.0, host selain localhost harus didaftarkan (dipisah koma); '*' mematikan pemeriksaan ini. Host check hanya pengaman best-effort, bukan pengganti proxy, TLS, dan auth untuk publikasi.

Integrasi Docker dan penemuan container

Salah satu keunggulan Homepage adalah mendeteksi container secara dinamis lewat soket Docker: kontainer baru dengan label tertentu otomatis muncul tanpa konfigurasi tambahan. Anda bisa bereksperimen langsung:

docker ps --filter label=homepage

Label mengikuti notasi titik homepage.*, misalnya homepage.group=Media, homepage.name=Emby, homepage.icon=emby.png, homepage.href=http://<HOST>/, dan homepage.description.

Nilai server dan container tidak perlu ditulis manual — keduanya disimpulkan otomatis dari koneksi di docker.yaml.

Keamanan: soket, host check, dan autentikasi

Akses ke /var/run/docker.sock bukan tanpa risiko: siapa pun yang memilikinya memegang kendali penuh atas daemon Docker.

Penting: Soket Docker bersifat read-write. Keamanan container sama pentingnya dengan host itu sendiri, karena akses soket berarti hak akses root penuh. Jangan pernah memaparkan antarmuka ini ke publik tanpa autentikasi dan otorisasi kuat yang memadai.

Soket langsung mengharuskan Homepage berjalan sebagai root; alternatif yang lebih disukai: docker-socket-proxy — container read-only (POST=0, misal hanya CONTAINERS=1) untuk daftar container. Mount soket pun bisa :ro.

Sejak v2.0 ada gerbang autentikasi password atau OIDC — hampir semua route /api (kecuali healthcheck) butuh sesi login. Tidak ada rate limiting bawaan; deployment terekspos disarankan rate limit di reverse proxy. Karena itu saya menjalankannya hanya di jaringan pribadi, dengan auth sebagai lapisan tambahan.

Kelebihan yang saya rasakan

Satu pintu untuk semua service. Tidak menghafal port atau path; status terlihat sekilas.
Penemuan otomatis lewat label. Cukup beri label homepage.*, service baru langsung muncul.
Ikon dan widget. Pustaka ikon bawaan mengikuti konvensi penamaan; widget status bisa ditempel ke kartu apa pun.
Konfigurasi = file biasa. Version control, restore, dan kustomisasi (custom.css/custom.js) sederhana.

Kontra dan keterbatasan

Soket Docker = root. Integrasi penuh butuh akses read-write ke daemon; socket proxy read-only menambah satu container lagi yang dirawat.
Host check hanya best-effort. '*' menonaktifkannya; publikasi butuh proxy, TLS, dan auth.
Tanpa rate limiting login. Percobaan password tidak dibatasi aplikasi; aman hanya bila jaringan atau proxy membatasinya.
Kurva belajar YAML. Grup, nested group, widget per service, dan label discovery punya format sendiri.
Render statis dan key di file. Perubahan settings.yaml butuh regenerate; API key tersimpan di widgets.yaml dan label widget.

Pencadangan dan pemulihan

Data yang perlu dicadangkan hanya direktori konfigurasi dan ikon. Karena seluruh pengaturan tersimpan sebagai berkas, mengamankannya berarti menyalin berkas-berkas tersebut.

Pemulihan juga sederhana: jalankan ulang instance dengan direktori konfigurasi hasil cadangan; uji pada direktori terpisah dulu.

Operasi sehari-hari

Lihat status: docker ps --filter name=homepage
Cek log: docker logs --tail 100 homepage
Mulai ulang: docker restart homepage

Log bisa berisi informasi sensitif (nama layanan, URL); perhatikan kontennya sebelum membagikannya.

Kesimpulan

Homepage bukan dashboard paling canggih — justru itu keunggulannya: ringan, transparan, dan penemuan container otomatis. Di konteks saya (satu mesin, akses via Tailscale), kontra utamanya bisa ditekan dengan menjalankannya tertutup di jaringan pribadi dan memakai socket proxy read-only bila integrasi penuh tak dibutuhkan.