Sanitized mirror from private repository - 2026-04-20 01:32:01 UTC
This commit is contained in:
Gitea Mirror Bot
232
docs/troubleshooting/RECOVERY_GUIDE.md
Normal file
232
docs/troubleshooting/RECOVERY_GUIDE.md
Normal file
@@ -0,0 +1,232 @@
|
||||
# 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 |
|
||||
Reference in New Issue
Block a user