# Estado del contenedor
docker ps -a | grep heimdall

# Logs recientes
docker logs --tail 50 heimdall

# Logs en vivo
docker logs -f heimdall

# Inspeccionar contenedor
docker inspect heimdall

# Verificar volumen
docker volume inspect heimdall_config

# Verificar red (si usas proxy)
docker network inspect proxy

🚫 Problemas de Acceso

No puedo acceder a Heimdall

Síntoma: Timeout o "No se puede acceder al sitio"

1. Verificar que el contenedor está corriendo:

docker ps | grep heimdall

Si NO aparece:

# Ver por qué se detuvo
docker ps -a | grep heimdall
docker logs heimdall

2. Verificar modo de despliegue:

Standalone - Debe tener puertos publicados:

docker ps | grep heimdall
# Debe mostrar: 0.0.0.0:8080->80/tcp

Si no hay puertos:

# Verifica que usaste override standalone
docker compose config | grep -A 5 ports

Con proxy (NPM/Traefik) - Debe estar en red proxy:

docker network inspect proxy | grep heimdall

Si no aparece:

# Verifica override
docker compose config | grep -A 5 networks

3. Verificar conectividad:

Desde el host:

curl http://localhost:8080  # Si standalone
curl http://heimdall  # Si proxy (desde otro contenedor en red proxy)

Desde otro dispositivo:

curl http://IP-DEL-SERVIDOR:8080
telnet IP-DEL-SERVIDOR 8080

4. Verificar firewall:

Linux (UFW):

sudo ufw status
sudo ufw allow 8080/tcp  # Si standalone

Linux (iptables):

sudo iptables -L -n | grep 8080

Windows:

Get-NetFirewallRule | Where-Object DisplayName -like "*8080*"

# Crear regla si no existe
New-NetFirewallRule -DisplayName "Heimdall" -Direction Inbound -LocalPort 8080 -Protocol TCP -Action Allow

Error 502 Bad Gateway (con proxy)

Causa: NPM/Traefik no puede conectar con Heimdall.

Solución:

Verificar que están en la misma red:

docker network inspect proxy
# Deben aparecer tanto npm/traefik como heimdall

Verificar nombre del contenedor:

En NPM: Forward Hostname debe ser heimdall En Traefik: Labels deben usar el nombre correcto

# Verificar nombre real
docker ps | grep heimdall
# Usar el nombre exacto en NAMES

Verificar puerto interno:

En NPM: Forward Port debe ser 80 (no 8080) En Traefik: loadbalancer.server.port=80

Recrear stack:

docker compose down
docker compose up -d

Error 404 Not Found (con Traefik)

Causa: Traefik no encuentra el router.

Solución:

Verificar labels:

docker inspect heimdall | grep -A 20 Labels

Debe incluir:

traefik.enable=true
traefik.http.routers.heimdall.rule=Host(...)

Verificar en Traefik Dashboard:

Accede al dashboard de Traefik y busca:

HTTP Routers → heimdall (debe aparecer)
Services → heimdall@docker

Si no aparece: Revisar override y labels.

Verificar dominio:

nslookup heimdall.tudominio.com
# Debe resolver a IP del servidor

Advertencia de certificado SSL

Modo Standalone (puerto 8443):

Causa: Heimdall usa certificado autofirmado.

Soluciones:

Acepta la advertencia (OK para red local)
Usa HTTP puerto 8080 en su lugar
Migra a NPM o Traefik para SSL real

Con proxy:

Causa: SSL no configurado correctamente.

NPM: Verifica que marcaste "Request a new SSL Certificate" Traefik: Verifica que tls.certresolver=letsencrypt

# Ver logs de generación de certificado
docker logs npm | grep -i ssl
docker logs traefik | grep -i certificate

🗄️ Problemas de Base de Datos

"Database is locked"

Síntoma: Error al guardar aplicaciones o configuración.

Causa: Múltiples procesos accediendo a SQLite simultáneamente.

Solución:

Reiniciar contenedor:

docker restart heimdall

Si persiste, verificar procesos:

docker exec heimdall fuser /config/www/app.sqlite

Reparar base de datos:

