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

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

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