Docker Compose di Homelab: organisasi, profil, dan praktik terbaik

Informatec Digital » Sumber Daya » Docker Compose di Homelab: Pengorganisasian, Profil, dan Praktik Terbaik

Membangun homelab modern dengan container telah menjadi hobi favorit bagi banyak penggemar teknologi. Docker Compose hampir selalu menjadi inti dari pengaturan ini : definisikan layanan Anda dalam YAML, kelola versinya dengan Git, dan jalankan seluruh lingkungan Anda dengan satu perintah.

Namun, ketika Anda mulai berkembang, segalanya berubah: Anda beralih dari hanya memiliki dua atau tiga kontainer menjadi puluhan layanan, jaringan internal, reverse proxy, basis data, dan CI runner . Saat itulah pertanyaan besar muncul: satu instance Docker Compose raksasa atau banyak file kecil? Bagaimana cara mengatur profil, jaringan, cadangan, keamanan, dan yang terpenting, mempermudah migrasi?

Pendekatan praktis untuk menyiapkan Docker Compose di lab rumahan.

Dalam praktiknya, orang-orang yang telah menggunakan Homelab untuk beberapa waktu biasanya bekerja dengan tiga model organisasi Compose yang berbeda, masing-masing dengan kelebihan dan kekurangannya sendiri. Memilih pendekatan yang tepat akan menghemat banyak masalah saat melakukan scaling up atau migrasi ke mesin baru.

Di satu sisi, ada mereka yang memulai dengan perintah Docker Run mandiri, kemudian beralih ke Portainer, dan akhirnya melompat ke Docker Compose . Ini adalah skenario tipikal: Portainer menawarkan visibilitas yang bagus, antarmuka yang ramah pengguna, templat, dll., tetapi pada akhirnya, mengedit parameter yang kompleks atau memigrasi konfigurasi menjadi merepotkan jika Anda tidak memiliki apa pun dalam bentuk file.

Di sisi ekstrem yang berlawanan terdapat orang yang telah mengkonsolidasikan semuanya ke dalam satu file docker-compose.yml "mega" yang mampu menjalankan semua layanan homelab: reverse proxy, media, utilitas, pemantauan, LLM, basis data... Semuanya dalam satu tumpukan.

Di antara keduanya, banyak pengguna tetap menggunakan pendekatan campuran: beberapa file docker-compose.yml kecil yang dikelompokkan berdasarkan konteks (misalnya, media, infrastruktur, produktivitas, pemantauan), semuanya berada di bawah repositori yang sama dan biasanya berbagi variabel lingkungan global.

Solusi yang cukup elegan menggabungkan kedua dunia: sebuah docker-compose "root" yang menyertakan file-file lain (masing-masing dalam subfolder aplikasi atau layanan). Dengan cara ini, Anda tetap memiliki pandangan global tentang homelab, tetapi tanpa harus berurusan dengan file YAML sepanjang ribuan baris yang sulit dibaca.

Profil, pengelompokan berdasarkan fungsi, dan lab rumahan berskala besar

Ketika homelab Anda mulai mendekati 30, 40, atau 50 layanan (termasuk layanan cadangan seperti basis data, cache, atau pengindeks), sangat penting untuk mengaturnya. Di sinilah pengelompokan berdasarkan fungsi dan penggunaan profil Docker Compose berperan.

Pola yang sangat umum adalah mengelompokkan semuanya ke dalam satu "proyek" Compose, tetapi secara logis dibagi berdasarkan profil. Misalnya:

• Profil inti: inti homelab, dengan Traefik sebagai reverse proxy dan penyedia identitas (misalnya, OAuth atau Authentik) untuk mengautentikasi semua aplikasi di bawah domain yang sama dengan HTTPS.
• Profil mediaLayanan seperti Plex, Sonarr, Radarr, Ombi, SABnzbd atau qBittorrent, bertanggung jawab untuk mengkurasi, mengunduh, dan menyajikan konten multimedia.
• Profil UtilitasGunakan alat-alat seperti Portainer, Watchtower (jika digunakan), Diun, dockcheck, atau yang serupa untuk mengelola dan memantau kontainer dan pembaruan.
• Profil infrastruktur/pemantauan: Traefik, cAdvisor, Prometheus, Grafana, Uptime Kuma, Dozzle dan segala sesuatu yang terkait dengan pemantauan dan pencatatan log.
• Profil eksperimental atau LLM: tumpukan khusus untuk LLM atau aplikasi unik (ChatGPT Next Web lokal, LibreOffice Online, dll.) yang biasanya dinonaktifkan secara default.

