Homelab/RESTORE.md

Restoration Guide

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
• 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

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

• 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

# 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;"

... (rest of file continues)

Architecture Alignment

• This section connects to the Architecture two-table layout described in README.md.

Last Updated: December 2025