Alojar Homepage en su propio VPS

Homepage (gethomepage.dev) es un dashboard escrito en Next.js, concebido para ser la página de inicio de su infraestructura. A diferencia de las soluciones SaaS de tipo start page, todo permanece bajo su control: la configuración vive en simples archivos YAML, los widgets consultan sus propios servicios (Proxmox, qBittorrent, Sonarr, Pi-hole…) y ningún dato pasa por una nube externa. Alojarlo en un VPS lo hace accesible desde cualquier parte y cualquier navegador.

Es también el punto de entrada ideal para pilotar una stack Docker en crecimiento: un solo archivo services.yaml basta para cartografiar decenas de contenedores. Conforme su infraestructura gana en complejidad — múltiples aplicaciones, múltiples subdominios, servicios en varios VPS — Homepage se convierte en el único cockpit desde el que comprueba el estado de cada uno de un vistazo, sin abrir cinco pestañas.

Homepage es muy ligero. Un VPS con 1 vCPU y 512 MB de RAM es suficiente en la práctica, incluso sumando otros contenedores. Cuente con unos 300 MB de espacio en disco para la imagen y la configuración. Necesitará:

- Docker y Docker Compose v2 instalados (verifique con docker compose version).
- Un nombre de dominio o subdominio apuntando a la IP pública del VPS, por ejemplo home.sudominio.com.
- Un reverse proxy — Caddy o Traefik — para gestionar el HTTPS y el certificado Let's Encrypt.
- El socket Docker /var/run/docker.sock montado en solo lectura si quiere usar los widgets Docker y el descubrimiento automático — o, más seguro, un proxy de socket (vea la sección de seguridad).

Si parte de un VPS limpio, instale Docker según la documentación oficial, luego active el arranque automático con systemctl enable --now docker.

Los widgets son el valor añadido de Homepage sobre una simple lista de enlaces. Cada widget consulta la API de su servicio objetivo y muestra métricas en tiempo real directamente en la tarjeta.

Para activar un widget, añada un bloque widget bajo la declaración del servicio en services.yaml. Ejemplo con Portainer:

- Portainer:
    href: https://portainer.sudominio.com
    widget:
      type: portainer
      url: https://portainer.sudominio.com
      env: 1
      key: {{HOMEPAGE_VAR_PORTAINER_KEY}}

Las claves de API nunca deben escribirse en texto plano en services.yaml si ese archivo está versionado en un repositorio público. Páselas al contenedor como variables de entorno con el prefijo HOMEPAGE_VAR_, por ejemplo desde un archivo .env cargado con env_file: .env en el docker-compose.yml, y referéncielas con la notación {{HOMEPAGE_VAR_PORTAINER_KEY}} en el YAML: Homepage sustituye cada {{HOMEPAGE_VAR_…}} por el valor de la variable.

Otros widgets muy utilizados: Proxmox (CPU, RAM, almacenamiento del clúster), Pi-hole (peticiones bloqueadas, clientes activos), Sonarr / Radarr (descargas en curso), Grafana (paneles embebidos), Uptime Kuma (estado de cada monitor). La lista completa está en la documentación oficial de gethomepage.dev.

Un dashboard que lista todos sus servicios es un objetivo atractivo. Dos medidas básicas son necesarias antes de exponer Homepage en Internet.

Restringir el acceso por IP o autenticación. Si Homepage es solo para usted, la solución más sencilla es permitir solo su dirección IP en la configuración del reverse proxy. Con Caddy:

home.sudominio.com {
    @allowed remote_ip 203.0.113.42
    handle @allowed {
        reverse_proxy localhost:3000
    }
    respond 403
}

Si accede al dashboard desde varias redes, prefiera la autenticación HTTP básica o un middleware de autenticación como Authelia o Authentik delante de Homepage. Desde la v2.0, Homepage ofrece también su propia puerta de autenticación, por contraseña u OIDC (HOMEPAGE_AUTH_ENABLED=true).

No entregue el socket Docker en bruto. El :ro del montaje /var/run/docker.sock:/var/run/docker.sock:ro solo protege el archivo: la API de Docker sigue plenamente accesible a través de él, y un contenedor comprometido puede crear nuevos contenedores con volúmenes arbitrarios en el host. La documentación de Homepage recomienda un proxy de socket (docker-socket-proxy) que solo permita lecturas: CONTAINERS=1 y POST=0, puerto enlazado a 127.0.0.1, y luego host: dockerproxy y port: 2375 en config/docker.yaml.

Actualice la imagen con regularidad. Use docker compose pull && docker compose up -d para actualizar Homepage en cuanto haya una nueva imagen disponible. Puede automatizar esto con una tarea cron. Watchtower, recomendado durante mucho tiempo para ello, ya no se mantiene: su repositorio de GitHub está archivado.

Toda la configuración de Homepage vive en la carpeta config/: es el único directorio que hay que respaldar. Sin base de datos, sin estado persistente fuera de estos archivos YAML.

Versionar en Git. El método más fiable es inicializar un repositorio Git en ~/homepage/config/ y hacer commit tras cada cambio. Si su configuración contiene claves de API (incluso mediante variables), añada un .gitignore para excluir el archivo .env y versionar solo los YAML.

Copia de seguridad incremental en almacenamiento de objetos. Con restic y un bucket compatible con S3 (Garage, MinIO, Backblaze B2), programe una copia de seguridad diaria desde un cron:

restic -r s3:s3.example.com/mi-bucket/homepage backup ~/homepage/config

Restauración. En caso de pérdida del VPS, recree el contenedor, restaure la carpeta config/ desde la copia de seguridad y ejecute docker compose up -d. Homepage estará operativo en menos de un minuto — una de las ventajas concretas de una configuración 100% declarativa en YAML.

Si prefiere no configurar Docker manualmente, el Marketplace de ServOrbit ofrece Homepage como instalación guiada. Unos pocos clics desde su panel de cliente aprovisionan un VPS con Homepage listo para usar: imagen oficial, puerto enlazado en loopback y volumen de configuración persistente.

El template no instala reverse proxy: declare su subdominio, conecte Caddy o Traefik como se describe más arriba para el HTTPS y restrinja HOMEPAGE_ALLOWED_HOSTS a ese subdominio, ya que la receta lo entrega abierto a todos los hosts (*). Después, personalice los archivos YAML en config/.

Encuentre la ficha completa, los requisitos mínimos y el botón de instalación en la página dedicada del Marketplace.