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
```bash
# 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
```bash
# 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)
```bash
# 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:
```nginx
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

```bash
# 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)

```bash
# 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:
```bash
# 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 |