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

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

# 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

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

cp requirements.txt /docker/discord-agent/
cp Dockerfile /docker/discord-agent/

Step 5: Update Environment Variables

Add these to your .env file:

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

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

# 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

# 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

# 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