Zap Platform Backup & Restore Guide

Complete backup and restore procedures for the Zap platform and all its components.

Quick Reference

Component	Location	Backup Location	Retention
-----------	----------	-----------------	-----------
PostgreSQL	`/var/lib/postgresql/`	`/mnt/merlin-backups/databases/postgresql/`	7d+4w+3m
SQLite (Zap-Mail)	`/var/www/zap-mail/data/`	`/mnt/merlin-backups/databases/sqlite/orcus/zap-mail/`	7d+4w+3m
SQLite (Philoenic)	`/var/www/philoenic.com/data/`	`/mnt/merlin-backups/databases/sqlite/orcus/philoenic/`	7d+4w+3m
Code	`/var/www/zap/`	`/mnt/atrium-data/orcus-backups/var/www/zap/`	Daily
Config	`/var/www/zap/env/`	`/mnt/atrium-data/orcus-backups/zap-env/`	Daily

---

PostgreSQL Database Restore

Single Database Restore

Identify Backup File

   # Check backup history table
   psql -U zap_user -d zap -c "SELECT backup_path, created_at FROM backup_history WHERE database_name = 'zap' AND status = 'success' ORDER BY created_at DESC LIMIT 5;"
   
   # Or list backup files
   ls -la /mnt/merlin-backups/databases/postgresql/zap_*.sql.gz | tail -5
   ``
Restore Using pg_restore (for custom-format dumps)
   `bash
   # Drop and recreate database
   sudo -u postgres dropdb zap
   sudo -u postgres createdb -O zap_user zap
   
   # Restore from backup
   gunzip -c /path/to/zap_2024-02-24_daily.sql.gz | sudo -u postgres psql zap
   `
Verify Restore
   `bash
   # Check table counts
   psql -U zap_user -d zap -c "
     SELECT 'chats' AS table_name, COUNT(*) FROM cursor_chats
     UNION ALL
     SELECT 'plans', COUNT(*) FROM cursor_plans
     UNION ALL
     SELECT 'projects', COUNT(*) FROM cursor_projects;
   "
   
   # Check specific critical data
   psql -U zap_user -d zap -c "SELECT COUNT(*) FROM writer_documents;"
   `
Full PostgreSQL Restore
Stop All Applications
   `bash
   sudo systemctl stop apache2
   sudo systemctl stop orcus_zap-chat-watcher
   `
Restore All Databases
   `bash
   # List all database backups
   ls -la /mnt/merlin-backups/databases/postgresql/*.sql.gz
   
   # Restore each database
   for db in zap energystats philanthropy_planner prospecta_cc; do
     latest=$(ls -t /mnt/merlin-backups/databases/postgresql/${db}_*.sql.gz | head -1)
     echo "Restoring $db from $latest"
     sudo -u postgres dropdb $db 2>/dev/null
     sudo -u postgres createdb -O zap_user $db
     gunzip -c "$latest" | sudo -u postgres psql $db
   done
   `
Recreate Extensions and Functions
   `bash
   # Enable required extensions
   sudo -u postgres psql zap -c "CREATE EXTENSION IF NOT EXISTS pg_trgm;"
   sudo -u postgres psql zap -c "CREATE EXTENSION IF NOT EXISTS vector;"
   `
---
SQLite Database Restore
Zap-Mail Restore
Stop Zap-Mail Service
   `bash
   sudo systemctl stop apache2  # If running under Apache
   # Or stop any standalone service
   `
Backup Current Database (in case restore fails)
   `bash
   cp /var/www/zap-mail/data/zap-mail.sqlite /var/www/zap-mail/data/zap-mail.sqlite.bak
   `
Restore from Backup
   `bash
   # Find latest backup
   latest=$(ls -t /mnt/merlin-backups/databases/sqlite/orcus/zap-mail/*.sqlite.gz | head -1)
   
   # Decompress and restore
   gunzip -c "$latest" > /var/www/zap-mail/data/zap-mail.sqlite
   chmod 644 /var/www/zap-mail/data/zap-mail.sqlite
   chown www-data:www-data /var/www/zap-mail/data/zap-mail.sqlite
   `
