/config/
├── www/
│   ├── app.sqlite        ← Base de datos (apps, settings)
│   ├── icons/            ← Iconos subidos
│   └── backgrounds/      ← Imágenes de fondo subidas
├── log/                  ← Logs de la aplicación
└── nginx/                ← Configuración NGINX

Importante: Solo necesitas backup de /config/www/ para recuperar tus aplicaciones y personalización.

💾 Métodos de Backup

Método 1: Backup Completo del Volumen (Recomendado)

Este método guarda TODO el volumen.

Desde CLI

# Crear directorio de backups
mkdir -p ~/backups/heimdall

# Backup completo
docker run --rm \
  -v heimdall_config:/config \
  -v ~/backups/heimdall:/backup \
  alpine tar czf /backup/heimdall-config-$(date +%Y%m%d-%H%M%S).tar.gz -C /config .

# Ejemplo de resultado:
# heimdall-config-20251203-143022.tar.gz

Desde PowerShell (Windows)

# Crear directorio de backups
New-Item -ItemType Directory -Force -Path "$HOME\backups\heimdall"

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

Automatizar con Cron (Linux)

# Editar crontab
crontab -e

# Añadir backup diario a las 3 AM
0 3 * * * docker run --rm -v heimdall_config:/config -v ~/backups/heimdall:/backup alpine tar czf /backup/heimdall-config-$(date +\%Y\%m\%d).tar.gz -C /config .

# Limpiar backups antiguos (mantener 30 días)
0 4 * * * find ~/backups/heimdall -name "heimdall-config-*.tar.gz" -mtime +30 -delete

Automatizar con Tarea Programada (Windows)

PowerShell script (heimdall-backup.ps1):

$BackupPath = "$HOME\backups\heimdall"
$Date = Get-Date -Format "yyyyMMdd-HHmmss"
$BackupFile = "heimdall-config-$Date.tar.gz"

docker run --rm `
  -v heimdall_config:/config `
  -v ${BackupPath}:/backup `
  alpine tar czf /backup/$BackupFile -C /config .

# Limpiar backups antiguos (30 días)
Get-ChildItem -Path $BackupPath -Filter "heimdall-config-*.tar.gz" | 
  Where-Object { $_.LastWriteTime -lt (Get-Date).AddDays(-30) } | 
  Remove-Item

Crear tarea:

$Action = New-ScheduledTaskAction -Execute "PowerShell.exe" -Argument "-File C:\Scripts\heimdall-backup.ps1"
$Trigger = New-ScheduledTaskTrigger -Daily -At 3am
Register-ScheduledTask -TaskName "Heimdall Backup" -Action $Action -Trigger $Trigger

Método 2: Backup Solo de Base de Datos

Más rápido, solo guarda configuración (no iconos/fondos subidos).

# Backup de SQLite
docker exec heimdall cat /config/www/app.sqlite > ~/backups/heimdall-$(date +%Y%m%d).sqlite

# Verificar
file ~/backups/heimdall-$(date +%Y%m%d).sqlite
# Debe decir: SQLite 3.x database

Método 3: Backup con docker-compose

Si usas docker-compose:

# Añadir servicio de backup en docker-compose.override.yml
services:
  heimdall-backup:
    image: alpine:latest
    volumes:
      - heimdall_config:/config:ro
      - ./backups:/backup
    command: >
      sh -c "tar czf /backup/heimdall-config-$$(date +%Y%m%d-%H%M%S).tar.gz -C /config . &&
             find /backup -name 'heimdall-config-*.tar.gz' -mtime +30 -delete"
    profiles:
      - backup

Ejecutar manualmente:

docker compose --profile backup run --rm heimdall-backup

Método 4: Backup Remoto (Nextcloud/NAS)

A Nextcloud

# Backup + subida a Nextcloud
BACKUP_FILE="heimdall-config-$(date +%Y%m%d).tar.gz"

docker run --rm \
  -v heimdall_config:/config \
  -v /tmp:/backup \
  alpine tar czf /backup/$BACKUP_FILE -C /config .

# Subir a Nextcloud con curl
curl -u "usuario:password" \
  -T /tmp/$BACKUP_FILE \
  "https://nextcloud.tudominio.com/remote.php/dav/files/usuario/Backups/$BACKUP_FILE"

rm /tmp/$BACKUP_FILE

A NAS (SMB/CIFS)

# Montar carpeta NAS
sudo mount -t cifs //nas.local/backups /mnt/nas -o username=user,password=pass

# Backup directo a NAS
docker run --rm \
  -v heimdall_config:/config \
  -v /mnt/nas/heimdall:/backup \
  alpine tar czf /backup/heimdall-config-$(date +%Y%m%d).tar.gz -C /config .

🔄 Restauración

Restaurar Backup Completo

# Detener Heimdall
docker stop heimdall

# Restaurar
docker run --rm \
  -v heimdall_config:/config \
  -v ~/backups/heimdall:/backup \
  alpine tar xzf /backup/heimdall-config-20251203-143022.tar.gz -C /config

# Iniciar Heimdall
docker start heimdall

PowerShell (Windows)

# Detener Heimdall
docker stop heimdall

# Restaurar (ajustar nombre de archivo)
docker run --rm `
  -v heimdall_config:/config `
  -v ${HOME}\backups\heimdall:/backup `
  alpine tar xzf /backup/heimdall-config-20251203-143022.tar.gz -C /config

# Iniciar Heimdall
docker start heimdall

Restaurar Solo Base de Datos

# Detener Heimdall
docker stop heimdall

# Restaurar SQLite
cat ~/backups/heimdall-20251203.sqlite | docker exec -i heimdall tee /config/www/app.sqlite > /dev/null

