homelab-optimized/docs/troubleshooting/RECOVERY_GUIDE.md

Recovery Guide

Quick reference for recovering homelab services when things go wrong.

Homarr Dashboard

Database Backups Location

/volume2/metadata/docker/homarr/appdata/db/

Available Backups

Backup	Description
db.sqlite.backup.working.20260201_023718	✅ Latest stable - 60 apps, 6 sections
db.sqlite.backup.20260201_022448	Pre-widgets attempt
db.sqlite.backup.pre_sections	Before machine-based sections
db.sqlite.backup.pre_dns_update	Before URL updates to local DNS

Restore Homarr Database

# SSH to Atlantis
ssh vish@atlantis.vish.local

# Stop Homarr
sudo docker stop homarr

# Restore from backup (pick the appropriate one)
sudo cp /volume2/metadata/docker/homarr/appdata/db/db.sqlite.backup.working.20260201_023718 \
       /volume2/metadata/docker/homarr/appdata/db/db.sqlite

# Start Homarr
sudo docker start homarr

Recreate Homarr from Scratch

# On Atlantis
cd /volume1/docker

# Pull latest image
sudo docker pull ghcr.io/homarr-labs/homarr:latest

# Run container
sudo docker run -d \
  --name homarr \
  --restart unless-stopped \
  -p 7575:7575 \
  -v /volume2/metadata/docker/homarr/appdata:/appdata \
  -e TZ=America/Los_Angeles \
  -e SECRET_ENCRYPTION_KEY=your-secret-key \
  ghcr.io/homarr-labs/homarr:latest

Authentik SSO

Access

• URL: https://sso.vish.gg or http://192.168.0.250:9000
• Admin: akadmin

Key Configuration

Item	Value
Forward Auth Provider ID	5
Cookie Domain	vish.gg
Application	"vish.gg Domain Auth"

Users & Groups

User	ID	Groups
akadmin	6	authentik Admins
aquabroom (Crista)	8	Viewers
openhands	7	-

Group	ID
Viewers	c267106d-d196-41ec-aebe-35da7534c555

Recreate Viewers Group (if needed)

# Get API token from Authentik admin → Directory → Tokens
AK_TOKEN="your-token-here"

# Create group
curl -X POST "http://192.168.0.250:9000/api/v3/core/groups/" \
  -H "Authorization: Bearer $AK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Viewers", "is_superuser": false}'

# Add user to group (replace GROUP_ID and USER_ID)
curl -X POST "http://192.168.0.250:9000/api/v3/core/groups/GROUP_ID/add_user/" \
  -H "Authorization: Bearer $AK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"pk": USER_ID}'

Nginx Proxy Manager

Access

• URL: http://192.168.0.250:81 or https://npm.vish.gg
• Login: your-email@example.com

Key Proxy Hosts

ID	Domain	Target
40	dash.vish.gg	atlantis.vish.local:7575

Forward Auth Config (for Authentik)

Add this to Advanced tab of proxy hosts:

location /outpost.goauthentik.io {
    proxy_pass http://192.168.0.250:9000/outpost.goauthentik.io;
    proxy_set_header Host $host;
    proxy_set_header X-Original-URL $scheme://$http_host$request_uri;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

auth_request /outpost.goauthentik.io/auth/nginx;
error_page 401 = @goauthentik_proxy_signin;

auth_request_set $auth_cookie $upstream_http_set_cookie;
add_header Set-Cookie $auth_cookie;

auth_request_set $authentik_username $upstream_http_x_authentik_username;
auth_request_set $authentik_groups $upstream_http_x_authentik_groups;
auth_request_set $authentik_email $upstream_http_x_authentik_email;
auth_request_set $authentik_name $upstream_http_x_authentik_name;
auth_request_set $authentik_uid $upstream_http_x_authentik_uid;

proxy_set_header X-authentik-username $authentik_username;
proxy_set_header X-authentik-groups $authentik_groups;
proxy_set_header X-authentik-email $authentik_email;
proxy_set_header X-authentik-name $authentik_name;
proxy_set_header X-authentik-uid $authentik_uid;

location @goauthentik_proxy_signin {
    internal;
    add_header Set-Cookie $auth_cookie;
    return 302 /outpost.goauthentik.io/start?rd=$scheme://$http_host$request_uri;
}

Network Reference

Split Horizon DNS (via Tailscale)

Hostname	IP
atlantis.vish.local	192.168.0.200
calypso.vish.local	192.168.0.250
homelab.vish.local	192.168.0.210
concordnuc.vish.local	(check Tailscale)

Key Ports on Atlantis

Port	Service
7575	Homarr
8989	Sonarr
7878	Radarr
8686	Lidarr
9696	Prowlarr
8080	SABnzbd
32400	Plex
9080	Authentik (local)

Key Ports on Calypso

Port	Service
81	NPM Admin
9000	Authentik
3000	Gitea

Quick Health Checks

# Check if Homarr is running
curl -s -o /dev/null -w "%{http_code}" http://atlantis.vish.local:7575

# Check Authentik
curl -s -o /dev/null -w "%{http_code}" http://192.168.0.250:9000

# Check NPM
curl -s -o /dev/null -w "%{http_code}" http://192.168.0.250:81

# Check all key services
for svc in "atlantis.vish.local:7575" "atlantis.vish.local:8989" "atlantis.vish.local:32400"; do
  echo -n "$svc: "
  curl -s -o /dev/null -w "%{http_code}\n" "http://$svc" --connect-timeout 3
done

Docker Commands (Synology)

# Docker binary location on Synology
DOCKER="sudo /var/packages/REDACTED_APP_PASSWORD/target/usr/bin/docker"

# Or just use sudo docker if alias is set
sudo docker ps
sudo docker logs homarr --tail 50
sudo docker restart homarr

Fenrus (Old Dashboard - Archived)

Backup location: /volume1/docker/fenrus-backup-20260201/

To restore if needed:

# On Atlantis
cd /volume1/docker
sudo docker run -d \
  --name fenrus \
  -p 5000:5000 \
  -v /volume1/docker/fenrus-backup-20260201:/app/data \
  revenz/fenrus:latest

Repository

All documentation and scripts are in Gitea:

• URL: https://git.vish.gg/Vish/homelab
• Clone: git clone https://git.vish.gg/Vish/homelab.git

Key Files

File	Purpose
docs/services/HOMARR_SETUP.md	Complete Homarr setup guide
docs/infrastructure/USER_ACCESS_GUIDE.md	User management & SSO
docs/troubleshooting/RECOVERY_GUIDE.md	This file
scripts/add_apps_to_sections.sh	Organize apps by machine