Keunggulan profil adalah Anda dapat menerapkan hanya sebagian infrastruktur sesuai kebutuhan. Misalnya, Anda dapat menjalankan hanya profil inti + infrastruktur pada PC mini berdaya rendah, dan hanya menerapkan profil media pada server besar dengan lebih banyak disk dan GPU.

Dalam repositori yang dirancang dengan baik, biasanya terdapat file docker-compose.yml "master" di root yang menggunakan perintah include untuk mendorong file individual ke dalam folder apps/ atau services/ . Selain itu, hampir semua layanan dikonfigurasi melalui satu file .env global, dan beberapa rahasia disimpan dalam direktori secrets/ , yang sangat menyederhanakan pengaturan awal.

Mengikuti pola ini, mengelola homelab pada dasarnya hanya mencakup mengedit file .env dan secrets, mengaktifkan atau menonaktifkan profil, dan memutuskan layanan mana yang akan dijalankan di setiap host . Ini ideal jika Anda akan menyebarkan rangkaian aplikasi yang sama di beberapa mesin.

Satu file docker-compose besar tunggal vs. beberapa file kecil.

Ini adalah perdebatan abadi: satu file docker-compose.yml yang berisi semuanya, atau beberapa file per layanan/stack? Jawaban sebenarnya biasanya "tergantung pada apa yang ingin Anda prioritaskan: kesederhanaan migrasi atau kejelasan per layanan."

Mereka yang mendukung penggunaan satu file induk (single master file) biasanya menyoroti beberapa keunggulan:

• Migrasi host sangat mudah.Anda mengklon repositori, menyalin file .env dan rahasia, memasang volume, dan menjalankan `docker compose up -d`. Tidak perlu masuk ke setiap direktori satu per satu.
• Infrastruktur sebagai kode kebenaranSeluruh topologi homelab (layanan, jaringan, volume, dependensi) berada di satu tempat.
• Pembaruan terpusatAnda mengubah versi gambar, kebijakan reboot, atau beberapa pencatatan log, dan Anda tahu persis di mana harus melakukan perubahan.

Namun, metode ini juga memiliki kekurangan yang jelas: file YAML yang besar lebih sulit dikelola, konflik penggabungan meningkat, dan saat melakukan debugging masalah tertentu, Anda akan menemukan diri Anda menavigasi tumpukan ratusan baris kode. Tidak jarang kita merasa sedikit menyesal ketika semuanya menjadi terlalu besar.

Pendekatan lainnya adalah dengan memiliki file docker-compose.yml untuk setiap aplikasi atau setiap tumpukan logis , dalam struktur seperti ini:

docker/
├── bookstack/
│   └── docker-compose.yml
├── dashy/
│   └── docker-compose.yml
└── traefik/
    └── docker-compose.yml

Dengan demikian, setiap kontainer diberi nama seperti bookstack-app-1 atau traefik-reverse-proxy-1 , yang membantu Anda menemukan masalah dengan cepat: jika kontainer bookstack-app-1 mengalami crash, Anda tahu persis folder mana yang harus diperiksa.

Secara visual, tampilannya jauh lebih bersih dan memungkinkan Anda mengelola setiap layanan secara independen (memulai, menghentikan, atau memperbarui tanpa memengaruhi layanan lainnya). Selain itu, aplikasi seperti Dozzle memanfaatkan adanya tumpukan terpisah untuk mengatur log dengan lebih baik.

