Include RESTORE.md as documentation companion; finalize Architecture two-table tables and push
This commit is contained in:
Jamie Miller
338
RESTORE.md
Normal file
338
RESTORE.md
Normal file
@@ -0,0 +1,338 @@
|
||||
# Restoration Guide
|
||||
|
||||
This guide walks you through restoring your Docker infrastructure from a backup.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Fresh system with Docker and Docker Compose installed
|
||||
- Backup archive (`docker-backup-YYYYMMDD_HHMMSS.tar.gz`)
|
||||
- Access to NAS storage (if applicable)
|
||||
- Root or sudo access
|
||||
|
||||
## Step 1: Extract Backup
|
||||
|
||||
```bash
|
||||
# Navigate to your backup location
|
||||
cd /path/to/backups
|
||||
|
||||
# Extract the backup archive
|
||||
tar xzf docker-backup-YYYYMMDD_HHMMSS.tar.gz
|
||||
|
||||
# Navigate into the extracted backup
|
||||
cd YYYYMMDD_HHMMSS
|
||||
```
|
||||
|
||||
## Step 2: Restore Directory Structure
|
||||
|
||||
```bash
|
||||
# Copy the directory structure script
|
||||
cp directory_structure.sh /opt/docker-compose/
|
||||
cd /opt/docker-compose/
|
||||
|
||||
# Make it executable and run
|
||||
chmod +x directory_structure.sh
|
||||
./directory_structure.sh
|
||||
```
|
||||
|
||||
## Step 3: Restore Docker Compose Configuration
|
||||
|
||||
```bash
|
||||
# Copy main configuration files
|
||||
cp /path/to/backup/docker-compose.yaml .
|
||||
cp /path/to/backup/.env .
|
||||
cp /path/to/backup/.gitignore .
|
||||
cp /path/to/backup/README.md .
|
||||
|
||||
# IMPORTANT: Edit .env file with new system-specific values
|
||||
nano .env
|
||||
|
||||
# Verify the configuration
|
||||
docker compose config
|
||||
```
|
||||
|
||||
## Step 4: Restore Service Configurations
|
||||
|
||||
```bash
|
||||
# Copy service configurations back to /docker
|
||||
rsync -av /path/to/backup/docker/ /docker/
|
||||
|
||||
# Set correct permissions
|
||||
PUID=$(id -u)
|
||||
PGID=$(id -g)
|
||||
sudo chown -R $PUID:$PGID /docker
|
||||
```
|
||||
|
||||
## Step 5: Restore Docker Volumes
|
||||
|
||||
For each volume backup in `/path/to/backup/volumes/`:
|
||||
|
||||
```bash
|
||||
# Create the volume if it doesn't exist
|
||||
docker volume create VOLUME_NAME
|
||||
|
||||
# Restore the volume data
|
||||
docker run --rm \
|
||||
-v VOLUME_NAME:/volume \
|
||||
-v /path/to/backup/volumes:/backup \
|
||||
alpine \
|
||||
tar xzf /backup/VOLUME_NAME.tar.gz -C /volume
|
||||
```
|
||||
|
||||
Example for specific volumes:
|
||||
|
||||
```bash
|
||||
# Restore Portainer data
|
||||
docker volume create portainer_data
|
||||
docker run --rm \
|
||||
-v portainer_data:/volume \
|
||||
-v /path/to/backup/volumes:/backup \
|
||||
alpine \
|
||||
tar xzf /backup/portainer_data.tar.gz -C /volume
|
||||
|
||||
# Restore Open WebUI data
|
||||
docker volume create open-webui
|
||||
docker run --rm \
|
||||
-v open-webui:/volume \
|
||||
-v /path/to/backup/volumes:/backup \
|
||||
alpine \
|
||||
tar xzf /backup/open-webui.tar.gz -C /volume
|
||||
|
||||
# Repeat for other volumes...
|
||||
```
|
||||
|
||||
## Step 6: Start Database Services First
|
||||
|
||||
```bash
|
||||
# Start only database services
|
||||
docker compose up -d paperless-db immich-postgres litellm-postgres wygiwyh-db gitea-db speedtest-db npm-db
|
||||
|
||||
# Wait for databases to be healthy
|
||||
docker compose ps
|
||||
|
||||
# Check logs for any errors
|
||||
docker compose logs -f paperless-db
|
||||
# Press Ctrl+C to exit logs
|
||||
```
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
## Step 8: Mount NAS Storage (if applicable)
|
||||
|
||||
```bash
|
||||
# Create mount point
|
||||
sudo mkdir -p /mnt/Nas-Storage
|
||||
|
||||
# Add to /etc/fstab for permanent mounting
|
||||
# Example for NFS:
|
||||
# nas-server:/volume1/data /mnt/Nas-Storage nfs defaults 0 0
|
||||
|
||||
# Example for CIFS/SMB:
|
||||
# //nas-server/data /mnt/Nas-Storage cifs credentials=/root/.smbcredentials,uid=1000,gid=1000 0 0
|
||||
|
||||
# Mount immediately
|
||||
sudo mount -a
|
||||
|
||||
# Verify mount
|
||||
df -h /mnt/Nas-Storage
|
||||
```
|
||||
|
||||
## Step 9: Start All Services
|
||||
|
||||
```bash
|
||||
# Start all services
|
||||
docker compose up -d
|
||||
|
||||
# Watch the startup process
|
||||
docker compose logs -f
|
||||
|
||||
# Check service health
|
||||
docker compose ps
|
||||
```
|
||||
|
||||
## Step 10: Verify Services
|
||||
|
||||
Go through each service and verify it's working correctly:
|
||||
|
||||
### Check Web Interfaces
|
||||
- Homepage: http://your-server:7575
|
||||
- Portainer: https://your-server:9443
|
||||
- Jellyfin: http://your-server:8096
|
||||
- Paperless: http://your-server:8100
|
||||
- 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;"
|
||||
|
||||
# Immich
|
||||
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
|
||||
|
||||
# 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`
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: December 2025
|
||||
Reference in New Issue
Block a user