Verify Integrity
   `bash
   sqlite3 /var/www/zap-mail/data/zap-mail.sqlite "PRAGMA integrity_check;"
   sqlite3 /var/www/zap-mail/data/zap-mail.sqlite "SELECT COUNT(*) FROM messages;"
   `
Restart Service
   `bash
   sudo systemctl start apache2
   `
Philoenic Restore
Stop Application
   `bash
   sudo systemctl stop apache2
   `
Restore Database
   `bash
   # Find latest backup (may have environment suffix)
   latest=$(ls -t /mnt/merlin-backups/databases/sqlite/orcus/philoenic/*_local.sqlite.gz | head -1)
   
   # Decompress and restore
   gunzip -c "$latest" > /var/www/philoenic.com/data/philoenic.sqlite
   chmod 644 /var/www/philoenic.com/data/philoenic.sqlite
   chown www-data:www-data /var/www/philoenic.com/data/philoenic.sqlite
   `
Verify and Restart
   `bash
   sqlite3 /var/www/philoenic.com/data/philoenic.sqlite "PRAGMA integrity_check;"
   sqlite3 /var/www/philoenic.com/data/philoenic.sqlite "SELECT COUNT(*) FROM documents;"
   sudo systemctl start apache2
   `
---
Code and Configuration Restore
Code Repository Restore
Check Git Status
   `bash
   cd /var/www/zap
   git status
   `
Reset to Last Known Good State
   `bash
   # If working directory is corrupted
   git reset --hard HEAD
   git clean -fd
   
   # Or restore from backup
   sudo rm -rf /var/www/zap
   sudo cp -r /mnt/atrium-data/orcus-backups/var/www/zap /var/www/
   sudo chown -R www-data:www-data /var/www/zap
   `
Reinstall Dependencies
   `bash
   cd /var/www/zap
   sudo -u www-data composer install --no-dev
   `
Environment Configuration
Restore .env File
   `bash
   sudo cp /mnt/atrium-data/orcus-backups/zap-env/.env /var/www/zap/env/
   sudo chown www-data:www-data /var/www/zap/env/.env
   sudo chmod 600 /var/www/zap/env/.env
   `
Verify Configuration
   `bash
   # Test database connection
   php -r "require 'env/.env'; echo 'DB_HOST: ' . DB_HOST . PHP_EOL;"
   `
---
Application-Specific Procedures
Zap-Projects Restore
Database Restore (see PostgreSQL section)
File Watcher Restart
   `bash
   sudo systemctl restart orcus_zap-chat-watcher
   `
Verify MCP Server
   `bash
   # Test MCP connectivity
   curl -s http://localhost:8080/list_tools
   `
Zap-Writer Restore
Database Restore (see PostgreSQL section)
Rebuild Embeddings (if corrupted)
   `bash
   cd /var/www/zap/apps/zap-writer
   php bin/rebuild-embeddings.php --project=hidden-money
   `
Verify LLM Gateway
   `bash
   curl -s http://llm.orcus.lan/v1/models | jq .
   `
---
Disaster Recovery Scenarios
Scenario 1: Database Corruption
Symptoms: Database errors, connection failures
Time to Recover: 15-30 minutes
Identify affected database from error logs
Restore from most recent backup
Verify application functionality
Log incident in CODING_HISTORY.md
Scenario 2: Code Deployment Failure
Symptoms: 500 errors, missing files
Time to Recover: 10-20 minutes
Check git status and recent commits
Reset to previous working commit
Clear caches and restart services
Test all applications
Scenario 3: Full Server Migration
Symptoms: Hardware failure, complete outage
Time to Recover: 2-4 hours
See /var/www/orcus.lan/docs/BACKUP_RESTORE.md for full server restore

Follow Zap-specific procedures after system is restored
Test all Zap applications
Update DNS if needed
---
Verification & Testing
Post-Restore Checklist
Database Connectivity
   `bash
   psql -U zap_user -d zap -c "SELECT version();"
   `