Kelemahannya adalah jika Anda memisahkan semuanya terlalu jauh, koordinasi antara layanan umum (seperti Traefik atau jaringan bersama) membutuhkan sedikit lebih banyak perhatian : Anda harus mendeklarasikan jaringan eksternal, label Traefik khusus, dan mengingat nomenklatur jaringan yang dibuat oleh docker-compose lainnya.

Praktik terbaik dengan .env, penggantian pengaturan, dan kontrol versi.

Salah satu trik yang paling diremehkan adalah memusatkan konfigurasi dalam file .env . Alih-alih membanjiri docker-compose.yml Anda dengan variabel lingkungan, Anda dapat mendefinisikan sesuatu seperti ini:

DB_USERNAME=myuser
DB_PASSWORD=secretpassword

Kemudian dalam file YAML, variabel tersebut dirujuk sebagai ${DB_USERNAME} atau ${DB_PASSWORD} . Hal ini membuat Compose mudah dibaca sekilas, memungkinkan Anda untuk berbagi variabel di antara beberapa layanan , dan yang terpenting, menyimpan kata sandi dalam file terpisah (yang dapat Anda kecualikan dari Git).

Untuk lingkungan yang berbeda (produksi, pengujian, pengembangan), sangat berguna untuk memanfaatkan docker-compose.override.yml . Idenya adalah memiliki file docker-compose.yml dasar dan, di bagian override, hanya mengganti apa yang berubah: port, path, flag debug, dll.

Sebagai contoh, dalam pengembangan Anda dapat memuat override di mana Anda mengekspos port yang berbeda, mengaktifkan debugging, dan memasang kode sumber lokal . Anda tidak menyentuh YAML utama, tetapi Anda menyesuaikan tumpukan dengan lingkungan tempat Anda menjalankannya.

Jelas, melakukan kontrol versi dengan Git adalah wajib jika Anda ingin homelab Anda terlihat profesional . Biasanya Anda akan memiliki sesuatu seperti ini:

homelab-docker/
├── docker-compose.yml
├── .env.example
├── services/
│   ├── media/
│   ├── infra/
│   └── ...
└── scripts/

Dari situ, Anda menginisialisasi repositori, melakukan commit perubahan infrastruktur, dan jika terjadi kesalahan, Anda dapat kembali ke versi Compose sebelumnya dalam hitungan detik . Bagi homelab yang ambisius, ini bukan hanya pilihan; ini adalah satu-satunya cara untuk menghindari frustrasi.

Jaringan, Traefik, dan paparan layanan yang aman

Di hampir semua homelab tingkat menengah, kombinasi yang sama muncul: Traefik sebagai reverse proxy dan penyedia identitas terpusat (Auth atau Authentik) . Ini memungkinkan untuk mengekspos banyak aplikasi di bawah subdomain dengan HTTPS dan SSO.

Pendekatan klasik adalah dengan menyiapkan jaringan Docker khusus, seperti reverse_proxy atau yang serupa, tempat Traefik dan semua layanan web yang akan Anda layani secara eksternal terhubung. Kontainer lainnya (basis data, cache, dll.) tetap berada di jaringan internal yang terisolasi.

Jika Anda menggunakan Traefik dan memisahkan layanan Anda ke dalam beberapa instance Docker Compose yang berbeda, Anda perlu menentukan jaringan eksternal bersama . Kurang lebih seperti ini:

services:
  bookstack:
    image: lscr.io/linuxserver/bookstack
    networks:
      - traefik-net
    labels:
      - "traefik.docker.network=traefik_default"

networks:
  traefik-net:
    name: traefik_default
    external: true

Di sini, jaringan traefik_default dibuat oleh tumpukan Traefik, dan layanan lain ditambahkan ke dalamnya melalui jaringan eksternal yang disebut traefik-net. Label memberi tahu Traefik jaringan mana yang akan digunakan untuk merute lalu lintas.

Ketika satu tumpukan (stack) mencakup layanan backend (misalnya, kontainer web dan basis datanya), Anda dapat menghubungkannya ke jaringan default bersama, dan hanya memberikan akses kontainer web ke jaringan Traefik . Basis data akan memiliki label yang diatur ke `traefik.enable=false` sehingga Traefik mengabaikannya.