# Backup primero
docker exec heimdall cp /config/www/app.sqlite /config/www/app.sqlite.bak

# Reparar
docker exec heimdall sqlite3 /config/www/app.sqlite "PRAGMA integrity_check;"

# Si falla, restaurar desde backup
# Ver [[Backup y Restauración]]

Aplicaciones desaparecen tras reiniciar

Causa: Base de datos no persiste.

Solución:

Verificar volumen:

docker volume inspect heimdall_config
# Debe existir y tener Mountpoint

Verificar montaje en contenedor:

docker inspect heimdall | grep -A 10 Mounts
# Debe mostrar heimdall_config montado en /config

Si el volumen no existe, recrearlo:

docker compose down
docker volume create heimdall_config
docker compose up -d

Nota: Si recreas el volumen, perderás la configuración. Restaura desde backup.

🔐 Problemas de Permisos

"Permission denied" en logs

Síntoma:

s6-supervise nginx: warning: unable to spawn ./run - disabling service
Permission denied

Causa: PUID/PGID incorrectos.

Solución:

Verificar tu UID/GID:

id
# uid=1000(user) gid=1000(user)

Actualizar docker-compose.yml:

environment:
  PUID: 1000  # Tu UID
  PGID: 1000  # Tu GID

Recrear contenedor:

docker compose down
docker compose up -d

Si persiste, forzar permisos:

docker exec heimdall chown -R 1000:1000 /config
docker restart heimdall

No puedo subir iconos o fondos

Síntoma: Error al subir archivos en Settings.

Solución:

Verificar permisos de escritura:

docker exec heimdall ls -la /config/www/
# Debe ser owned por PUID:PGID

Verificar espacio en disco:

df -h

Ajustar permisos:

docker exec heimdall chown -R 1000:1000 /config/www
docker exec heimdall chmod -R 755 /config/www

🎨 Problemas de Interfaz

Interfaz se ve rota (sin estilos)

Síntoma: Solo texto plano, sin colores ni diseño.

Causa: Archivos estáticos no cargan.

Solución:

Limpiar caché del navegador:

Chrome: Ctrl+Shift+Delete
Firefox: Ctrl+Shift+Delete
Safari: Cmd+Opt+E

Forzar recarga sin caché:

Ctrl+F5 (Windows/Linux)
Cmd+Shift+R (Mac)

Verificar logs de NGINX:

docker logs heimdall | grep -i error

Recrear contenedor:

docker compose down
docker compose up -d --force-recreate

Cambios no se guardan

Síntoma: Edito aplicaciones pero desaparecen al recargar.

Causa: Sesión o base de datos.

Solución:

Verificar que sales del modo edición (click en llave de nuevo)
Limpiar cookies:

Navegador → Configuración → Cookies
Eliminar cookies de heimdall.tudominio.com

Verificar base de datos:

docker exec heimdall ls -la /config/www/app.sqlite
# Debe tener tamaño > 0

Verificar permisos de escritura (ver sección anterior)

Enhanced apps no funcionan

Síntoma: No muestra información de Sonarr/Radarr/etc.

Solución:

Verificar API Key:

Copia de nuevo el API Key desde la app
Pega en Heimdall sin espacios extra

Verificar URL:

Debe ser accesible desde Heimdall
Si está en la misma red proxy: http://sonarr:8989
Si es externo: https://sonarr.tudominio.com

Probar conectividad:

docker exec heimdall curl http://sonarr:8989/api/system/status -H "X-Api-Key: TU_API_KEY"

Verificar CORS:

Algunas apps bloquean peticiones desde Heimdall. Verifica logs de la app (Sonarr/Radarr).

🌐 Problemas de Red

Contenedor no puede conectar a Internet

Síntoma: Enhanced apps no funcionan, no descarga iconos.

Solución:

Verificar DNS:

docker exec heimdall cat /etc/resolv.conf
docker exec heimdall ping -c 3 google.com

Configurar DNS custom en docker-compose.yml:

services:
  heimdall:
    dns:
      - 8.8.8.8
      - 1.1.1.1

Recrear contenedor:

docker compose down
docker compose up -d

