HomelabGuía

De Portainer a Dockhand: cómo migré mis Docker Stacks sin perder datos

Descubre cómo migrar tus contenedores y Docker Compose Stacks de Portainer a Dockhand sin perder configuraciones ni datos. Una guía paso a paso con ejemplos prácticos, archivos .env, volúmenes persistentes y pruebas de redeploy para realizar una migración segura.

Ilustración de Homelab

De Portainer a Dockhand: migración segura de Docker Compose y archivos .env

Dockhand migration cover

Lab note: Todos los nombres, rutas, puertos y ejemplos de este artículo son genéricos. No se incluye información sobre infraestructura privada ni credenciales.

Después de administrar mis contenedores con Portainer, decidí probar Dockhand. La interfaz me gustó, pero encontré un problema típico: Dockhand veía los contenedores y sus etiquetas de Compose, aunque no encontraba los archivos originales de los stacks. Esta guía reproduce la solución con ejemplos públicos y ficticios.

Why Dockhand?

Dockhand permite gestionar contenedores, stacks, logs, imágenes y varios entornos desde una interfaz web. Lo más útil en esta migración es su función para adoptar stacks existentes sin tener que reconstruirlos inmediatamente. Un stack Untracked está ejecutándose en Docker, pero Dockhand todavía no conoce la ubicación de su archivo Compose.

Official resources: Quick Start · User Manual

Before you begin

Antes de empezar, haz un respaldo del volumen de Portainer y de los datos de las aplicaciones. No confundas los archivos Compose con los datos persistentes. Detener o eliminar Portainer no exige eliminar tus contenedores.

1. Instalar Dockhand

Crea el directorio compartido y guarda el siguiente archivo como /opt/docker/dockhand/compose.yaml. El ejemplo usa el puerto 3100; cambia el puerto si está ocupado. El socket Docker concede control elevado sobre el host: limita el acceso a la interfaz.

bash
sudo mkdir -p /opt/docker/stacks /opt/docker/dockhand
yaml
services:
  dockhand:
    image: fnsys/dockhand:latest
    container_name: dockhand
    restart: unless-stopped
    ports:
      - "3100:3000"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - dockhand_data:/app/data
      - /opt/docker/stacks:/opt/docker/stacks:rw
volumes:
  dockhand_data:
bash
cd /opt/docker/dockhand
docker compose up -d
docker ps --filter name=dockhand

Open http://HOST:3100 and set up the local environment and user.

2. Localizar los stacks de Portainer

Si Portainer usa el volumen llamado portainer_data, normalmente sus archivos se encuentran bajo compose/<ID>/docker-compose.yml. El nombre y la ubicación pueden variar según tu instalación.

bash
docker volume inspect portainer_data --format '{{.Mountpoint}}'
find /var/lib/docker/volumes/portainer_data/_data/compose \
  -type f \( -name '*.yml' -o -name '*.yaml' -o -name '*.env' \)

Back up and copy the definitions (not application data):

bash
sudo mkdir -p /root/docker-migration-backup
sudo tar -czpf /root/docker-migration-backup/portainer-compose.tar.gz \
  -C /var/lib/docker/volumes/portainer_data/_data compose
sudo cp -a /var/lib/docker/volumes/portainer_data/_data/compose/. \
  /opt/docker/stacks/

Migration workflow

3. Adoptar un stack Untracked

Copia los directorios completos, incluidos los archivos stack.env, a una ubicación independiente. En Dockhand, abre Stacks, selecciona el stack Untracked, elige Browse for compose file, selecciona el archivo nuevo y pulsa Save, no Save & redeploy. También puedes utilizar la opción Adopt/Import para buscar varios proyectos. Comprueba que el nombre de proyecto coincida con el existente.

Important: The source file must be accessible inside the Dockhand container. The bind mount /opt/docker/stacks:/opt/docker/stacks makes this possible for the local environment. For remote environments, follow Dockhand's shared-files and agent documentation.

4. Ejemplo 1: un stack sencillo

Este ejemplo inicia un servicio de prueba Whoami. Guárdalo como /opt/docker/stacks/whoami/compose.yaml y despliégalo desde Dockhand. Comprueba http://HOST:8087. Es una prueba nueva, no una copia de datos privados.

yaml
services:
  whoami:
    image: traefik/whoami:latest
    restart: unless-stopped
    ports:
      - "8087:80"
