Files

Jamie Miller 108ef2dda8 Include RESTORE.md as documentation companion; finalize Architecture two-table tables and push

2026-01-10 12:36:25 +00:00

7.7 KiB

Raw Blame History

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

# 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

# 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

# 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

# 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/:

# 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:

# 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

# 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

# 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

docker exec -i immich_postgres psql -U postgres immich < /path/to/backup/database-dumps/immich.sql

LiteLLM PostgreSQL

docker exec -i litellm-postgres psql -U litellm litellm_db < /path/to/backup/database-dumps/litellm.sql

WYGIWYH PostgreSQL

docker exec -i WYGIWYH-db psql -U ${WYGIWYH_DB_USER} ${WYGIWYH_DB_DATABASE} < /path/to/backup/database-dumps/wygiwyh.sql

Gitea MySQL

docker exec -i gitea-db mysql -u root -pgitea gitea < /path/to/backup/database-dumps/gitea.sql

Speedtest Tracker MariaDB

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)

# 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

# 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

Verify Databases

# 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

# 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)

Access Nginx Proxy Manager at http://your-server:81
Default credentials (if fresh install):
- Email: admin@example.com
- Password: changeme
Recreate proxy hosts for each service
Restore SSL certificates (if backed up in /npm/letsencrypt)

Troubleshooting

Service Won't Start

# 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

# 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

# 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

# Verify .env file is loaded
docker compose config | grep VARIABLE_NAME

# Check for typos in .env
cat .env | grep VARIABLE_NAME

Volume Restore Failed

# 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:

# 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:

Start with minimal services (databases only)
Verify database connectivity
Add services one at a time
Check logs after each addition
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

7.7 KiB Raw Blame History