Backup and Restore
Relevant source files
The following files were used as context for generating this wiki page:
Nyansa provides automated scripts to safeguard the state of the AI "second brain" stack. The system captures the PostgreSQL database, every stateful Docker volume, and generates checksums for verification. These operations ensure data persistence across deployments and enable recovery from hardware failure or configuration errors.
The backup and restore logic centers on two primary scripts: scripts/backup.sh and scripts/restore.sh. These scripts manage the lifecycle of stateful components like n8n workflows, Qdrant vector segments, and Open WebUI SQLite databases.
Sources: README.md:32-34, scripts/backup.sh:1-12
Backup Architecture
The backup process creates a timestamped folder containing a logical dump of the PostgreSQL database and compressed tarballs of individual volumes. It utilizes a helper Docker image to perform cold copies of volumes while services are temporarily stopped to ensure data consistency.
Data Flow for Backup
The following diagram illustrates the sequence of operations during a backup:
Sources: scripts/backup.sh:55-126
Target Volumes and Exclusions
The system archives specific stateful volumes while excluding temporary caches to minimize backup size.
| Volume Name | Purpose | Exclusions |
|---|---|---|
nyansa_n8n_storage | n8n workflows and nodes | None |
nyansa_qdrant_storage | Vector database segments | None |
nyansa_openwebui_storage | Chat history and settings | ./cache |
nyansa_caddy_data | SSL certificates and keys | None |
nyansa_tailscale_state | Tailscale node identity | None |
Sources: scripts/backup.sh:26-38
Restore Mechanism
The restore process replaces existing volume content with data from a backup folder. You must have an existing stack created via docker compose up -d before running the restore script. The script stops all running containers, wipes existing volumes, extracts archives, and restores the PostgreSQL dump.
Restore Procedure Sequence
Sources: scripts/restore.sh:31-90
Key Components and Configurations
Configuration Variables
Environmental variables control backup destination, retention, and the helper utility used for volume access.
| Variable | Description | Default Value |
|---|---|---|
BACKUP_DIR | Root directory for backup storage | ./backups |
BACKUP_RETENTION_DAYS | Number of days to keep backups (0 = infinite) | 14 |
BACKUP_HELPER_IMAGE | Image used for tar operations | alpine:3.24.2 |
Sources: scripts/backup.sh:15-20
Security and Verification
- Checksums: The backup script generates
SHA256SUMSfor all artifacts. The restore script verifies these checksums before proceeding. - Permissions: Backups use
umask 077to restrict access to the backup creator. - Secrets: The
.envfile andN8N_ENCRYPTION_KEYare not included in backups. You must store these separately to decrypt n8n credentials after restoration. - Consistency: "Writer" containers (e.g., Qdrant, n8n) stop during volume archiving to prevent database corruption.
Sources: scripts/backup.sh:8-12, scripts/backup.sh:69-80, scripts/restore.sh:44-46
Operational Usage
Creating a Backup
You trigger a backup manually or during deployment. The system automatically creates a backup folder named with a UTC timestamp (e.g., 20260926T150000Z).
# Manual backup
scripts/backup.sh
Sources: scripts/backup.sh:73-77, README.md:129-132
Restoring from Backup
Restoration requires the --yes flag to confirm the destructive operation on existing data.
# Restore specific backup
scripts/restore.sh ./backups/20260926T150000Z --yes
Sources: scripts/restore.sh:12-14
Summary
The Backup and Restore system ensures the Nyansa stack remains resilient. By combining logical PostgreSQL dumps with physical volume archiving, it captures the entire application state. Users are responsible for managing the .env file and encryption keys externally, as these are omitted from the automated backup process for security reasons.
Sources: scripts/backup.sh:8-12, README.md:144-145