# 1. Hacer backup (recomendado)
docker run --rm \
  -v heimdall_config:/config \
  -v ~/backups/heimdall:/backup \
  alpine tar czf /backup/heimdall-pre-update-$(date +%Y%m%d).tar.gz -C /config .

# 2. Descargar nueva imagen
docker compose pull

# 3. Recrear contenedor
docker compose up -d

# 4. Verificar logs
docker logs -f heimdall

Desde Portainer

Stacks → heimdall → Pull and redeploy

✅ Pull latest image versions
✅ Re-deploy stack
Click en Update

Verificar:

Containers → heimdall → Logs

PowerShell (Windows)

# Backup
docker run --rm `
  -v heimdall_config:/config `
  -v ${HOME}\backups\heimdall:/backup `
  alpine tar czf /backup/heimdall-pre-update-$(Get-Date -Format "yyyyMMdd").tar.gz -C /config .

# Actualizar
docker compose pull
docker compose up -d

# Ver logs
docker logs -f heimdall

Método 2: Watchtower (Automático)

Usa Watchtower del repositorio groales/watchtower para auto-actualizar.

Configuración

Watchtower ya está configurado para monitorear todos los contenedores.

Etiquetar para actualización automática:

En docker-compose.yml o override:

services:
  heimdall:
    labels:
      - "com.centurylinklabs.watchtower.enable=true"

Excluir de auto-actualización:

services:
  heimdall:
    labels:
      - "com.centurylinklabs.watchtower.enable=false"

Verificar Watchtower

# Ver logs de Watchtower
docker logs watchtower

# Debe mostrar:
# Checking heimdall
# Found new lscr.io/linuxserver/heimdall:latest image
# Stopping heimdall
# Removing heimdall
# Creating heimdall

Método 3: Actualización Programada

Crear script de actualización automática.

Script Bash (Linux)

~/scripts/update-heimdall.sh:

#!/bin/bash

BACKUP_DIR=~/backups/heimdall
DATE=$(date +%Y%m%d-%H%M%S)

# Función de log
log() {
    echo "[$(date '+%Y-%m-%d %H:%M:%S')] $1"
}

log "Iniciando actualización de Heimdall"

# Backup
log "Creando backup..."
docker run --rm \
  -v heimdall_config:/config \
  -v $BACKUP_DIR:/backup \
  alpine tar czf /backup/heimdall-pre-update-$DATE.tar.gz -C /config . || {
    log "ERROR: Falló el backup. Abortando actualización."
    exit 1
}

log "Backup creado: heimdall-pre-update-$DATE.tar.gz"

# Actualizar
log "Descargando nueva imagen..."
cd ~/heimdall
docker compose pull || {
    log "ERROR: Falló la descarga de la imagen."
    exit 1
}

log "Recreando contenedor..."
docker compose up -d || {
    log "ERROR: Falló la recreación del contenedor."
    log "Restaurando desde backup..."
    docker run --rm \
      -v heimdall_config:/config \
      -v $BACKUP_DIR:/backup \
      alpine tar xzf /backup/heimdall-pre-update-$DATE.tar.gz -C /config
    docker compose up -d
    exit 1
}

# Verificar salud
log "Esperando 10 segundos para verificar salud..."
sleep 10

if docker ps | grep -q heimdall; then
    log "✓ Heimdall actualizado correctamente"
    
    # Limpiar backups antiguos (30 días)
    find $BACKUP_DIR -name "heimdall-pre-update-*.tar.gz" -mtime +30 -delete
    log "✓ Backups antiguos limpiados"
else
    log "ERROR: Heimdall no está corriendo. Revisa los logs:"
    docker logs heimdall
    exit 1
fi

Hacer ejecutable:

chmod +x ~/scripts/update-heimdall.sh

Automatizar con Cron

crontab -e

# Actualizar semanalmente (domingos a las 3 AM)
0 3 * * 0 ~/scripts/update-heimdall.sh >> ~/logs/heimdall-updates.log 2>&1

PowerShell Script (Windows)

C:\Scripts\Update-Heimdall.ps1:

$BackupPath = "$HOME\backups\heimdall"
$Date = Get-Date -Format "yyyyMMdd-HHmmss"
$LogFile = "$HOME\logs\heimdall-updates.log"

function Write-Log {
    param($Message)
    $Timestamp = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
    "$Timestamp - $Message" | Tee-Object -FilePath $LogFile -Append
}

Write-Log "Iniciando actualización de Heimdall"

# Backup
Write-Log "Creando backup..."
docker run --rm `
  -v heimdall_config:/config `
  -v ${BackupPath}:/backup `
  alpine tar czf /backup/heimdall-pre-update-$Date.tar.gz -C /config .

if ($LASTEXITCODE -ne 0) {
    Write-Log "ERROR: Falló el backup. Abortando."
    exit 1
}

Write-Log "Backup creado: heimdall-pre-update-$Date.tar.gz"

# Actualizar
Write-Log "Descargando nueva imagen..."
Set-Location "$HOME\repos\heimdall"
docker compose pull

if ($LASTEXITCODE -ne 0) {
    Write-Log "ERROR: Falló la descarga."
    exit 1
}

Write-Log "Recreando contenedor..."
docker compose up -d

