Docker Compose en homelab: organització, perfils i bones pràctiques

Informatec Digital » Recursos » Docker Compose en homelab: organització, perfils i bones pràctiques

Muntar un homelab modern amb contenidors ha esdevingut el hobby favorit de molta gent tech. Docker Compose és gairebé sempre el cor d'aquest muntatge : defineix els teus serveis a YAML, els versions amb Git i pots aixecar tot el teu entorn amb una sola ordre.

Ara bé, quan comences a créixer passen coses: passes de tenir dos o tres contenidors a desenes de serveis, xarxes internes, proxys inversos, bases de dades i runners de CI . Aquí és quan sorgeix el dubte gros: un únic docker-compose gegant o molts fitxers petits? com organitzo perfils, xarxes, backups, seguretat, ia sobre ho faig fàcil de migrar?

Enfocaments reals per organitzar Docker Compose en un homelab

A la pràctica, la gent que fa temps que té homelabs sol moure's en tres models d'organització de Compose, cadascun amb els seus avantatges i inconvenients. Triar bé l'enfocament t'estalvia molt de dolor en créixer o migrar de màquina.

D'una banda hi ha qui va començar amb docker run solts, després va passar a Portainer i va acabar saltant a Docker Compose . És el típic: Portainer dóna molta visibilitat, interfície còmoda, plantilles, etc., però al final editar paràmetres complexos o migrar configuracions es torna un embolic si no tens res en fitxers.

A l'extrem oposat hi ha qui ho ha consolidat tot en un únic “mega” docker-compose.yml capaç d'aixecar absolutament tots els serveis de l'homelab: proxy invers, mitjana, utilitats, monitorització, LLMs, bases de dades… Tot en un sol stack.

Entre mitges, molts usuaris es queden amb un enfocament mixt: diversos docker-compose.yml petits agrupats per context (per exemple, mitjana, infraestructura, productivitat, monitorització), tots sota un mateix repositori i normalment compartint variables d'entorn globals.

Una solució força elegant barreja tots dos mons: un docker-compose “arrel” que fa include d'altres fitxers (cadascú en una subcarpeta d'apps o services). Així, mantenes una visió global de l'homelab, però sense patir un YAML de mil línies impossible de llegir.

Perfils, agrupació per funcions i homelabs de grans dimensions

Quan el teu homelab comença a fregar els 30, 40 o 50 serveis (incloent serveis de suport com a bases de dades, caixets o indexadors) és vital posar ordre. Aquí entren en joc tant l' agrupació per funció com l'ús de perfils de Docker Compose.

Un patró molt habitual és agrupar-ho tot en un únic “projecte” Compose, però dividit lògicament per perfils. Per exemple:

• Perfil core: nucli de l'homelab, amb Traefik com a reverse proxy i un proveïdor d'identitat (per exemple, OAuth o Authentik) per autenticar totes les apps sota un mateix domini amb HTTPS.
• Perfil mitjana: serveis estil Plex, Sonarr, Radarr, Ombi, SABnzbd o qBittorrent, responsables de curar, descarregar i servir contingut multimèdia.
• Perfil utilities: eines com Portainer, Watchtower (si es fa servir), Diun, dockcheck o similars per gestionar i vigilar contenidors i actualitzacions.
• Perfil infra/monitoring: Traefik, cAdvisor, Prometheus, Grafana, Uptime Kuma, Dozzle i tot allò relatiu a monitorització i logging.
• Perfils experimentals o LLM: piles específiques per a LLMs o apps curioses (ChatGPT Next Web local, LibreOffice Online, etc.) que solen venir desactivades per defecte.

La gràcia dels perfils és que pots llançar només una part de la infraestructura segons t'interessi. Per exemple, executar només el perfil core + infra en un mini PC de baixa potència, i aixecar el perfil mitjana únicament al servidor gran amb més discos i GPU.

En repositoris ben pensats, sol haver-hi a l'arrel un docker-compose.yml “mestre” que tira d'include cap a fitxers individuals en una carpeta apps/ o services/ . A més, gairebé tots els serveis es configuren via un únic fitxer .env global i alguns secrets en un directori secrets/ , cosa que simplifica molt la configuració inicial.

Seguint aquest patró, la gestió de l'homelab es redueix bàsicament a editar el .env i els secrets, activar o desactivar perfils i decidir quins serveis arrenques a cada host . Ideal si desplegareu el mateix conjunt d'aplicacions en diversos equips.

Un sol docker-compose gegant vs diversos fitxers petits

