Backup & Restore

Ontheia stores all persistent data in two Docker volumes. Regular backups are especially important before updates and in production environments.

Volume Overview

Volume	Contents
ontheia-db-data	PostgreSQL database (chats, agents, configuration, users)
ontheia-sources	Namespace rule files (memory policies, configuration)

---

Backup

Database Backup (SQL Dump)

docker exec ontheia-db pg_dump -U postgres ontheia > backup-$(date +%Y%m%d).sql

Compressed backup:

docker exec ontheia-db pg_dump -U postgres ontheia | gzip > backup-$(date +%Y%m%d).sql.gz

Namespaces Volume

docker run --rm \
  -v ontheia-sources:/data \
  -v "$(pwd)/backups:/backup" \
  alpine tar czf /backup./sources-$(date +%Y%m%d).tar.gz /data

Full Backup Script

#!/bin/bash
BACKUP_DIR="./backups"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
mkdir -p "$BACKUP_DIR"

# Database
docker exec ontheia-db pg_dump -U postgres ontheia \
  > "$BACKUP_DIR/ontheia-db-${TIMESTAMP}.sql"
echo "✓ DB backup: $BACKUP_DIR/ontheia-db-${TIMESTAMP}.sql"

# Namespaces volume
docker run --rm \
  -v ontheia-sources:/data \
  -v "$(pwd)/backups:/backup" \
  alpine tar czf "/backup/sources-${TIMESTAMP}.tar.gz" /data
echo "✓ Namespaces backup: $BACKUP_DIR/sources-${TIMESTAMP}.tar.gz"

Recommendation: Cron Job

Automated daily backup (Linux crontab):

# Every day at 03:00
0 3 * * * cd /opt/ontheia && bash scripts/backup.sh >> /var/log/ontheia-backup.log 2>&1

---

Restore

Restore Database

Warning: This overwrites all current data in the database.

# Stop services
docker compose stop host webui

# Drop and recreate database
docker exec -i ontheia-db psql -U postgres -c "DROP DATABASE IF EXISTS ontheia;"
docker exec -i ontheia-db psql -U postgres -c "CREATE DATABASE ontheia;"
docker exec -i ontheia-db psql -U postgres ontheia < backup-20240101.sql

# Re-run migrations (ensures schema consistency)
docker compose up -d migrator
docker compose wait migrator

# Start services again
docker compose up -d

From a compressed backup:

gunzip -c backup-20240101.sql.gz | docker exec -i ontheia-db psql -U postgres ontheia

Restore Namespaces Volume

docker run --rm \
  -v ontheia-sources:/data \
  -v "$(pwd)/backups:/backup" \
  alpine sh -c "rm -rf /data/* && tar xzf /backup./sources-20240101.tar.gz -C / --strip-components=1"

---

Backup Before Updates

The update.sh script automatically creates a backup before every update:

bash scripts/update.sh

Backups are stored in the ./backups/ directory.

---

Notes

• Back up your .env file: It contains all secrets (DB passwords, API keys, METRICS_TOKEN). Store it separately and encrypted.
• Test your backups: Regularly perform a restore on a test instance to verify backups are valid.
• Off-site storage: Copy backups to external storage (S3, NFS, USB) — backups in the same directory do not protect against server loss.