bash
mkdir -p /opt/docker/stacks/whoami
# Save the YAML above as /opt/docker/stacks/whoami/compose.yaml
docker compose -p whoami -f /opt/docker/stacks/whoami/compose.yaml config --quiet

5. Ejemplo 2: Nginx con archivo .env

Prepara un directorio de prueba con una página HTML y dos archivos. El .env permite que Compose sustituya el puerto y la ruta persistente. Para un nombre de archivo distinto, como stack.env, selecciónalo explícitamente en el campo Env file de Dockhand.

compose.yaml:

yaml
services:
  web:
    image: nginx:alpine
    restart: unless-stopped
    ports:
      - "${WEB_PORT}:80"
    volumes:
      - "${SITE_DIR}:/usr/share/nginx/html:ro"

.env:

dotenv
WEB_PORT=8088
SITE_DIR=/srv/demo-site/html
bash
mkdir -p /srv/demo-site/html /opt/docker/stacks/demo-nginx
printf '<h1>Dockhand migration test</h1>\n' > /srv/demo-site/html/index.html
# Save compose.yaml and .env in /opt/docker/stacks/demo-nginx/
docker compose --project-directory /opt/docker/stacks/demo-nginx \
  --env-file /opt/docker/stacks/demo-nginx/.env \
  -f /opt/docker/stacks/demo-nginx/compose.yaml config --quiet

The test site is available at http://HOST:8088 after deployment. The example .env contains no passwords. For real credentials, use Dockhand's secret management and do not commit secrets to Git.

Compose environment variable resolution

6. El error más peligroso: rutas relativas

Un volumen ./postgres:/var/lib/postgresql/data se resuelve respecto al directorio de trabajo del Compose. Si antes estaba en /data/compose/11 y ahora el archivo está en /opt/docker/stacks/11, la ruta cambia. El contenedor puede arrancar con un directorio vacío. Conserva la ubicación antigua usando una ruta absoluta o mueve los datos mediante un procedimiento de migración separado y probado.

bash
# Inspect the currently mounted host paths
docker inspect YOUR_CONTAINER \
  --format '{{range .Mounts}}{{println .Source " -> " .Destination}}{{end}}'

# Check the resolved configuration without deploying
docker compose -p YOUR_PROJECT \
  -f /opt/docker/stacks/YOUR_PROJECT/compose.yaml config --quiet

If a Compose file uses ./data, compare the resolved source path against the current container's mounts. Do not redeploy a database until they match.

7. Validar antes de hacer redeploy

Prueba primero con un servicio no crítico. Anota su ID, haz redeploy desde Dockhand y comprueba que el nuevo contenedor tiene el proyecto y la ruta Compose correctos. Una recreación puede causar una interrupción breve.

bash
# Before and after the test redeploy
docker inspect whoami --format 'ID: {{.Id}} | Created: {{.Created}}'
docker inspect whoami --format 'Project: {{index .Config.Labels "com.docker.compose.project"}} | Compose: {{index .Config.Labels "com.docker.compose.project.config_files"}}'

8. Retirar Portainer con seguridad

Solo cuando hayas adoptado los stacks y verificado sus rutas, detén y elimina el contenedor de Portainer. Conserva su volumen hasta completar las pruebas. No ejecutes docker compose down -v, docker system prune --volumes ni borres directorios de datos activos.

bash
docker stop portainer
docker rm portainer
# Only after independently confirming the old volume is no longer needed:
# docker volume rm portainer_data

Conclusión

La migración no consiste en copiar YAML y pulsar Deploy. Consiste en conservar los nombres de proyecto, las variables, los montajes y los datos. En mi prueba, Dockhand adoptó los stacks y un redeploy de un servicio sencillo confirmó que podía recrearlo desde la nueva ruta sin depender de Portainer.


References: Dockhand · Dockhand Manual — Adopting Untracked Stacks

EL

Edward Lopez

IT Consultant y entusiasta del self-hosting. Me gusta entender cómo funcionan las cosas y compartir lo aprendido.

SIGAMOS LA CONVERSACIÓN

Preguntas, ideas y hallazgos.

0

Tu experiencia también cuenta.

Inicia sesión para participar en esta conversación.

Unirme

La conversación empieza contigo.

Busca en títulos, resúmenes y contenido.