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

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.
sudo mkdir -p /opt/docker/stacks /opt/docker/dockhandservices:
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:cd /opt/docker/dockhand
docker compose up -d
docker ps --filter name=dockhandOpen 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.
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):
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/
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.
services:
whoami:
image: traefik/whoami:latest
restart: unless-stopped
ports:
- "8087:80"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 --quiet5. 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:
services:
web:
image: nginx:alpine
restart: unless-stopped
ports:
- "${WEB_PORT}:80"
volumes:
- "${SITE_DIR}:/usr/share/nginx/html:ro".env:
WEB_PORT=8088
SITE_DIR=/srv/demo-site/htmlmkdir -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 --quietThe 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.

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.
# 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 --quietIf 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.
# 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.
docker stop portainer
docker rm portainer
# Only after independently confirming the old volume is no longer needed:
# docker volume rm portainer_dataConclusió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

Preguntas, ideas y hallazgos.
Tu experiencia también cuenta.
Inicia sesión para participar en esta conversación.
La conversación empieza contigo.