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

26
README.md
View File

@@ -21,13 +21,13 @@ This infrastructure manages a comprehensive self-hosted environment including me
| Data Management | Paperless | Document management interface | 8100 |
| Data Management | Stirling-PDF | PDF manipulation tools | 8090 |
| Data Management | OnlyOffice | Document collaboration server | 8091 |
| Open WebUI | LLM interface | 3000 |
| Local AI | Open WebUI | LLM interface | 3000 |
| Data Management | Immich | Photo management | 2283 |
| Data Management | Syncthing | File synchronization | 8384 |
| Management & Infrastructure | Gitea | Git service | 8418 |
| GrampsWeb Jamie | Genealogy UI | 5511 |
| GrampsWeb Helen | Genealogy UI | 5512 |
| Speedtest Tracker | Network performance | 8180 |
| Data Management | GrampsWeb Jamie | Genealogy UI | 5511 |
| Data Management | GrampsWeb Helen | Genealogy UI | 5512 |
| Data Management | Speedtest Tracker | Network performance | 8180 |
| Management & Infrastructure | NPM Admin | NPM admin UI | 81 |
| Data Management | Maloja | Music scrobbling | 42010 |
| Data Management | Multi-Scrobbler | Cross-platform scrobbler | 9078 |
@@ -39,15 +39,15 @@ This infrastructure manages a comprehensive self-hosted environment including me
| Service Categories| Service | Role / Description | Web UI Port |
|---|---|---|---|
| Management & Infrastructure | adguard | DNS/ad-blocking | 3000 |
| Data Management | vaultwarden | Password manager | 80/8080 |
| Entertainment | crafty (Crafty Controller) | Minecraft server management | 3000 |
| Data Management | nextcloud | File sync and collaboration | 443 |
| Automation | homeassistant | Home automation | 8123 |
| Entertainment | foundryvtt | Foundry VTT | 30000 |
| Data Management | openmediavault | NAS management | 80/443 |
| Website Hosting | wordpress-irodori | WordPress site | 80 |
| Website Hosting | wordpress-dustin | WordPress site | 80 |
| Management & Infrastructure | Adguard | DNS/ad-blocking | 3000 |
| Data Management | Vaultwarden | Password manager | 80/8080 |
| Entertainment | Crafty (Crafty Controller) | Minecraft server management | 3000 |
| Data Management | Nextcloud | File sync and collaboration | 443 |
| Automation | Homeassistant | Home automation | 8123 |
| Entertainment | Foundryvtt | Foundry VTT | 30000 |
| Data Management | Openmediavault | NAS management | 80/443 |
| Website Hosting | Wordpress-irodori | WordPress site | 80 |
| Website Hosting | Wordpress-dustin | WordPress site | 80 |
### Network Segmentation

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