No puedo conectar con otros contenedores

Síntoma: Enhanced apps no funcionan con apps locales.

Causa: No están en la misma red Docker.

Solución:

Verificar redes:

# Red de Heimdall
docker inspect heimdall | grep -A 10 Networks

# Red de Sonarr (ejemplo)
docker inspect sonarr | grep -A 10 Networks

Conectar a red compartida:

Si ambos deben comunicarse, usa red proxy:

docker network connect proxy sonarr
docker network connect proxy heimdall

O configura en docker-compose.yml:

networks:
  - proxy

🔄 Problemas de Actualización

Ver guía completa: Actualización

Actualización falla

# 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

Nuevo contenedor no inicia

# Ver logs de inicio
docker logs heimdall

# Volver a versión anterior
docker compose down
# Editar docker-compose.yml: cambiar :latest por :2.5.7
docker compose up -d

🐛 Problemas Específicos

Puerto 8080 ya en uso

Síntoma:

Error starting userland proxy: listen tcp 0.0.0.0:8080: bind: address already in use

Solución:

Ver qué proceso usa el puerto:

# Linux
sudo netstat -tulpn | grep :8080
sudo lsof -i :8080

# Windows
Get-NetTCPConnection -LocalPort 8080

Cambiar puerto en override standalone:

ports:
  - "9080:80"  # Usar puerto 9080 en lugar de 8080

Recrear:

docker compose up -d

Contenedor se reinicia constantemente

Síntoma: docker ps muestra Restarting (1) 5 seconds ago

Solución:

Ver logs de error:

docker logs heimdall

Errores comunes:

Permisos: Ajustar PUID/PGID
Volumen corrupto: Restaurar desde backup
Puerto en uso: Cambiar puerto

Detener auto-restart para debug:

docker update --restart=no heimdall
docker stop heimdall
# Investigar problema
# Arreglar
docker start heimdall
docker update --restart=unless-stopped heimdall

Certificado SSL no se renueva (con proxy)

Con NPM:

Verificar que puerto 80 es accesible desde Internet
Proxy Hosts → Editar → SSL → Force Renew

Con Traefik:

Verificar logs:

docker logs traefik | grep -i certificate
docker logs traefik | grep -i acme

Verificar archivo acme.json:

docker exec traefik ls -la /letsencrypt/acme.json
# Debe tener permisos 600

Forzar renovación:

docker exec traefik rm /letsencrypt/acme.json
docker restart traefik

🔧 Modo de Recuperación

Si nada funciona:

Reset Completo

# 1. Backup actual (por si acaso)
docker run --rm \
  -v heimdall_config:/config \
  -v /tmp:/backup \
  alpine tar czf /backup/heimdall-emergency.tar.gz -C /config .

# 2. Detener y eliminar todo
docker compose down
docker volume rm heimdall_config

# 3. Redesplegar limpio
docker compose up -d

# 4. Si necesitas recuperar datos, restaura backup
docker stop heimdall
docker run --rm \
  -v heimdall_config:/config \
  -v /tmp:/backup \
  alpine tar xzf /backup/heimdall-emergency.tar.gz -C /config
docker start heimdall

📊 Herramientas de Diagnóstico

Verificación Completa

Script para recopilar toda la info:

#!/bin/bash
echo "=== HEIMDALL DIAGNOSTICS ==="
echo ""
echo "--- Container Status ---"
docker ps -a | grep heimdall
echo ""
echo "--- Recent Logs ---"
docker logs --tail 20 heimdall
echo ""
echo "--- Volume Info ---"
docker volume inspect heimdall_config
echo ""
echo "--- Network Info ---"
docker network inspect proxy 2>/dev/null | grep -A 5 heimdall || echo "Not in proxy network"
echo ""
echo "--- Config Files ---"
docker exec heimdall ls -la /config/www/
echo ""
echo "--- Disk Space ---"
df -h | grep docker

📚 Recursos Adicionales

Configuración Inicial - Configurar desde cero
Backup y Restauración - Recuperación de datos
Actualización - Problemas de actualización

Soporte oficial:

Repositorio: groales/heimdall