Jenis pengaturan ini menawarkan dua manfaat utama: isolasi antar layanan dan paparan yang terkontrol . Hanya kontainer yang Anda beri label dengan label Traefik dan yang berada di jaringan proxy yang dapat diakses dari luar.

Ketahanan data, volume, dan struktur disk.

Homelab tanpa data persisten tidak akan terlalu berguna: basis data, konfigurasi, media, dokumen… semuanya harus tetap ada meskipun Docker Compose dihentikan. Volume dan bind mount adalah penyelamat Anda.

Banyak orang mengatur penyimpanan mereka menggunakan struktur seperti ini:

/mnt/storage/
├── downloads/
│   ├── movies/
│   └── tv/
├── media/
│   ├── movies/
│   ├── tv/
│   └── music/
└── srv/
    └── 

Idenya adalah bahwa pengunduh (qBittorrent, SABnzbd, dll.) hanya melihat folder unduhan , pengelola seperti Radarr/Sonarr memiliki akses ke unduhan dan media (untuk memindahkan/membuat tautan keras), dan server seperti Plex atau Jellyfin hanya melihat folder media.

Dengan cara ini Anda menerapkan prinsip hak akses minimal : setiap kontainer hanya mengakses apa yang benar-benar dibutuhkannya. Dan pemisahan yang jelas juga membantu saat memutuskan volume atau jalur mana yang akan dicadangkan ke cloud atau drive eksternal.

Direktori srv biasanya digunakan untuk menyimpan konfigurasi aplikasi (misalnya, /srv/jellyfin/config, /srv/traefik, /srv/paperless, dll.). Direktori ini biasanya sebagian diatur versinya (template, Caddyfile, dll.), dengan menghilangkan hal-hal penting atau yang membutuhkan banyak sumber daya.

Dalam beberapa kasus, ada baiknya menggunakan hard link dalam rantai unduhan: layanan seperti Radarr atau Sonarr dapat menautkan file yang diunduh untuk mempertahankan seeding tanpa menduplikasi ruang disk. Struktur direktori yang diusulkan oleh panduan seperti TRaSHGuides didasarkan tepat pada prinsip ini.

Mengotomatiskan deployment dengan GitHub Actions dan runner lokal.

Jika Anda ingin melangkah lebih jauh, Anda dapat mengotomatiskan pembaruan homelab dengan CI/CD . Beberapa pengguna telah mengganti Jenkins dan alat serupa dengan alur kerja menggunakan GitHub Actions dan runner yang di-hosting sendiri di dalam homelab.

Mekanismenya sederhana: setiap kali Anda melakukan push ke branch utama repositori homelab Anda, alur kerja GitHub Actions akan diluncurkan yang menjalankan pengujian, linter, dan, jika semuanya berjalan lancar, akan menyebarkan perubahan ke server.

Alur kerja tipikal mencakup langkah-langkah seperti:

• Pemindai rahasia tipe Gitleaks: jika Anda secara tidak sengaja mengunggah kata sandi atau token ke repositori.
• linting dari YAML atau kode infrastruktur, untuk mempertahankan format yang mudah dibaca dan konsisten.
• Memperbarui repositori di dalam homelab itu sendiri: Lakukan git pull pada server target.
• Rekreasi terkontrol dari kontainer: Hentikan yang lama, luncurkan yang baru, dan periksa statusnya.

Keuntungan: keamanan tambahan (Anda mengontrol kebocoran rahasia), kualitas kode yang lebih baik, dan penerapan yang dapat diulang dengan sekali push . Dan karena Anda menggunakan runner lokal, image dan volume tidak meninggalkan jaringan Anda; Anda cukup memanfaatkan antarmuka GitHub untuk memvisualisasikan pipeline.

Mengapa Docker Compose membuat hidup jauh lebih mudah di lab rumahan?