Aquesta és la discussió eterna: un únic docker-compose.yml amb tot a dins o diversos fitxers per servei/stack? La resposta real sol ser “depèn del que vulguis prioritzar: simplicitat de migració o claredat per servei”.

Qui defensa el fitxer mestre únic sol destacar diversos avantatges:

• Migrar de host és facilíssim: clones el repositori, copies el .env i els secrets, muntes els volums i fas un docker compose up -d. No cal anar directori per directori.
• Infraestructura com a codi de veritat: tota la topologia de l'homelab (serveis, xarxes, volums, dependències) és en un sol lloc.
• Actualitzacions centralitzades: canvies una versió d'imatge, una política de reinici o una mica de logging i saps exactament on tocar.

Però també té pegues clares: un YAML enorme és més difícil de mantenir, els conflictes de merges augmenten ia l'hora de depurar un problema concret et veus navegant un monstre de centenars de línies. No és rar penedir-se una mica quan tot creix massa.

L'altre enfocament és tenir un docker-compose.yml per app o per stack lògic , dins d'una estructura tipus:

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

Amb això, cada contenidor es diu alguna cosa com bookstack-app-1 o traefik-reverse-proxy-1 , la qual cosa t'ajuda a localitzar problemes ràpid: si el contenidor bookstack-app-1 peta, ja saps exactament a quina carpeta mirar.

Visualment és molt més net i permet gestionar cada servei de manera independent (arrencar-lo, aturar-lo o actualitzar-lo sense tocar la resta). A més, hi ha aplicacions com Dozzle que s'aprofiten de tenir stacks separats per organitzar millor els logs.

La contrapartida és que si separes tot massa, la coordinació entre serveis comuns (com Traefik o xarxes compartides) exigeix ​​una mica més de cura : cal declarar xarxes externes, etiquetes específiques de Traefik i recordar la nomenclatura de les xarxes creades per altres docker-compose.

Bones pràctiques amb .env, overrides i control de versions

Un dels trucs més infravalorats és centralitzar la configuració en fitxers .env . En lloc d'inundar el vostre docker-compose.yml amb variables d'entorn, es defineix una cosa així:

DB_USERNAME=myuser
DB_PASSWORD=secretpassword

I després al YAML es referencien com a ${DB_USERNAME} o ${DB_PASSWORD} . Això fa que el compose es llegeixi d'una ullada, us permet compartir variables entre múltiples serveis i, sobretot, desar contrasenyes en un fitxer separat (que podeu excloure de Git).

Per a entorns diferents (producció, proves, desenvolupament) és molt útil aprofitar docker-compose.override.yml . La idea és tenir un docker-compose.yml base i, a l'override, només sobreescriure el que canvia: ports, rutes, flags de depuració…

Per exemple, en desenvolupament pots carregar un override on exposes un port diferent, actives DEBUG i muntes el codi font local . No toques el YAML principal, però adaptes l'stack a l'entorn on el llences.

Òbviament, versionar tot amb Git és obligatori si vols que l'homelab sigui mínimament seriós . Sols tenir alguna cosa com:

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

A partir d'aquí, inicialitzes el repo, fas commits amb els canvis d'infraestructura i, si es trenca alguna cosa, pots tornar a una versió anterior dels teus Compose en segons . Per a homelabs una mica ambiciosos, això no és una opció, és l'única manera de no tornar-te boig.

Xarxes, Traefik i exposició segura de serveis

A gairebé tots els homelabs mitjanament avançats apareix el mateix combo: Traefik com a reverse proxy i un proveïdor d'identitat centralitzat (Auth o Authentik) . Això permet exposar moltes aplicacions sota subdominis amb HTTPS i SSO.

Un patró clàssic és muntar una xarxa Docker dedicada, per exemple reverse_proxy o similar, on es connecten Traefik i tots els serveis web que serviràs cap a fora. La resta de contenidors (bases de dades, caixets, etc.) romanen en xarxes internes aïllades.

Si fas servir Traefik i separes els teus serveis en docker-compose diferents, necessites definir una xarxa externa compartida . Una cosa així:

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

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

Aquí la xarxa traefik_default la crea l'stack de Traefik, i la resta de serveis s'hi afegeixen via una xarxa externa anomenada traefik-net. Les etiquetes indiquen a Traefik quina xarxa heu d' utilitzar per encaminar el trànsit.

Quan un mateix stack inclou serveis de backend (per exemple, un contenidor web i la base de dades) pots connectar-los a una xarxa per defecte compartida, i només al contenidor web donar-li accés a la xarxa de Traefik . La base de dades tindrà un label traefik.enable=false perquè Traefik la ignori.

