Add S3 database backups

Author: devalade

README.md

@@ -616,8 +616,44 @@ DB_USER=myapp_user           # PostgreSQL/MySQL user to create
 DB_PASSWORD=${DB_PASSWORD:-} # PostgreSQL/MySQL password from env or .env
 DB_SQLITE_PATH=              # Optional; defaults to $REMOTE_PATH/shared/database.sqlite
 REDIS_SETUP_ENABLED=false    # Set true to install/configure Redis on localhost
+
+# === Database backups to S3 ===
+DB_BACKUP_ENABLED=false      # Set true to configure scheduled backups
+DB_BACKUP_S3_BUCKET=         # S3 bucket for uploaded backup files
+DB_BACKUP_S3_PREFIX=myapp    # Optional path prefix inside the bucket
+DB_BACKUP_SCHEDULE=daily     # hourly, daily, weekly, or systemd OnCalendar
+DB_BACKUP_RETENTION_DAYS=14  # Local compressed backup retention
+DB_BACKUP_S3_ENDPOINT=       # Optional S3-compatible endpoint
+AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID:-}
+AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY:-}
+AWS_DEFAULT_REGION=eu-west-1
+```
+
+### Database Backups
+
+ShipNode can install a small remote backup script and a systemd timer that dumps the configured PostgreSQL, MySQL, or SQLite database, compresses it, and uploads it to S3.
+
+```bash
+DB_BACKUP_ENABLED=true
+DB_BACKUP_S3_BUCKET=my-backups
+DB_BACKUP_S3_PREFIX=myapp/production
+DB_BACKUP_SCHEDULE=daily
+AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID:-}
+AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY:-}
+AWS_DEFAULT_REGION=eu-west-1
 ```
 
+Put real AWS/S3 credentials in `.env`, upload them with `shipnode env`, then configure backups:
+
+```bash
+shipnode setup
+shipnode backup setup
+shipnode backup run
+shipnode backup status
+```
+
+Use `DB_BACKUP_S3_ENDPOINT` for S3-compatible storage such as Cloudflare R2, MinIO, or DigitalOcean Spaces. `DB_BACKUP_RETENTION_DAYS` controls local compressed files on the server; use your bucket lifecycle policy for S3 retention.
+
 ### Supported Frameworks
 
 Auto-detected from your `package.json`:

build.sh

@@ -15,6 +15,7 @@ MODULES=(
     "lib/core.sh"
     "lib/release.sh"
     "lib/database.sh"
+    "lib/backup.sh"
     "lib/users.sh"
     "lib/framework.sh"
     "lib/validation.sh"
@@ -31,6 +32,7 @@ MODULES=(
     "lib/commands/rollback.sh"
     "lib/commands/migrate.sh"
     "lib/commands/env.sh"
+    "lib/commands/backup.sh"
     "lib/commands/help.sh"
     "lib/commands/main.sh"
 )

docs/advanced/architecture.md

@@ -6,7 +6,7 @@ This document describes the internal architecture and module organization of Shi
 
 ShipNode is organized as a modular bash project to improve maintainability, testability, and collaboration. The codebase is split into focused modules, each with a single responsibility.
 
-**Total: ~8,350 lines** across 26 modules.
+**Total: ~8,350 lines** across 32 modules.
 
 ## Directory Structure
 
@@ -18,6 +18,7 @@ shipnode/
 │   ├── pkg-manager.sh         # Package manager detection + PM2 template generation (236 lines)
 │   ├── release.sh             # Release management with metadata tracking (263 lines)
 │   ├── database.sh            # Database and Redis operations
+│   ├── backup.sh              # Database backup operations
 │   ├── users.sh               # User provisioning helpers (352 lines)
 │   ├── framework.sh           # Framework detection (259 lines)
 │   ├── validation.sh          # Input validation (287 lines)
@@ -37,6 +38,7 @@ shipnode/
 │       ├── rollback.sh        # Rollback command (86 lines)
 │       ├── migrate.sh         # Migrate command (92 lines)
 │       ├── env.sh             # Environment upload (42 lines)
+│       ├── backup.sh          # Database backup commands
 │       ├── eject.sh           # Eject PM2/Caddy templates (266 lines)
 │       ├── metrics.sh         # PM2 resource monitoring (12 lines)
 │       ├── config-cmd.sh      # Config show/validate/path (137 lines)
@@ -64,32 +66,34 @@ Modules are loaded in a specific order to ensure dependencies are available:
 2. **pkg-manager.sh** - Depends on core.sh
 3. **release.sh** - Depends on core.sh
 4. **database.sh** - Depends on core.sh
-5. **users.sh** - Depends on core.sh
-6. **framework.sh** - Depends on core.sh
-7. **validation.sh** - Depends on core.sh
-8. **prompts.sh** - Depends on core.sh
-9. **templates.sh** - Depends on core.sh
-10. **commands/config.sh** - Depends on core.sh
-11. **commands/users-yaml.sh** - Depends on core.sh, validation.sh
-12. **commands/user.sh** - Depends on core.sh, users.sh, validation.sh
-13. **commands/mkpasswd.sh** - Depends on core.sh
-14. **commands/init.sh** - Depends on core.sh, framework.sh, validation.sh, prompts.sh
-15. **commands/setup.sh** - Depends on core.sh, release.sh, database.sh
-16. **commands/deploy.sh** - Depends on core.sh, release.sh, pkg-manager.sh
-17. **commands/doctor.sh** - Depends on core.sh
-18. **commands/status.sh** - Depends on core.sh
-19. **commands/unlock.sh** - Depends on core.sh, release.sh
-20. **commands/rollback.sh** - Depends on core.sh, release.sh
-21. **commands/migrate.sh** - Depends on core.sh, release.sh
-22. **commands/env.sh** - Depends on core.sh
-23. **commands/eject.sh** - Depends on core.sh
-24. **commands/metrics.sh** - Depends on core.sh
-25. **commands/config-cmd.sh** - Depends on core.sh
-26. **commands/upgrade.sh** - Depends on core.sh
-27. **commands/ci.sh** - Depends on core.sh
-28. **commands/harden.sh** - Depends on core.sh
-29. **commands/help.sh** - Depends on core.sh
-30. **commands/main.sh** - Depends on all other modules
+5. **backup.sh** - Depends on core.sh
+6. **users.sh** - Depends on core.sh
+7. **framework.sh** - Depends on core.sh
+8. **validation.sh** - Depends on core.sh
+9. **prompts.sh** - Depends on core.sh
+10. **templates.sh** - Depends on core.sh
+11. **commands/config.sh** - Depends on core.sh
+12. **commands/users-yaml.sh** - Depends on core.sh, validation.sh
+13. **commands/user.sh** - Depends on core.sh, users.sh, validation.sh
+14. **commands/mkpasswd.sh** - Depends on core.sh
+15. **commands/init.sh** - Depends on core.sh, framework.sh, validation.sh, prompts.sh
+16. **commands/setup.sh** - Depends on core.sh, release.sh, database.sh, backup.sh
+17. **commands/deploy.sh** - Depends on core.sh, release.sh, pkg-manager.sh
+18. **commands/doctor.sh** - Depends on core.sh
+19. **commands/status.sh** - Depends on core.sh
+20. **commands/unlock.sh** - Depends on core.sh, release.sh
+21. **commands/rollback.sh** - Depends on core.sh, release.sh
+22. **commands/migrate.sh** - Depends on core.sh, release.sh
+23. **commands/env.sh** - Depends on core.sh
+24. **commands/backup.sh** - Depends on core.sh, backup.sh
+25. **commands/eject.sh** - Depends on core.sh
+26. **commands/metrics.sh** - Depends on core.sh
+27. **commands/config-cmd.sh** - Depends on core.sh
+28. **commands/upgrade.sh** - Depends on core.sh
+29. **commands/ci.sh** - Depends on core.sh
+30. **commands/harden.sh** - Depends on core.sh
+31. **commands/help.sh** - Depends on core.sh
+32. **commands/main.sh** - Depends on all other modules
 
 ## Module Descriptions
 
@@ -140,6 +144,16 @@ Modules are loaded in a specific order to ensure dependencies are available:
 - `setup_sqlite()` - Install SQLite and create database file
 - `setup_redis()` - Install and configure Redis
 
+#### backup.sh
+
+**Purpose:** Database backup configuration, remote script installation, and S3 upload operations
+
+**Key Functions:**
+- `setup_database_backups()` - Install dependencies, write backup files, and configure timer
+- `run_database_backup()` - Run a backup immediately on the remote server
+- `list_database_backups()` - List uploaded backups in S3
+- `show_database_backup_status()` - Show systemd timer status, logs, and local backups
+
 #### users.sh (352 lines)
 
 **Purpose:** User provisioning helper functions
@@ -331,6 +345,13 @@ Modules are loaded in a specific order to ensure dependencies are available:
 **Key Functions:**
 - `cmd_env()` - Upload .env file to server
 
+#### commands/backup.sh
+
+**Purpose:** Database backup command router
+
+**Key Functions:**
+- `cmd_backup()` - Route backup subcommands: setup, run, status, list
+
 #### commands/ci.sh (362 lines)
 
 **Purpose:** CI/CD integration commands

docs/guides/configuration/shipnode-conf.md

@@ -101,6 +101,31 @@ DB_PASSWORD=${DB_PASSWORD:-}
 
 `DB_TYPE` can be `postgresql`, `mysql`, or `sqlite`. PostgreSQL/MySQL setup installs the server if missing, starts/enables it, creates the database/user, and grants privileges. SQLite setup installs `sqlite3` and creates a database file at `DB_SQLITE_PATH`, defaulting to `$REMOTE_PATH/shared/database.sqlite`. Keep SQLite files under `shared/`; ShipNode rejects paths inside `current/` or `releases/`.
 
+### Database Backups to S3
+
+Enable backups when ShipNode should dump the configured database and upload compressed files to S3 on a schedule:
+
+```bash
+DB_BACKUP_ENABLED=true
+DB_BACKUP_S3_BUCKET=my-backups
+DB_BACKUP_S3_PREFIX=myapp/production
+DB_BACKUP_SCHEDULE=daily
+DB_BACKUP_RETENTION_DAYS=14
+AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID:-}
+AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY:-}
+AWS_DEFAULT_REGION=eu-west-1
+```
+
+Put the real `AWS_*` values in `.env`, upload them with `shipnode env`, then run:
+
+```bash
+shipnode backup setup
+shipnode backup run
+shipnode backup status
+```
+
+`DB_BACKUP_SCHEDULE` accepts `hourly`, `daily`, `weekly`, or a systemd `OnCalendar` expression. Set `DB_BACKUP_S3_ENDPOINT` for S3-compatible providers.
+
 Enable Redis separately:
 
 ```bash