Banyak orang telah bertahun-tahun mengandalkan Docker Run dan Portainer hingga, setelah insiden atau migrasi, mereka terpaksa mengevaluasi kembali pendekatan mereka. Ketika Anda kehilangan host atau harus memindahkan layanan ke mesin lain, bergantung pada perintah atau konfigurasi terisolasi hanya di dalam Portainer adalah jebakan.

Perbedaan besar saat Anda beralih ke Compose adalah seluruh definisi layanan menjadi teks : volume, port, jaringan, label, variabel… Semuanya dalam file YAML yang dapat Anda salin, bagikan, buat versi, dan gunakan kembali.

Mengedit layanan tidak lagi berarti "membangun ulang kontainer secara manual"; sekarang cukup memodifikasi satu baris dalam file, menyimpan, dan menjalankan `docker compose up -d` . Anda tidak perlu mengingat perintah aslinya atau mengklik beberapa layar Portainer.

Selain itu, jika Anda bekerja dengan beberapa server (mini PC, NAS, desktop), sangat nyaman untuk dapat menyalin file Compose yang sama ke mesin lain, menyesuaikan empat jalur, dan menjalankan tumpukan yang sama pada perangkat keras yang berbeda . Bahkan, banyak orang mengakui bahwa, setelah kejadian yang menimbulkan kekhawatiran terkait kehilangan data atau migrasi yang kacau, Compose telah menghemat banyak waktu mereka dalam kejadian selanjutnya.

Sebagai bonus tambahan, membangun layanan baru dari layanan lama menjadi sangat mudah: misalnya, mengkloning konfigurasi Plex untuk menyiapkan Jellyfin dengan menggunakan kembali jalur media dan perangkat transcoding yang sama hanya membutuhkan beberapa menit jika Anda melakukannya dengan menyalin blok YAML.

Optimasi: konteks pembangunan, pembangunan multi-tahap, dan sumber daya.

Meskipun banyak kontainer Homelab berasal dari image publik, dalam beberapa kasus Anda perlu mengkompilasi sendiri. Dalam hal ini, penting untuk mengelola konteks build Anda : jangan mengunggah seluruh repositori tanpa filter, tetapi batasi diri Anda pada folder proyek Anda (menggunakan arahan `.dockerignore` yang kuat) untuk memastikan build yang cepat dan ringan.

Teknik lain yang sangat berguna adalah menggunakan build multi-tahap dalam Dockerfile Anda: pada tahap pertama Anda menginstal dependensi dan melakukan kompilasi, dan pada tahap kedua Anda hanya menyalin artefak yang diperlukan ke image dasar yang kecil. Hasilnya: image akhir yang jauh lebih kecil dan lebih aman , karena tidak membawa toolchain atau library yang tidak perlu.

Di sisi Compose, Anda memiliki opsi untuk menentukan batasan CPU dan RAM (terutama di lingkungan Swarm atau ketika Docker menghormati parameter tersebut) untuk mencegah aplikasi yang boros sumber daya memakan banyak sumber daya. Di Homelabs, ini membantu mencegah layanan yang salah konfigurasi melumpuhkan sistem lainnya.

Jangan lupakan kebijakan restart (restart: selalu, kecuali dihentikan, saat terjadi kegagalan): dengan kebijakan ini Anda memastikan bahwa layanan penting (reverse proxy, VPN, basis data utama) akan restart secara otomatis setelah reboot atau kegagalan yang terjadi sekali saja.

Terakhir, disarankan untuk menjadwalkan tugas pembersihan berkala dengan perintah seperti docker image prune, docker container prune, dan docker volume prune untuk menghapus sisa-sisa build lama, kontainer yang dihentikan, atau volume yang tidak terpakai, sehingga dapat memulihkan ruang disk.

Layanan kesehatan, pencatatan, dan pemantauan.

Untuk mencegah homelab Anda menjadi kotak hitam, penting untuk mengerjakan tiga aspek kunci: pemeriksaan kesehatan, pencatatan log yang terkontrol, dan pemantauan . Docker Compose memungkinkan Anda untuk mendeklarasikan pemeriksaan kesehatan per layanan (menggunakan perintah seperti `curl -f http://localhost` atau skrip khusus) yang menentukan apakah sebuah kontainer sehat.