Web Application Tests
   `bash
   # Zap-Projects
   curl -k https://zap.orcus.lan/projects/ | grep -q "Zap Projects"
   
   # Zap-Mail
   curl -k https://zap-mail.orcus.lan/ | grep -q "Zap Mail"
   
   # Philoenic
   curl -k https://philoenic.com/ | grep -q "Philoenic"
   `
API Endpoints
   `bash
   # Zap-Projects API
   curl -s https://zap.orcus.lan/projects/api/search.php?q=test | jq .
   
   # Zap-Writer RAG
   curl -sk https://zap.orcus.lan/writer/api/rag-search.php \
     -X POST -H 'Content-Type: application/json' \
     -d '{"project_slug":"test","query":"test","limit":1}'
   `
Background Services
   `bash
   sudo systemctl status orcus_zap-chat-watcher
   sudo systemctl status orcus_tusd
   sudo systemctl status orcus_centrifugo
   `
Automated TestingAdd to /var/www/zap/docs/TESTING.md:

bash
Database restore test
sudo -u postgres createdb test_restore
gunzip -c /mnt/merlin-backups/databases/postgresql/zap_*.sql.gz | \
  sudo -u postgres psql test_restore
sudo -u postgres dropdb test_restore

---
Backup Verification Schedule
Daily (Automated)
Backup scripts run and log to backup_history table

Telegram/ntfy notifications on failure
Disk space monitoring
Weekly (Manual)
Verify backup files are not corrupted
Test restore of one SQLite database
Check backup rotation is working correctly
Monthly (Manual)
Test restore of PostgreSQL database to temporary copy
Verify all applications can connect after restore
Document any issues
Quarterly (Full Drill)
Complete application restore to staging environment
Test full disaster recovery procedures
Update documentation based on lessons learned
---
Common Issues & SolutionsIssue: PostgreSQL Restore Fails with "role does not exist"bash
Create missing user
sudo -u postgres createuser zap_user
Grant necessary permissions
sudo -u postgres psql -c "ALTER USER zap_user CREATEDB;"

Issue: SQLite Database is Lockedbash
Find and kill processes using the database
sudo fuser /var/www/zap-mail/data/zap-mail.sqlite
Or stop the web server temporarily
sudo systemctl stop apache2

Issue: Composer Dependencies Missingbash
cd /var/www/zap
sudo -u www-data composer install --no-dev --optimize-autoloader

Issue: File Permissions Incorrectbash
Fix web directory permissions
sudo chown -R www-data:www-data /var/www/zap
sudo find /var/www/zap -type f -exec chmod 644 {} \;
sudo find /var/www/zap -type d -exec chmod 755 {} \;


---
Related Documentation

Orcus Server Restore: /var/www/orcus.lan/docs/BACKUP_RESTORE.md

Testing Guide: /var/www/zap/docs/TESTING.md

Infrastructure: /var/www/zap/docs/INFRASTRUCTURE.md

Coding History: /var/www/zap/docs/CODING_HISTORY.md`

← Back to Zap Projects 🖥️ Orcus Server Docs →

📚 Zap Platform Documentation

Zap Platform Backup & Restore Guide

Quick Reference

PostgreSQL Database Restore

Single Database Restore

Full PostgreSQL Restore

SQLite Database Restore

Zap-Mail Restore

Philoenic Restore

Code and Configuration Restore

Code Repository Restore

Environment Configuration

Application-Specific Procedures

Zap-Projects Restore

Zap-Writer Restore

Disaster Recovery Scenarios

Scenario 1: Database Corruption

Scenario 2: Code Deployment Failure

Scenario 3: Full Server Migration

Verification & Testing

Post-Restore Checklist

Automated Testing

Database restore test

Backup Verification Schedule

Daily (Automated)

Weekly (Manual)

Monthly (Manual)

Quarterly (Full Drill)

Common Issues & Solutions

`Issue: PostgreSQL Restore Fails with "role does not exist"`

Create missing user

Grant necessary permissions

`Issue: SQLite Database is Locked`

Find and kill processes using the database

Or stop the web server temporarily

`Issue: Composer Dependencies Missing`

`Issue: File Permissions Incorrect`

Fix web directory permissions

Related Documentation