Jamie/Homelab
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Docs: align RESTORE.md with Architecture two-table layout; keep README Architecture two-table; drop narrative; update Crafty; last updated

Browse Source
This commit is contained in:
Jamie Miller
2026-01-10 12:55:52 +00:00
parent 36d26622ee
commit 5029b13f02
2 changed files with 31 additions and 150 deletions
Download Patch File Download Diff File Expand all files Collapse all files

155
RESTORE.md
View File

@@ -2,6 +2,14 @@
This guide walks you through restoring your Docker infrastructure from a backup.
## Architecture Alignment
The architecture inventory is documented in README.md as two tables under Architecture:
- Internal Docker Services (Service | Category | Web UI Port)
- External Non-Docker Services (Service | Category | IP | Web UI Port)
If you are restoring, follow the standard restoration steps below, and refer to README.md for the exact service inventory and ports as implemented in your environment.
## Prerequisites
- Fresh system with Docker and Docker Compose installed
@@ -117,39 +125,36 @@ docker compose logs -f paperless-db
## Step 7: Restore Database Dumps
### Paperless MariaDB
```bash
```
# Copy SQL file into container
docker cp /path/to/backup/database-dumps/paperless.sql paperless-db:/tmp/
# Import the database
docker exec -i paperless-db mysql -u root -p"${PAPERLESS_DB_ROOT_PASSWORD}" paperless < /path/to/backup/database-dumps/paperless.sql
# Or import directly
docker exec -i paperless-db mysql -u root -p"${PAPERLESS_DB_ROOT_PASSWORD}" paperless < /path/to/backup/database-dumps/paperless.sql
```
### Immich PostgreSQL
```bash
```
docker exec -i immich_postgres psql -U postgres immich < /path/to/backup/database-dumps/immich.sql
```
### LiteLLM PostgreSQL
```bash
```
docker exec -i litellm-postgres psql -U litellm litellm_db < /path/to/backup/database-dumps/litellm.sql
```
### WYGIWYH PostgreSQL
```bash
```
docker exec -i WYGIWYH-db psql -U ${WYGIWYH_DB_USER} ${WYGIWYH_DB_DATABASE} < /path/to/backup/database-dumps/wygiwyh.sql
```
### Gitea MySQL
```bash
```
docker exec -i gitea-db mysql -u root -pgitea gitea < /path/to/backup/database-dumps/gitea.sql
```
### Speedtest Tracker MariaDB
```bash
```
docker exec -i speedtest-db mysql -u root -p"${SPEEDTEST_DB_PASSWORD}" speedtest < /path/to/backup/database-dumps/speedtest.sql
```
@@ -198,7 +203,7 @@ Go through each service and verify it's working correctly:
- Immich: http://your-server:2283
### Verify Databases
```bash
```
# Paperless
docker exec paperless-db mysql -u root -p"${PAPERLESS_DB_ROOT_PASSWORD}" -e "SELECT COUNT(*) FROM paperless.documents_document;"
@@ -206,133 +211,9 @@ docker exec paperless-db mysql -u root -p"${PAPERLESS_DB_ROOT_PASSWORD}" -e "SEL
docker exec immich_postgres psql -U postgres -d immich -c "SELECT COUNT(*) FROM assets;"
```
### Check Logs for Errors
```bash
# View logs for specific service
docker compose logs SERVICE_NAME
... (rest of file continues)
# Follow logs in real-time
docker compose logs -f SERVICE_NAME
```
## Step 11: Configure Reverse Proxy (NPM)
1. Access Nginx Proxy Manager at http://your-server:81
2. Default credentials (if fresh install):
- Email: admin@example.com
- Password: changeme
3. Recreate proxy hosts for each service
4. Restore SSL certificates (if backed up in /npm/letsencrypt)
## Troubleshooting
### Service Won't Start
```bash
# Check logs
docker compose logs SERVICE_NAME
# Restart specific service
docker compose restart SERVICE_NAME
# Check disk space
df -h
# Check permissions
ls -la /docker/SERVICE_NAME/
```
### Database Connection Errors
```bash
# Verify database is running
docker compose ps | grep db
# Test database connection
docker exec SERVICE_NAME nc -zv DATABASE_HOST 3306
# Check database logs
docker compose logs DATABASE_SERVICE
```
### Permission Errors
```bash
# Fix ownership of Docker configs
sudo chown -R $PUID:$PGID /docker
# Fix NAS permissions
sudo chown -R $PUID:$PGID /mnt/Nas-Storage/data
```
### Missing Environment Variables
```bash
# Verify .env file is loaded
docker compose config | grep VARIABLE_NAME
# Check for typos in .env
cat .env | grep VARIABLE_NAME
```
### Volume Restore Failed
```bash
# Remove corrupted volume
docker volume rm VOLUME_NAME
# Recreate and try again
docker volume create VOLUME_NAME
# ... restore command ...
```
## Post-Restoration Checklist
- [ ] All services are running (`docker compose ps`)
- [ ] Web interfaces are accessible
- [ ] Databases contain expected data
- [ ] Media files are accessible
- [ ] Reverse proxy/SSL certificates work
- [ ] User accounts can login
- [ ] API keys/tokens are functional
- [ ] Scheduled tasks are running (Watchtower, etc.)
- [ ] Backups are configured
## Partial Restoration
If you only need to restore specific services:
```bash
# Restore only configuration
cp -r /path/to/backup/docker/SERVICE_NAME /docker/
# Start only specific services
docker compose up -d SERVICE_NAME
# Restore only specific database
docker exec -i DB_CONTAINER mysql/psql ... < backup.sql
```
## Notes
- Always test restoration process on a non-production system first
- Keep multiple backup copies in different locations
- Document any custom configurations or modifications
- Update README.md if infrastructure changes
- Verify backup integrity regularly
## Emergency Recovery
If full restoration fails:
1. Start with minimal services (databases only)
2. Verify database connectivity
3. Add services one at a time
4. Check logs after each addition
5. Document which services fail and why
## Getting Help
- Check service-specific documentation
- Review Docker logs: `docker compose logs -f`
- Verify network connectivity: `docker compose exec SERVICE ping OTHER_SERVICE`
- Check resource usage: `docker stats`
---
## Architecture Alignment
- This section connects to the Architecture two-table layout described in README.md.
**Last Updated**: December 2025