BBS MongoDB Wiki Patch

changes.patch

From b8ea9db9c4299b111d6aff374ed15cd7f84650f8 Mon Sep 17 00:00:00 2001
From: sainf <suporte@sainf.com>
Date: Mon, 30 Mar 2026 23:14:50 +0100
Subject: [PATCH] Add MongoDB backup support to documentation and plugin
 overview

---
 Database-Backups.md | 141 ++++++++++++++++++++++++++++++++++++++++++--
 Plugins.md          |  54 ++++++++++++++++-
 2 files changed, 187 insertions(+), 8 deletions(-)

diff --git a/Database-Backups.md b/Database-Backups.md
index c9e2ebb..20ab39c 100644
--- a/Database-Backups.md
+++ b/Database-Backups.md
@@ -1,11 +1,11 @@
 # Database Backups
 
-BBS provides dedicated plugins for backing up MySQL and PostgreSQL databases. These plugins automatically dump databases before each backup operation, ensuring consistent, point-in-time database backups.
+BBS provides dedicated plugins for backing up MySQL, PostgreSQL, and MongoDB databases. These plugins automatically dump databases before each backup operation, ensuring consistent, point-in-time database backups.
 
 ## Overview
 
 Database backup plugins work by:
-1. Running a database dump (mysqldump or pg_dump) before Borg creates the backup archive
+1. Running a database dump (mysqldump, pg_dump, or mongodump) before Borg creates the backup archive
 2. Saving the dump files to a specified directory on the client machine
 3. Including those dump files in the regular Borg backup
 4. Allowing one-click restoration through the BBS web interface
@@ -87,9 +87,9 @@ When a backup job runs with a MySQL plugin attached:
 > **Screenshot:** MySQL restore dialog with database selection and target credentials
 
 The restore process:
-- Downloads the SQL dump files from the Borg archive
-- Connects to the target MySQL server
-- Creates databases (or drops/recreates if they exist)
+- Extracts the SQL dump files from the selected Borg archive (stored in the Dump Directory path within the archive)
+- Connects to the target MySQL server using the selected connector
+- Applies the chosen action per database (skip, replace, or copy to new name)
 - Imports the SQL dump: `mysql -h HOST -P PORT -u USER -pPASS DATABASE < dump.sql`
 
 ## PostgreSQL Backups (pg_dump)
