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

## Discord Agent Service

### Step 1: Create Discord Agent Directory
```bash
mkdir -p /docker/discord-agent/config /docker/discord-agent/data/logs /docker/discord-agent/data/database /docker/discord-agent/data/cache /docker/discord-agent/cogs /docker/discord-agent/scripts
```

### Step 2: Copy Configuration Files
```bash
# Copy agent configuration
cp agent-config.yaml /docker/discord-agent/config/
cp permissions.json /docker/discord-agent/config/

# Copy scripts
cp startup.sh /docker/discord-agent/scripts/
cp health_check.sh /docker/discord-agent/scripts/
```

### Step 3: Copy Python Files
```bash
cp discord_agent.py /docker/discord-agent/
cp base_cog.py /docker/discord-agent/cogs/
cp integration_cog.py /docker/discord-agent/cogs/
```

### Step 4: Copy Requirements
```bash
cp requirements.txt /docker/discord-agent/
cp Dockerfile /docker/discord-agent/
```

### Step 5: Update Environment Variables
Add these to your `.env` file:
```bash
# Discord Agent
DISCORD_BOT_TOKEN=your_discord_bot_token_here
OLLAMA_ENDPOINT=http://192.168.0.31:11434
OLLAMA_MODEL=ministral-3:8b
TZ=Pacific/Auckland
```

### Step 6: Update Configuration
Edit `/docker/discord-agent/config/agent-config.yaml` with your specific settings:
```yaml
discord:
  token: ${DISCORD_BOT_TOKEN}
  prefix: "!"
  status: "AI Assistant | !help"

ollama:
  endpoint: "${OLLAMA_ENDPOINT:http://192.168.0.31:11434}"
  model: "${OLLAMA_MODEL:ministral-3:8b}"
  parameters:
    temperature: 0.7
    top_p: 0.9
    top_k: 40
  timeout: 60
```

### Step 7: Build and Start Service
```bash
# Build the Discord agent image
docker compose build discord-agent

# Start the service
docker compose up -d discord-agent

# Verify the service is running
docker compose logs discord-agent
```

### Step 8: Verify Integration
```bash
# Check Discord bot connection
docker exec discord-agent python3 -c "import discord; print('Discord library available')"

# Check Ollama connection
curl http://192.168.0.31:11434/api/tags

# Check MySQL database
docker compose exec agent-db mysql -u agent -pagent -e "SHOW DATABASES;"
```

### Step 9: Test Bot Functionality
- The bot should appear in your Discord server
- Test with `!help` command to verify functionality
- Test with `!agent <message>` to verify Ollama integration
- Test with `!status` to check bot status

### Troubleshooting
- If bot doesn't start, check logs: `docker compose logs discord-agent`
- Verify DISCORD_BOT_TOKEN is set correctly in `.env` file
- Ensure Ollama is running and accessible at the configured endpoint
- Verify internal_net and db_net networks are available
- Check that MySQL database agent-db is running and healthy

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