Plantillas y stacks de Compose

Stacks de Compose

Un stack es un docker-compose.yml completo desplegado como una unidad, junto a tus aplicaciones y bases de datos. No hay paso de build: desplegar un stack es un docker compose up en el servidor de destino. Cada stack tiene su propia página de detalle con las pestañas General, Compose, Environment, Domains, Deployments, Logs, Terminal, Monitoring y Tasks, de modo que los logs, las métricas y el terminal funcionan por servicio dentro del stack.

Para crear uno, abre un proyecto, ve a la sección Stacks y haz clic en Add Stack. Ponle un nombre (letras minúsculas, números y guiones) y pega tu archivo Compose. El nombre pasa a ser el nombre del proyecto Compose dk-<name>, que actúa como prefijo de todos los contenedores, redes y volúmenes del stack. Un stack pegado no se inicia automáticamente: añade tus dominios y luego haz clic en Redeploy.

services:
  app:
    image: nginx:alpine
    restart: unless-stopped
    expose:
      - "80"

Qué cambia DeployKit en tu archivo Compose

Tu YAML se guarda exactamente como lo escribiste. En el momento del despliegue, DeployKit aplica algunos cambios solo en memoria:

• Se añaden etiquetas de propiedad a cada servicio — así es como los logs, las métricas y el terminal encuentran los contenedores del stack.
• Se elimina container_name, de modo que el mismo stack o plantilla pueda desplegarse dos veces sin colisiones de nombres.
• Los servicios con dominio reciben etiquetas de enrutamiento de Traefik y se unen a la red compartida deploykit-network. Sus puertos publicados se convierten a expose, ya que Traefik llega a ellos a través de esa red.
• Los servicios sin dominio se dejan tal cual y solo son accesibles desde dentro del stack (por nombre de servicio).

Prefiere expose a ports y evita container_name. No escribas nunca etiquetas de Traefik tú mismo — DeployKit las inyecta.

Dominios, variables de entorno y volúmenes

• Domains — en la pestaña Domains elige el Service, el Container port y el Domain (opcionalmente una ruta). Un servicio puede tener varios dominios. Marca “Request an HTTPS certificate” solo cuando el dominio ya resuelva a este servidor.
• Environment — las variables se cifran en reposo y se escriben en un archivo .env junto al archivo Compose, de modo que las referencias ${VAR} de tu YAML las rellena el propio Compose.
• Volumes — los volúmenes con nombre y los bind mounts relativos funcionan igual que en Compose estándar. Los archivos del stack viven en /var/lib/deploykit/compose, un directorio por stack.
• Redeploy — editar el archivo Compose, el entorno o los dominios se guarda al instante, pero solo se aplica en el siguiente Redeploy, que vuelve a descargar las imágenes y recrea los contenedores.

Plantillas con un clic

La página Templates de la barra lateral lista stacks ya preparados del catálogo público deploykit-templates — bases de datos, aplicaciones autoalojadas y stacks completos. Busca por nombre o filtra por etiqueta y haz clic en una tarjeta para desplegarla. Desplegar una plantilla crea un stack de Compose normal que gestionas como cualquier otro.

El diálogo de despliegue pide:

• Name — da nombre al stack y a todos los contenedores que contiene.
• Domain (opcional) — el nombre de host con el que se sirve la plantilla. Déjalo vacío y DeployKit genera uno (ver más abajo).
• Project — cuando abres el diálogo desde la página Templates en lugar de desde un proyecto.
• Server — dónde se ejecuta el stack.

Las plantillas nunca incluyen credenciales. Las contraseñas, claves y tokens se generan desde cero en tu servidor en cada despliegue y se guardan cifrados en el entorno del stack. El despliegue comienza de inmediato y el diálogo de resultado muestra las URL del stack y las credenciales generadas.

Nombres de host generados

Para que una plantilla funcione sin ninguna configuración de DNS, un dominio vacío se genera en este orden:

Define estas variables en el .env de DeployKit y reinicia. Los nombres de host sslip.io no pueden obtener certificados, así que en producción introduce tu propio dominio o configura TEMPLATES_BASE_DOMAIN.

# /opt/deploykit/.env
TEMPLATES_BASE_DOMAIN=apps.example.com   # *.apps.example.com -> this server
PUBLIC_IP=203.0.113.10                    # fallback for sslip.io hostnames

El catálogo de plantillas

Ninguna plantilla viene incluida dentro de DeployKit: el catálogo se obtiene en tiempo de ejecución desde TEMPLATES_REGISTRY_URL (por defecto, la URL raw de GitHub de deploykit-templates). Las plantillas nuevas publicadas allí aparecen en todas las instancias en aproximadamente una hora, sin actualizar DeployKit. Puedes apuntar esta variable a tu propio fork; debe ser una dirección http(s) pública — las direcciones privadas y de loopback se rechazan.

• El catálogo se vuelve a leer como máximo una vez por hora, y la última copia válida se guarda en caché durante 30 días.
• Si el registro no está accesible, la página Templates sigue funcionando con esa copia en caché y muestra un aviso con la hora en que se obtuvo.
• Solo una instancia que nunca ha llegado a alcanzar el registro muestra una página vacía, explicando que no se puede acceder al registro — revisa el acceso saliente a internet del servidor o TEMPLATES_REGISTRY_URL.

Escribir tu propia plantilla

Una plantilla es un directorio del catálogo con un docker-compose.yml, un template.json (metadatos, variables, dominios, env y montajes de archivos de configuración) y un logo opcional. Las variables usan helpers generadores como ${domain}, ${password:32}, ${base64:64}, ${uuid} o ${jwt:<secretVar>:<role>}; los dominios, el env y los montajes hacen después referencia a esas variables por su nombre.

Onboarding

En una instancia recién instalada, el panel muestra una lista de comprobación Welcome to DeployKit: Connect a server (los Admin pueden hacer clic en Use local server), Create a project y Deploy from a template, que abre la página Templates. Desaparece cuando la instancia tiene su primera aplicación o base de datos.