docs/reference/commands.md

@@ -60,6 +60,15 @@ All ShipNode commands with descriptions.
 | `shipnode env pull` | Download .env from server |
 | `shipnode env list` | List environment variables |
 
+## Backup Commands
+
+| Command | Description |
+|---------|-------------|
+| `shipnode backup setup` | Install/update database backup script and systemd timer |
+| `shipnode backup run` | Run a database backup immediately |
+| `shipnode backup status` | Show timer status, recent logs, and local backups |
+| `shipnode backup list` | List uploaded backups in S3 |
+
 ## User Commands
 
 | Command | Description |

docs/reference/configuration-reference.md

@@ -129,6 +129,37 @@ Run schema migrations from `.shipnode/pre-deploy.sh`; database creation and migr
 
 Keep SQLite files under `shared/` so they survive release switches and cleanup. ShipNode rejects paths inside `$REMOTE_PATH/current/` or `$REMOTE_PATH/releases/`.
 
+### Database Backups
+
+When `DB_BACKUP_ENABLED=true`, `shipnode setup` and `shipnode backup setup` install a remote backup script at `$REMOTE_PATH/shared/shipnode-backup.sh` and enable a systemd timer. Backups are compressed locally, uploaded to S3, and can be run manually with `shipnode backup run`.
+
+| Variable | Type | Default | Description |
+|----------|------|---------|-------------|
+| `DB_BACKUP_ENABLED` | boolean | `false` | Enable scheduled database backups |
+| `DB_BACKUP_S3_BUCKET` | string | - | S3 bucket where backups are uploaded |
+| `DB_BACKUP_S3_PREFIX` | string | app name | Optional S3 key prefix |
+| `DB_BACKUP_SCHEDULE` | string | `daily` | `hourly`, `daily`, `weekly`, or a systemd `OnCalendar` value |
+| `DB_BACKUP_RETENTION_DAYS` | number | `14` | Days to keep local compressed backups on the server |
+| `DB_BACKUP_S3_ENDPOINT` | string | - | Optional S3-compatible endpoint |
+| `AWS_ACCESS_KEY_ID` | string | - | S3 access key, preferably from `.env` |
+| `AWS_SECRET_ACCESS_KEY` | string | - | S3 secret key, preferably from `.env` |
+| `AWS_DEFAULT_REGION` | string | - | S3 region |
+
+Example:
+
+```bash
+DB_BACKUP_ENABLED=true
+DB_BACKUP_S3_BUCKET=my-backups
+DB_BACKUP_S3_PREFIX=myapp/production
+DB_BACKUP_SCHEDULE=daily
+DB_BACKUP_RETENTION_DAYS=14
+AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID:-}
+AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY:-}
+AWS_DEFAULT_REGION=eu-west-1
+```
+
+Store real credentials in `.env`, run `shipnode env`, then run `shipnode backup setup`. S3 object retention should be managed with bucket lifecycle rules; ShipNode only prunes local compressed files.
+
 ### Advanced
 
 | Variable | Type | Description |