From 5029b13f02ea851e90581618e8d4fbc0ab457b41 Mon Sep 17 00:00:00 2001 From: Jamie Miller Date: Sat, 10 Jan 2026 12:55:52 +0000 Subject: [PATCH] Docs: align RESTORE.md with Architecture two-table layout; keep README Architecture two-table; drop narrative; update Crafty; last updated --- README.md | 26 ++++----- RESTORE.md | 155 +++++++---------------------------------------------- 2 files changed, 31 insertions(+), 150 deletions(-) diff --git a/README.md b/README.md index 1cd4eef..07b6f22 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/RESTORE.md b/RESTORE.md index 993c1f2..71338ce 100644 --- a/RESTORE.md +++ b/RESTORE.md @@ -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