Backup & Restore Mechanics

Relevant source files

The following files were used as context for generating this wiki page:

• scripts/backup.sh
• src/server.js
• PLAN.md
• README.md
• test/app.test.js

PuppyPad employs a multi-layered backup system to protect the SQLite database, member files, and system configuration. The system combines automated local archiving with optional off-site synchronization to ensure data durability. Members can also manually export their individual sites as compressed archives for personal data portability.

Sources: PLAN.md:2.6, README.md:Backups

Automated System Backups

The scripts/backup.sh utility performs scheduled system-wide backups. It creates a consistent copy of the application state without requiring downtime. The backup process targets the ./data directory, which contains the SQLite database (puppypad.db) and the sites/ directory where member files reside.

Sources: src/server.js:14, PLAN.md:2.6, README.md:Backups

Backup Execution Flow

The system executes backups via a cron job, typically scheduled for 03:15 nightly. The process follows these steps:

1. Performs an online backup of the SQLite database to ensure consistency while the application is writing.
2. Archives the database backup along with the data/sites directory.
3. Stores the resulting archive in the ./backups directory.
4. Maintains a rotation of the last 14 nightly archives.
5. Synchronizes archives to a remote destination if BACKUP_REMOTE is configured using rclone.

Sources: PLAN.md:2.6, README.md:Backups

The diagram shows the automated workflow from the initial database backup to remote synchronization.
Sources: PLAN.md:2.6, README.md:Backups

Member-Initiated Backups

Individual members can export their entire site through the dashboard or API. This feature allows users to keep personal copies of their files or migrate to other hosting providers.

Sources: README.md:Building a site, src/server.js:655-663

Export Mechanisms

Feature	Method	Description
Site Download	GET /dashboard/download	Bundles every file in the member's root and subdirectories into a .zip archive.
API Export	GET /api/files	Lists every file with size and modification date for manual retrieval.
Zip Import	POST /dashboard/import	Allows users to restore or migrate sites by uploading a .zip archive.

Sources: src/server.js:655-663, src/server.js:835-842, README.md:Building a site

Export Logic

When a member requests a download, the application uses writeZip to pipe the contents of the member's directory directly to the response. The system enforces rate limits on these exports to prevent resource exhaustion.

Sources: src/server.js:655-663, test/app.test.js:231-242

The sequence diagram illustrates the process of a member initiating a site export from the dashboard.
Sources: src/server.js:655-663, test/app.test.js:231-242

Restoration Procedures

Restoring the system requires manual intervention to ensure data integrity and prevent corruption from active database handles.

Sources: README.md:Backups

Full System Restore

To perform a full restore from a system archive:

1. Stop the application container (docker compose stop app).
2. Delete transient SQLite files: data/puppypad.db-wal and data/puppypad.db-shm. This prevents these files from corrupting the restored database.
3. Unpack the chosen archive from ./backups into the ./data directory.
4. Rename the restored backup.db to puppypad.db.
5. Restart the application container (docker compose start app).

Sources: README.md:Backups

Member Site Restore

Members can restore their own files by using the Zip Import feature. The application validates imported ZIP files against several constraints:

• File Size: Entries must not exceed MAX_FILE_MB.
• Total Size: Unpacked content must fit within the member's QUOTA_MB.
• Security: Refuses traversal paths (e.g., ../), encrypted entries, and restricted file types.

Sources: src/server.js:624-648, test/app.test.js:316-353

Upgrade-Related Backups

The application includes an automated backup step during the server upgrade process. When an administrator triggers an upgrade from the /admin panel, the system performs a backup before applying new files.

Sources: src/server.js:909-923, README.md:Releases and upgrades

This diagram shows how backups are integrated into the automated upgrade safety workflow.
Sources: README.md:Releases and upgrades

Configuration Options

Backup behavior is influenced by environment variables defined in the system configuration.

Variable	Description	Default Value
DATA_DIR	Root directory for application data and site files.	./data
BACKUP_REMOTE	rclone remote destination for off-site backups.	(Unset)
QUOTA_MB	Maximum storage allowed per member site.	500
MAX_FILE_MB	Maximum size of a single file during import/upload.	5
ZIP_MAX_MB	Maximum allowed size of a ZIP archive for import.	20

Sources: src/server.js:14-36, src/db.js, README.md:Backups

Summary

The Backup & Restore Mechanics provide a redundant safety net for both the platform operator and individual members. System backups use SQLite's online backup capability for consistency, while member exports facilitate data portability. The integration of backups into the upgrade watcher ensures that system state is preserved even during critical maintenance operations.

Sources: src/server.js:909-923, README.md:Backups, PLAN.md:2.6