Aquest tipus de muntatge et dóna dos beneficis clau: aïllament entre serveis i exposició controlada . Només els contenidors que tu marques amb labels de Traefik i que són a la xarxa del proxy arriben a ser accessibles des de fora.

Persistència de dades, volums i estructura de discos

Un homelab sense dades persistents no serveix de gaire: bases de dades, configuracions, mitjana, documents… tot ha de sobreviure a un docker compose down. Els volums i els bind mounts són la teva assegurança de vida.

Molta gent organitza l'emmagatzematge amb una estructura tipus:

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

La idea és que els descarregadors (qBittorrent, SABnzbd, etc.) només vegin la carpeta downloads , els gestors tipus Radarr/Sonarr tinguin accés tant a downloads com a mitjana (per moure/crear hardlinks) i els servidors com Plex o Jellyfin només vegin la carpeta mitjana.

D'aquesta manera apliques el principi de mínim privilegi : cada contenidor només accedeix al que realment necessita. I la separació clara ajuda també a l'hora de decidir quins volums o rutes es recolzaran al núvol oa discos externs.

Al directori srv solen viure les configuracions de les apps (per exemple, /srv/jellyfin/config, /srv/traefik, /srv/paperless, etc.). Això se sol versionar parcialment (plantilles, Caddyfile, etc.), deixant fora allò purament sensible o pesat.

Per a alguns casos, és interessant fer servir hardlinks a la cadena de descàrrega: serveis tipus Radarr o Sonarr poden enllaçar els fitxers descarregats per mantenir el seeding sense duplicar espai en disc. El disseny de directoris proposat per guies com TRaSHGuides es basa precisament en això.

Automatització de desplegaments amb GitHub Actions i runners locals

Si us agrada arrissar el ris, podeu anar un pas més enllà i automatitzar l'actualització de l'homelab amb CI/CD . Diversos usuaris han reemplaçat Jenkins i similars per un flux amb GitHub Actions i un runner auto-allotjat al propi homelab.

El mecanisme és senzill: cada cop que fas push a la branca principal del teu repo d'homelab, es llança un workflow de GitHub Actions que executa proves, linters i, si tot va bé, desplega els canvis al servidor.

Un flux típic inclou passos com:

• Escàner de secrets tipus Gitleaks: per si per descuit has pujat contrasenyes o tokens al repo.
• Dinteles de YAML o del codi d'infraestructura, per mantenir el format llegible i consistent.
• Actualització del repositori al propi homelab: git pull al servidor objectiu.
• Recreació controlada de contenidors: aturar els vells, llançar els nous i verificar estat.

Avantatges: seguretat addicional (controles fuites de secrets), millor qualitat de codi i desplegaments repetibles amb un sol push . I com uses un runner local, les imatges i volums no surten de la teva xarxa; simplement aprofites la interfície de GitHub per visualitzar els pipelins.

Per què Docker Compose facilita tant la vida en un homelab

Molta gent ha passat anys fent de docker run i Portainer fins que, arran d'un incident o una migració, s'ha vist forçada a reavaluar el seu enfocament. Quan perds un host o has de moure serveis a una altra màquina, dependre de comandes soltes o de configuracions només a Portainer és un parany.

La gran diferència en passar-te a Compose és que tota la definició del servei passa a ser text : volums, ports, xarxes, labels, variables… Tot en un YAML que pots copiar, compartir, versionar i reutilitzar.

Editar un servei deixa de ser “reconstruir un contenidor a mà” i passa a ser modificar una línia en un fitxer, desar i fer docker compose up -d . No has d'acordar-te de l'ordre original, ni fer clic per diverses pantalles de Portainer.

A més, si treballes amb diversos servidors (mini PCs, NAS, sobretaules) és extremadament còmode poder copiar un mateix fitxer compose a una altra màquina, ajustar quatre rutes i llançar el mateix stack amb un altre maquinari . De fet, moltes persones reconeixen que, després d'un ensurt de pèrdua de dades o migracions caòtiques, Compose els ha salvat molt de temps en esdeveniments posteriors.

Com a extra, compondre nous serveis a partir d'antics es torna trivial: per exemple, clonar la configuració de Plex per muntar Jellyfin reutilitzant les mateixes rutes de mitjans i dispositius de transcodificació només fa uns minuts si ho fas copiant blocs de YAML.

Optimització: build context, multi-stage builds i recursos