if ($LASTEXITCODE -ne 0) {
    Write-Log "ERROR: Falló la recreación."
    Write-Log "Restaurando desde backup..."
    docker run --rm `
      -v heimdall_config:/config `
      -v ${BackupPath}:/backup `
      alpine tar xzf /backup/heimdall-pre-update-$Date.tar.gz -C /config
    docker compose up -d
    exit 1
}

# Verificar
Start-Sleep -Seconds 10

if (docker ps | Select-String "heimdall") {
    Write-Log "✓ Heimdall actualizado correctamente"
    
    # Limpiar backups antiguos (30 días)
    Get-ChildItem -Path $BackupPath -Filter "heimdall-pre-update-*.tar.gz" |
        Where-Object { $_.LastWriteTime -lt (Get-Date).AddDays(-30) } |
        Remove-Item
    Write-Log "✓ Backups antiguos limpiados"
} else {
    Write-Log "ERROR: Heimdall no está corriendo"
    docker logs heimdall | Out-File -Append $LogFile
    exit 1
}

Automatizar con Tarea Programada:

$Action = New-ScheduledTaskAction -Execute "PowerShell.exe" -Argument "-File C:\Scripts\Update-Heimdall.ps1"
$Trigger = New-ScheduledTaskTrigger -Weekly -DaysOfWeek Sunday -At 3am
Register-ScheduledTask -TaskName "Heimdall Update" -Action $Action -Trigger $Trigger

🔍 Verificar Versión

Ver versión actual

docker inspect heimdall | grep -A 5 Labels | grep build_version

# O ver logs al iniciar:
docker logs heimdall | grep "Version:"

Salida ejemplo:

Version: 2.5.8-ls234 Built: 2024-12-01

Ver versión disponible

# Comparar con registro remoto
docker pull lscr.io/linuxserver/heimdall:latest
docker inspect lscr.io/linuxserver/heimdall:latest | grep build_version

Desde Portainer

Containers → heimdall → Details → Labels

Buscar: org.opencontainers.image.version

📋 Changelog

Ver cambios en nuevas versiones:

GitHub: Heimdall Releases
LinuxServer.io: Blog
Docker Hub: Tags

🔔 Notificaciones de Actualizaciones

Con Diun

Usar Diun (Docker Image Update Notifier):

# docker-compose.yml de Diun
services:
  diun:
    image: crazymax/diun:latest
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - DIUN_WATCH_WORKERS=5
      - DIUN_NOTIF_MAIL_HOST=smtp.gmail.com
      - DIUN_NOTIF_MAIL_PORT=587
      - DIUN_NOTIF_MAIL_FROM=tu@gmail.com
      - DIUN_NOTIF_MAIL_TO=tu@gmail.com

Con Watchtower (solo notificaciones)

# Watchtower en modo notificación (no actualiza)
services:
  watchtower:
    command:
      - --monitor-only
      - --notifications
      - email
    environment:
      - WATCHTOWER_NOTIFICATION_EMAIL_TO=tu@email.com

🐛 Solución de Problemas

Actualización falla

# Ver logs detallados
docker logs heimdall

# Errores comunes:
# 1. Permisos: Verificar PUID/PGID
# 2. Volumen corrupto: Restaurar desde backup
# 3. Red: Verificar conectividad a Docker Hub

Contenedor no inicia tras actualización

# Revertir a versión anterior
docker compose down
docker pull lscr.io/linuxserver/heimdall:2.5.8  # Versión específica
# Editar docker-compose.yml: image: lscr.io/linuxserver/heimdall:2.5.8
docker compose up -d

# O restaurar desde backup
docker run --rm \
  -v heimdall_config:/config \
  -v ~/backups/heimdall:/backup \
  alpine tar xzf /backup/heimdall-pre-update-20251203.tar.gz -C /config
docker start heimdall

Configuración perdida tras actualización

Esto NO debería ocurrir (el volumen persiste). Si ocurre:

# Verificar volumen
docker volume inspect heimdall_config

# Verificar montaje
docker inspect heimdall | grep -A 10 Mounts

# Restaurar desde backup
# Ver guía: [[Backup y Restauración]]

Actualizaciones muy frecuentes

LinuxServer.io actualiza regularmente. Para estabilidad:

Usar tag específico:

services:
  heimdall:
    image: lscr.io/linuxserver/heimdall:2.5.8

Actualizar manualmente cada 1-2 meses en lugar de :latest.

📊 Mejores Prácticas

✅ Backup antes de actualizar (siempre)
✅ Actualizar en horario de bajo uso (madrugada)
✅ Verificar changelog antes de actualizar
✅ Probar en desarrollo si tienes entorno test
✅ Mantener 2-3 backups recientes
✅ Monitorear logs tras actualización
❌ NO actualizar en producción sin backup

🔄 Frecuencia Recomendada

Entorno	Frecuencia	Método
Producción	Mensual	Manual con backup
Personal	Semanal	Watchtower o manual
Testing	Diario	Watchtower

🚀 Actualización con Downtime Cero

Para entornos críticos:

Despliega segunda instancia con nueva versión
Configura balanceo en proxy (NPM/Traefik)
Cambia tráfico a nueva instancia
Verifica funcionamiento
Detiene instancia antigua

Con Traefik:

services:
  heimdall-blue:
    # Versión actual
    
  heimdall-green:
    # Nueva versión
    
# Traefik balancea entre ambas
# Cambiar peso gradualmente

📚 Siguiente Paso

Backup y Restauración - Protege tu configuración
Solución de Problemas - Resolver errores

Repositorio: groales/heimdall