Hal ini memungkinkan Anda untuk memastikan bahwa hanya kontainer yang "sehat" yang menerima lalu lintas (misalnya, melalui Traefik) dan bahwa jika kontainer tersebut berhenti merespons, kontainer tersebut akan dihidupkan ulang sesuai dengan kebijakan yang telah dikonfigurasi. Ini secara signifikan meningkatkan ketahanan dengan upaya minimal.

Terkait log, menyesuaikan driver file json dengan batasan ukuran maksimum dan jumlah file maksimum mencegah disk terisi penuh dengan gigabyte log yang terlupakan. Alat web seperti Dozzle membantu Anda menelusuri log semua kontainer dari browser, yang sangat nyaman untuk men-debug layanan tertentu.

Untuk metrik dan pemantauan berkelanjutan, kombinasi klasiknya adalah cAdvisor + Prometheus + Grafana . cAdvisor mengekspos statistik penggunaan CPU, memori, disk, dan jaringan per kontainer; Prometheus mengumpulkannya secara berkala, dan Grafana menampilkannya dalam dasbor yang menarik, dengan peringatan jika terjadi lonjakan.

Homelab yang tertata dengan baik biasanya mencakup Uptime Kuma untuk pengecekan ketersediaan (HTTP, ICMP, TCP, dll.) dan sistem pencadangan otomatis seperti Duplicati untuk menyalin data penting ke disk lain atau cloud. Dengan cara ini, Anda tahu apa yang terjadi, dan jika terjadi kesalahan, Anda tidak akan kehilangan data penting.

Keamanan dan akses jarak jauh ke homelab

Namun, terlepas dari bagaimana cara melakukan pengaturan sendiri, keamanan bukanlah pilihan. Banyak orang memilih untuk tidak secara langsung mengekspos NAS atau layanannya ke dunia luar , membatasi akses jarak jauh melalui VPN (WireGuard adalah pilihan yang sangat populer karena kinerja dan kesederhanaannya).

Dalam model ini, router bertindak sebagai gateway: hanya port acak yang dibuka ke server VPN, dan setelah terhubung, semua permintaan ke layanan internal melewati terowongan terenkripsi . Baik Traefik maupun aplikasi tidak terekspos ke internet tanpa penyaringan sebelumnya ini.

Mereka yang lebih memilih untuk tidak mengelola VPN sendiri terkadang beralih ke Cloudflare Tunnel atau Tailscale untuk mengakses lab rumahan mereka tanpa membuka port. Ini adalah alternatif yang nyaman, meskipun jika privasi adalah prioritas utama Anda, Anda perlu mempertimbangkan metadata apa yang mungkin dikumpulkan oleh pihak ketiga ini.

Praktik baik lainnya adalah mengenkripsi disk server dan NAS , menerapkan patch secara teratur, dan membatasi pembaruan otomatis (banyak yang menghindari Watchtower dan lebih memilih pembaruan manual yang terkontrol). Lebih baik sedikit tertinggal tetapi tetap terkontrol daripada merusak sebagian besar Homelab karena pembaruan yang belum Anda periksa.

Seperti yang Anda lihat, Anda tidak perlu mencapai level "perusahaan", tetapi disarankan untuk menetapkan tingkat keamanan dan disiplin minimum agar homelab Anda tidak menjadi celah keamanan atau sumber ketakutan yang terus-menerus.

Pada akhirnya, membangun homelab yang serius dengan Docker Compose adalah perpaduan antara organisasi, akal sehat, dan kemauan untuk bereksperimen: jika Anda mengelompokkan layanan, mendefinisikan jaringan dengan baik, mendokumentasikan di Git, dan melakukan otomatisasi sedikit demi sedikit, Anda akan mendapatkan lingkungan yang dapat Anda mulai dengan satu perintah, bermigrasi ke mesin lain dengan mudah, dan berkembang sedikit demi sedikit tanpa menjadi hutan belantara yang tidak terkendali.