# Iniciar Heimdall
docker start heimdall

Restaurar en Nuevo Servidor

# 1. Clonar repositorio
git clone https://git.ictiberia.com/groales/heimdall
cd heimdall

# 2. Desplegar Heimdall (sin configuración)
docker compose up -d

# 3. Detener para restaurar
docker stop heimdall

# 4. Copiar backup al servidor
scp ~/backups/heimdall-config-20251203.tar.gz user@nuevo-servidor:/tmp/

# 5. Restaurar (en nuevo servidor)
docker run --rm \
  -v heimdall_config:/config \
  -v /tmp:/backup \
  alpine tar xzf /backup/heimdall-config-20251203.tar.gz -C /config

# 6. Iniciar
docker start heimdall

🔁 Migración entre Modos

De Standalone a NPM/Traefik

La configuración de Heimdall es independiente del proxy. Solo necesitas:

Hacer backup del volumen
Cambiar override file
Restaurar backup

# Backup actual
docker run --rm -v heimdall_config:/config -v /tmp:/backup \
  alpine tar czf /backup/heimdall-migrate.tar.gz -C /config .

# Detener stack actual
docker compose down

# Cambiar override
cp docker-compose.override.npm.yml.example docker-compose.override.yml

# Desplegar con nuevo override
docker compose up -d

# Restaurar configuración (si es nueva instalación)
docker stop heimdall
docker run --rm -v heimdall_config:/config -v /tmp:/backup \
  alpine tar xzf /backup/heimdall-migrate.tar.gz -C /config
docker start heimdall

🗄️ Backup con Watchtower

Si usas Watchtower para auto-actualizar, configura backup previo:

# docker-compose.yml de Heimdall
services:
  heimdall:
    labels:
      - "com.centurylinklabs.watchtower.lifecycle.pre-update=/backup.sh"

Crear script /backup.sh en contenedor:

#!/bin/sh
tar czf /backup/heimdall-pre-update-$(date +%Y%m%d-%H%M%S).tar.gz -C /config .

📊 Verificar Backup

# Listar contenido sin extraer
tar tzf ~/backups/heimdall-config-20251203.tar.gz

# Debe mostrar:
# www/app.sqlite
# www/icons/
# www/backgrounds/
# log/
# nginx/

🐛 Solución de Problemas

Backup corrupto

# Verificar integridad
tar tzf ~/backups/heimdall-config-20251203.tar.gz > /dev/null

# Si falla:
# tar: Error is not recoverable: exiting now
# → Backup corrupto, usar backup anterior

Permisos incorrectos tras restaurar

# Ajustar permisos (PUID/PGID del docker-compose.yml)
docker exec heimdall chown -R 1000:1000 /config

Base de datos bloqueada

# Detener Heimdall antes de backup/restauración
docker stop heimdall

# Si persiste:
docker exec heimdall fuser /config/www/app.sqlite
# Matar proceso si es necesario

☁️ Backup en la Nube

Rclone (recomendado)

Soporta Google Drive, Dropbox, OneDrive, S3, etc.

# Instalar rclone
curl https://rclone.org/install.sh | sudo bash

# Configurar (seguir wizard)
rclone config

# Backup a Google Drive
BACKUP_FILE="heimdall-config-$(date +%Y%m%d).tar.gz"

docker run --rm \
  -v heimdall_config:/config \
  -v /tmp:/backup \
  alpine tar czf /backup/$BACKUP_FILE -C /config .

rclone copy /tmp/$BACKUP_FILE gdrive:Backups/Heimdall/
rm /tmp/$BACKUP_FILE

Restic (con encriptación)

# Instalar restic
sudo apt install restic

# Inicializar repositorio
restic -r /mnt/backups/heimdall init

# Backup encriptado
docker run --rm \
  -v heimdall_config:/config \
  -v /tmp:/backup \
  alpine tar czf /backup/heimdall-latest.tar.gz -C /config .

restic -r /mnt/backups/heimdall backup /tmp/heimdall-latest.tar.gz

# Restaurar
restic -r /mnt/backups/heimdall restore latest --target /tmp/restore

📅 Estrategia de Backup Recomendada

Diario:   Backup completo (retener 7 días)
Semanal:  Backup completo (retener 4 semanas)
Mensual:  Backup completo (retener 12 meses)

Script completo:

#!/bin/bash
BACKUP_DIR=~/backups/heimdall
DATE=$(date +%Y%m%d)
BACKUP_FILE="heimdall-config-$DATE.tar.gz"

# Crear backup
docker run --rm \
  -v heimdall_config:/config \
  -v $BACKUP_DIR:/backup \
  alpine tar czf /backup/$BACKUP_FILE -C /config .

# Copiar a semanales (si es domingo)
if [ $(date +%u) -eq 7 ]; then
    cp $BACKUP_DIR/$BACKUP_FILE $BACKUP_DIR/weekly/
fi

# Copiar a mensuales (si es día 1)
if [ $(date +%d) -eq 01 ]; then
    cp $BACKUP_DIR/$BACKUP_FILE $BACKUP_DIR/monthly/
fi

# Limpiar antiguos
find $BACKUP_DIR -maxdepth 1 -name "heimdall-config-*.tar.gz" -mtime +7 -delete
find $BACKUP_DIR/weekly -name "heimdall-config-*.tar.gz" -mtime +28 -delete
find $BACKUP_DIR/monthly -name "heimdall-config-*.tar.gz" -mtime +365 -delete

🚀 Siguiente Paso

Actualización - Mantén Heimdall al día
Solución de Problemas - Resolver errores comunes

Repositorio: groales/heimdall