@@ -176,6 +176,119 @@ The restore process:
     -d DATABASE /path/to/dump.dump
   ```
 
+## MongoDB Backups (mongo_dump)
+
+### Requirements
+
+The following tools must be installed on the client machine:
+
+- `mongodump` — included in [MongoDB Database Tools](https://www.mongodb.com/docs/database-tools/)
+- `mongorestore` — included in MongoDB Database Tools
+- `mongosh` (or legacy `mongo` shell) — used for listing databases and connectivity tests
+
+**Install on Ubuntu/Debian:**
+
+```bash
+curl -fsSL https://www.mongodb.org/static/pgp/server-7.0.asc | sudo gpg --dearmor -o /usr/share/keyrings/mongodb-server-7.0.gpg
+echo "deb [signed-by=/usr/share/keyrings/mongodb-server-7.0.gpg] https://repo.mongodb.org/apt/ubuntu $(lsb_release -cs)/mongodb-org/7.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-7.0.list
+sudo apt-get update
+sudo apt-get install -y mongodb-database-tools mongodb-mongosh
+```
+
+### Enabling MongoDB Backups
+
+1. Navigate to the client detail page
+2. Click the **Plugins** tab
+3. Toggle **MongoDB Backup** to enabled
+
+> **Screenshot:** Plugins tab showing MongoDB Backup plugin toggle switch
+
+### Creating a MongoDB Plugin Configuration
+
+1. On the Plugins tab, click **Add Configuration** under MongoDB Backup
+2. Fill in the configuration details:
+   - **Configuration Name**: A descriptive name (e.g., "Production MongoDB")
+   - **Host**: MongoDB host (default: `127.0.0.1` — use this instead of `localhost` to avoid IPv6 issues)
+   - **Port**: MongoDB port (default: `27017`)
+   - **Username**: MongoDB username (leave empty if authentication is not required)
+   - **Password**: MongoDB password (leave empty if authentication is not required)
+   - **Auth Database**: Authentication database (default: `admin`)
+   - **Databases**: Comma-separated database names, or `*` for all
+   - **Exclude Databases**: Databases to skip when using `*` (default: `admin,config,local`)
+   - **Dump Directory**: Local path where dumps will be stored (e.g., `/home/bbs/mongodump`)
+   - **Compress**: Enable gzip compression for dump files (default: enabled)
+   - **Extra Options**: Additional flags passed directly to `mongodump`
+3. Click **Save Configuration**
+
+> **Screenshot:** MongoDB plugin configuration form
+
+### Configuration Fields Explained
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| Host | `127.0.0.1` | MongoDB server hostname or IP |
+| Port | `27017` | MongoDB server port |
+| Username | *(empty)* | MongoDB user. Leave empty if authentication is disabled. |
+| Password | *(empty)* | MongoDB password (encrypted in BBS). |
+| Auth Database | `admin` | The authentication database (only used when username is set). |
+| Databases | `*` | Comma-separated list or `*` for all |
+| Exclude Databases | `admin,config,local` | Skipped when using `*` |
+| Dump Directory | `/home/bbs/mongodump` | Temporary local directory for dump files |
+| Compress | `true` | Adds `--gzip` flag to `mongodump` |
+| Extra Options | *(empty)* | Extra flags passed to `mongodump` |
+
+### Authentication
+
+MongoDB authentication is **optional**. If your MongoDB instance does not require authentication (common in development or localhost-only setups), leave the Username and Password fields empty.
+
+If authentication is enabled, create a backup user:
+
+```javascript
+// Connect with mongosh
+mongosh --host 127.0.0.1
+
+use admin
+db.createUser({
+  user: "bbs_backup",
+  pwd: "your_secure_password",
+  roles: [{ role: "root", db: "admin" }]
+})
+```
+
+### How MongoDB Backups Work
+
+When a backup job runs with a MongoDB plugin attached:
+
+1. The agent connects to MongoDB using `mongosh` to list available databases
+2. System databases in the exclude list are skipped
+3. Before running `borg create`, the agent executes `mongodump` for each database:
+   ```bash
+   mongodump --host=127.0.0.1 --port=27017 --db=mydb --out=/home/bbs/mongodump --gzip
+   ```
+4. Borg backs up the dump directory along with all other specified directories
+5. After the Borg backup completes, the dump directory is cleaned up
+
+### Restoring MongoDB Databases
+
+1. Navigate to client detail → **Restore** tab
+2. Select the database(s) to restore
+3. Select the **Connector** — the MongoDB plugin configuration with the target connection details
+4. Select the **archive** to restore from
+5. For each selected database, choose a restore action:
+   - **None**: Skip this database
+   - **Replace** *(caution)*: Drop existing collections and restore from the dump (`--drop`)
+   - **Copy**: Restore into a new database — set the new database name
+6. Click **Restore Selected Databases**
+
+The restore process:
+- Extracts the dump files from the selected Borg archive (stored in the Dump Directory path within the archive)
+- Connects to the target MongoDB server using the selected connector
+- Applies the chosen action per database (skip, replace with `--drop`, or copy to new name)
+- Restores using `mongorestore`:
+  ```bash
+  mongorestore --host=127.0.0.1 --port=27017 --db=mydb --drop --gzip /home/bbs/mongodump/mydb
+  ```
+
 ## Testing Plugin Configurations
 
 Before running your first backup, test your database plugin configuration:
@@ -221,6 +334,14 @@ Common test failure reasons:
 - The custom format (`-Fc`) provides compression and selective restore capabilities
 - Ensure `pg_dump` and `pg_restore` are installed on the client machine
 
+### For MongoDB Backups
+
+- Use `127.0.0.1` as the host (not `localhost`) to avoid IPv6 resolution issues
+- Create a dedicated backup user with the `root` role (or a minimal role sufficient for `mongodump`)
+- Enable compression to reduce dump size and backup transfer time
+- Ensure `mongodb-database-tools` and `mongosh` are installed on the client machine
+- The dump directory is temporary and is cleaned up after each backup — do not use it as a permanent storage path
+
 ### General Best Practices
 
 - **Named Configurations**: Create reusable named configs for each database server. Share configs across multiple backup plans.
@@ -252,6 +373,16 @@ Common test failure reasons:
 | permission denied | Grant SELECT on all tables in schema to backup user |
 | pg_dump: command not found | Install postgresql-client package on the agent machine |
 
+### MongoDB Issues
+
+| Problem | Solution |
+|---------|----------|
+| Connection refused on localhost | Use `127.0.0.1` instead of `localhost` to avoid IPv6 resolution issues |
+| Authentication failed | Verify credentials with `mongosh --host 127.0.0.1 -u user -p pass --authenticationDatabase admin` |
+| mongodump: command not found | Install `mongodb-database-tools` (separate package since MongoDB 4.4) |
+| mongosh: command not found | Install `mongodb-mongosh` on the client machine |
+| Dump directory not writable | Create the directory and ensure the agent user has write access |
+
 ### Restore Issues
 
 | Problem | Solution |
diff --git a/Plugins.md b/Plugins.md
index 9157252..1c62faf 100644
--- a/Plugins.md
+++ b/Plugins.md
@@ -6,7 +6,7 @@ BBS plugins extend backup functionality by adding pre-backup actions, post-backu
 
 The BBS plugin architecture consists of:
 
-- **Plugin Types**: Built-in plugins provided by BBS (MySQL, PostgreSQL, Shell Hook, S3 Sync)
+- **Plugin Types**: Built-in plugins provided by BBS (MySQL, PostgreSQL, MongoDB, Shell Hook, S3 Sync)
 - **Plugin Configurations**: Named, reusable configurations for each plugin type
 - **Backup Plan Association**: Plugins are attached to backup plans, not directly to clients
 - **Per-Client Enablement**: Each plugin must be enabled on a per-client basis before use
@@ -210,6 +210,48 @@ See [[S3-Offsite-Sync]] for detailed S3 sync documentation.
 
 ---
 
+### 5. MongoDB Backup (mongo_dump)
+
+**Purpose**: Automatically dump MongoDB databases before backup
+
+**Use Cases**:
+- Node.js and MEAN stack application databases
+- Content management platforms backed by MongoDB
+- Analytics and event data stores
+- Custom MongoDB applications
+
+**Requirements** (must be installed on the client machine):
+- `mongodump` — included in [MongoDB Database Tools](https://www.mongodb.com/docs/database-tools/)
+- `mongorestore` — included in MongoDB Database Tools
+- `mongosh` (or legacy `mongo` shell) — used for listing databases and connectivity tests
+
+**How It Works**:
+- Connects to MongoDB using `mongosh` to enumerate available databases
+- Executes `mongodump` for each selected database before Borg runs
+- Creates dump files in a specified dump directory (optionally gzip-compressed)
+- Borg includes the dump files in the backup archive
+- After the Borg backup completes, the dump directory is cleaned up
+- Enables one-click MongoDB restoration from the BBS web interface
+
+**Configuration Parameters**:
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| Host | `127.0.0.1` | MongoDB host. Use `127.0.0.1` instead of `localhost` to avoid IPv6 issues. |
+| Port | `27017` | MongoDB port. |
+| Username | *(empty)* | MongoDB username. Leave empty if authentication is not enabled. |
+| Password | *(empty)* | MongoDB password. Leave empty if authentication is not enabled. |
+| Auth Database | `admin` | Authentication database (only used when username is set). |
+| Databases | `*` | Comma-separated list of databases, or `*` for all. |
+| Exclude Databases | `admin,config,local` | Databases to skip when using `*`. |
+| Dump Directory | `/home/bbs/mongodump` | Temporary directory for dump files (cleaned up after backup). |
+| Compress | `true` | Use `--gzip` for compressed dumps. |
+| Extra Options | *(empty)* | Additional flags passed to `mongodump`. |
+
+See [[Database-Backups]] for detailed MongoDB backup documentation.
+
+---
+
 ## Enabling Plugins
 
 Plugins must be enabled on a per-client basis before they can be used:
@@ -266,6 +308,7 @@ Plugins are activated by attaching their configurations to backup plans:
 4. Select plugin configurations from the dropdowns:
    - **MySQL Backup**: Choose a MySQL config (if enabled)
    - **PostgreSQL Backup**: Choose a PostgreSQL config (if enabled)
+   - **MongoDB Backup**: Choose a MongoDB config (if enabled)
    - **Shell Hook**: Choose a shell hook config (if enabled)
    - **S3 Sync**: Choose an S3 config (if enabled)
 5. Save the backup plan
@@ -285,6 +328,7 @@ A single backup plan can use multiple plugins simultaneously:
    - Shell hook pre-backup script
    - MySQL dump
    - PostgreSQL dump
+   - MongoDB dump
 2. **Backup phase**:
    - `borg create` runs
 3. **Post-backup phase**:
@@ -308,7 +352,7 @@ Before running a production backup, test your plugin configurations:
 
 ### What Testing Does
 
-- **MySQL/PostgreSQL**: Connects to database, performs a test dump, verifies dump files created
+- **MySQL/PostgreSQL/MongoDB**: Connects to database, performs a test dump, verifies dump files created
 - **Shell Hook**: Executes the scripts in a test environment, captures output and exit codes
 - **S3 Sync**: Tests S3 credentials, attempts to create a test file in the bucket
 
@@ -321,6 +365,9 @@ Before running a production backup, test your plugin configurations:
 | PostgreSQL | authentication failed | Check credentials, review pg_hba.conf |
 | Shell Hook | Script not found | Verify path is absolute and file exists on client |
 | Shell Hook | Permission denied | Make script executable, check file permissions |
+| MongoDB | Connection refused | Use `127.0.0.1` instead of `localhost`; verify MongoDB is running |
+| MongoDB | Authentication failed | Check credentials and auth database name |
+| MongoDB | mongodump not found | Install `mongodb-database-tools` on the client machine |
 | S3 Sync | Invalid credentials | Verify access key and secret key |
 | S3 Sync | Bucket not found | Check bucket name, ensure it exists |
 
@@ -334,6 +381,7 @@ Plugins create jobs that appear in the Queue:
 | `plugin_test` | Test a plugin configuration | Manual test button |
 | `restore_mysql` | Restore MySQL databases from archive | Manual restore |
 | `restore_pg` | Restore PostgreSQL databases from archive | Manual restore |
+| `restore_mongo` | Restore MongoDB databases from archive | Manual restore |
 | `s3_sync` | Sync repository to S3 | After successful prune |
 
 ## Plugin Security
@@ -410,7 +458,7 @@ Plugins create jobs that appear in the Queue:
 
 ## Related Documentation
 
-- [[Database-Backups]] — Detailed MySQL and PostgreSQL backup guide
+- [[Database-Backups]] — Detailed MySQL, PostgreSQL, and MongoDB backup guide
 - [[S3-Offsite-Sync]] — Comprehensive S3 sync documentation
 - [[Queue-and-Jobs]] — Monitoring plugin job execution
 - [[Troubleshooting]] — General BBS troubleshooting
-- 
2.53.0