Encara que molts contenidors d'homelab vénen d'imatges públiques, en alguns casos compilareu les vostres pròpies imatges. Aquí convé cuidar el build context : no enviar tot el repositori sense filtrar, sinó limitar-te a la carpeta del projecte (amb un bon .dockerignore) perquè les builds siguin ràpides i lleugeres.

Una altra tècnica molt útil és recórrer a multi-stage builds als teus Dockerfiles: en una primera fase instal·les dependències i compil·les, i en una segona fase còpies només els artefactes necessaris a una imatge base petita. Resultat: imatges finals molt més petites i segures , perquè no arrosseguen toolchains ni llibreries de més.

Al costat de Compose, tens l'opció de definir límits de CPU i RAM (sobretot en entorns Swarm o quan Docker respecta aquests paràmetres) per evitar que una app goluda acapari recursos. A homelabs això ajuda que un servei mal configurat no deixi sec la resta del sistema.

No us oblideu de les polítiques de reinici (restart: always, unless-stopped, on-failure): amb elles t'assegures que els serveis crítics (proxy invers, VPN, bases de dades clau) tornin a aixecar-se sols després d'un reboot o una fallada puntual.

Finalment, convé marcar tasques periòdiques de neteja amb comandes com docker image prune, docker container prune i docker volum prune per anar eliminant residus de builds antigues, contenidors detinguts o volums orfes i així recuperar espai en disc.

Salut de serveis, logging i monitorització

Perquè el teu homelab no sigui una caixa negra, és important treballar tres potes: healthchecks, logging controlat i monitorització . Docker Compose permet declarar healthcheck per servei (ordres tipus curl -f http://localhost o scripts específics) que determinen si un contenidor es considera sa.

Amb això pots fer que només els contenidors “healthy” rebin trànsit (per exemple, a través de Traefik) i que, si deixen de respondre, es reiniciïn seguint la política configurada. Això puja força la resiliència amb un esforç mínim.

Quant a logs, ajustar el driver json-file amb límits de max-size i max-file evita que el disc s'ompli amb gigues de logs oblidats. Eines web com Dozzle ajuden a navegar pels logs de tots els contenidors des d'un navegador, una cosa molt còmoda per depurar serveis concrets.

Per la part de mètriques i monitorització contínua, el combo clàssic és cAdvisor + Prometheus + Grafana . cAdvisor exposa estadístiques dús de CPU, memòria, disc i xarxa per contenidor; Prometheus les recol·lecta periòdicament i Grafana les mostra en panells atractius, amb alertes si alguna cosa es dispara.

Un homelab ben muntat sol incloure a més Uptime Kuma per a revisions de disponibilitat (HTTP, ICMP, TCP…) i algun sistema de backups automatitzats tipus Duplicati per copiar les dades crítiques a altres discos o al núvol. Així saps què està passant i, si alguna cosa rebenta, no perds allò important.

Seguretat i accés remot a l'homelab

Per molt casolà que sigui el muntatge, la seguretat no és opcional. Molta gent opta per no exposar directament el NAS ni els serveis a l'exterior , limitant l'accés remot a través d'una VPN (WireGuard és una opció molt popular per rendiment i senzillesa).

En aquest model, el router fa de porta d'entrada: només s'obre un port aleatori cap al servidor VPN, i un cop connectat totes les peticions a serveis interns passen per un túnel xifrat . Ni Traefik ni les apps s'exposen a Internet sense aquest filtre previ.

Qui prefereix no gestionar la seva pròpia VPN de vegades recorre a Cloudflare Tunnel o Tailscale per arribar a l'homelab sense obrir ports. Són alternatives còmodes, encara que si la teva prioritat absoluta és la privadesa, hauràs de valorar quines metadades poden recopilar aquests tercers.

Una altra bona pràctica és xifrar els discos del servidor i del NAS , aplicar pegats regularment i limitar les versions automàtiques (molts eviten Watchtower a favor d'actualitzacions manuals controlades). Val més anar una mica per darrere però amb control, que trencar mig homelab per un update que no has revisat.

Com es veu, no cal arribar a un nivell “enterprise”, però sí que convé establir unes bases mínimes de seguretat i disciplina perquè el teu homelab no sigui un colador ni una font constant d'ensurts.

Al final, muntar un homelab seriós amb Docker Compose és una barreja d'organització, sentit comú i ganes de fer catxa: si agrupar serveis, defineixes bé les xarxes, documentes a Git i automatitzes una mica, et queda un entorn que pots aixecar amb una sola comanda, migrar a una altra màquina amb facilitat i ampliar a poc a poc sense que es converteixi en una selva.