@trieb.work/payload-plugin-backup-mongodb 0.1.7 → 0.2.0

package/README.md

@@ -9,9 +9,10 @@
 
 A **Payload CMS v3** plugin for **MongoDB only** — not Postgres, SQLite, or
 other database adapters. It handles Mongo + media backup, restore, and scheduled
-retention with zero meta-database and a built-in admin UI. Backups live directly
-in Vercel Blob Storage, so a fresh install can list and restore any prior backup
-without bootstrapping a database first.
+retention with zero meta-database and a built-in admin UI. Backups live in
+**Vercel Blob Storage** (default) or **AWS S3 / S3-compatible stores** (R2,
+MinIO, etc.), so a fresh install can list and restore any prior backup without
+bootstrapping a database first.
 
 ![Backup dashboard embedded in the Payload admin panel](./docs/screenshots/dashboard.png)
 
@@ -51,15 +52,13 @@ originated at
   you do not add `app/.../route.ts` files for this plugin.
 - **Pluggable blob storage.** Uses `BLOB_READ_WRITE_TOKEN` by default (the same
   store you often use with `@payloadcms/storage-vercel-blob`), or point backups
-  at a dedicated Vercel Blob store in the admin. Both **public** and **private**
-  access stores are supported; a validation step detects which modes the store
-  accepts.
-- **Resumable long-running tasks.** Manual backups, restores, and seed runs are
-  tracked in a hidden `backup-tasks` collection (TTL, 30 min). The UI polls
-  progress with a short-lived `pollSecret` so long jobs stay observable even
-  across reloads.
-- **Demo/seed support.** Optional `seedDemoDumpUrl` registers a one-click seed
-  endpoint for templates and starters.
+  at a dedicated Vercel Blob store in the admin. Alternatively set
+  `BACKUP_STORAGE=s3` and use AWS S3, Cloudflare R2, MinIO, etc. Both **public**
+  and **private** access stores are supported; a validation step detects which
+  modes the store accepts.
+- **Resumable long-running tasks.** Manual backups and restores are tracked in a
+  hidden `backup-tasks` collection (TTL, 30 min). The UI polls progress with a
+  short-lived `pollSecret` so long jobs stay observable even across reloads.
 - **Tested.** Vitest covers archive, backup, restore, task progress, blob I/O,
   endpoint auth, cron parsing, and blob-name helpers.
 
@@ -67,30 +66,107 @@ originated at
 
 ## Requirements
 
+- **Node.js 20.9+** (Node 18 is no longer supported).
 - Payload **v3+** (same major as your other `@payloadcms/*` packages).
 - MongoDB with Payload’s mongoose adapter (`@payloadcms/db-mongodb`).
 - MongoDB server (any version supported by that adapter).
-- A Vercel Blob read/write token (`BLOB_READ_WRITE_TOKEN`). Vercel hosting is
-  **not** required — any Node runtime that can reach Vercel Blob works.
+- A backup target:
+  - **Vercel Blob:** `BLOB_READ_WRITE_TOKEN` (the default target). Vercel
+    hosting is **not** required — any Node runtime that can reach Vercel Blob
+    works.
+  - **S3:** `BACKUP_STORAGE=s3` plus `BACKUP_S3_BUCKET` (and optionally
+    credentials). Requires Node 20+ for the optional AWS SDK peer packages. See
+    [Choosing a backup target](#choosing-a-backup-target-vercel-blob-or-s3).
 - Next.js **15+** and React **19+** (the usual Payload 3 + App Router stack).
 
 ### Environment variables
 
-| Variable                       | Required | Purpose                                                                                                                                                                                                                                                                                                                |
-| ------------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `MONGODB_URI`                  | yes      | MongoDB connection string (used by Payload and to label backups with the DB name).                                                                                                                                                                                                                                     |
-| `BLOB_READ_WRITE_TOKEN`        | yes      | Default Vercel Blob store for backups and media. Can be overridden in admin settings.                                                                                                                                                                                                                                  |
-| `CRON_SECRET`                  | for cron | Bearer token for every `/api/backup-mongodb/cron/*` call. Vercel Cron can supply this.                                                                                                                                                                                                                                 |
-| `NEXT_PUBLIC_SERVER_URL`       | optional | Used to label backups with the current host. Falls back to `VERCEL_URL` when set.                                                                                                                                                                                                                                      |
-| `BACKUPS_TO_KEEP`              | optional | Default retention for cron backups if the settings document has not been edited. Default `10`.                                                                                                                                                                                                                         |
-| `PAYLOAD_BACKUP_ALLOWED_ROLES` | optional | Comma-separated role slugs that may see the **Backups** dashboard (case-insensitive). Use `*` to allow any authenticated user. When unset, the plugin falls back to requiring a `role` with slug `admin`, or allows everyone when the users collection has no `roles` field. Overridden by the `access` plugin option. |
+| Variable                       | Required        | Purpose                                                                                                                                                                                                                                                                                                                |
+| ------------------------------ | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `MONGODB_URI`                  | yes             | MongoDB connection string (used by Payload and to label backups with the DB name).                                                                                                                                                                                                                                     |
+| `BACKUP_STORAGE`               | optional        | Backup target: `vercel-blob` (default) or `s3`. See [Choosing a backup target](#choosing-a-backup-target-vercel-blob-or-s3).                                                                                                                                                                                           |
+| `BLOB_READ_WRITE_TOKEN`        | for Vercel Blob | Default Vercel Blob store for backups and media. Required when `BACKUP_STORAGE=vercel-blob` (the default). Can be overridden in admin settings.                                                                                                                                                                        |
+| `CRON_SECRET`                  | for cron        | Bearer token for every `/api/backup-mongodb/cron/*` call. Vercel Cron can supply this.                                                                                                                                                                                                                                 |
+| `NEXT_PUBLIC_SERVER_URL`       | optional        | Used to label backups with the current host. Falls back to `VERCEL_URL` when set.                                                                                                                                                                                                                                      |
+| `BACKUPS_TO_KEEP`              | optional        | Default retention for cron backups if the settings document has not been edited. Default `10`.                                                                                                                                                                                                                         |
+| `PAYLOAD_BACKUP_ALLOWED_ROLES` | optional        | Comma-separated role slugs that may see the **Backups** dashboard (case-insensitive). Use `*` to allow any authenticated user. When unset, the plugin falls back to requiring a `role` with slug `admin`, or allows everyone when the users collection has no `roles` field. Overridden by the `access` plugin option. |
+
+---
+
+## Choosing a backup target (Vercel Blob or S3)
+
+Backups can be stored in **Vercel Blob** (default) or **AWS S3**. The S3 target
+also works with any S3-compatible store — **Cloudflare R2**, **MinIO**, etc. —
+because they share the same API; only the configuration differs, never the
+plugin code.
+
+Select the target with `BACKUP_STORAGE`. When unset it stays `vercel-blob`, so
+existing deployments are unaffected.
+
+### Using S3
+
+S3 is enabled when `BACKUP_STORAGE=s3`. Install the AWS SDK (declared as
+optional peer dependencies, so Vercel-only installs don't pull it in):
+
+```bash
+pnpm add @aws-sdk/client-s3 @aws-sdk/lib-storage @aws-sdk/s3-request-presigner
+```
+
+| Variable                      | Required | Purpose                                                                                                               |
+| ----------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
+| `BACKUP_STORAGE`              | yes      | Set to `s3`.                                                                                                          |
+| `BACKUP_S3_BUCKET`            | yes      | Target bucket name.                                                                                                   |
+| `BACKUP_S3_REGION`            | optional | Region. Falls back to `AWS_REGION`, then `us-east-1`.                                                                 |
+| `BACKUP_S3_ENDPOINT`          | optional | Custom endpoint for S3-compatible stores (R2, MinIO). Omit for AWS S3.                                                |
+| `BACKUP_S3_FORCE_PATH_STYLE`  | optional | Path-style addressing. Defaults to `true` when an endpoint is set (needed for MinIO and some R2 setups).              |
+| `BACKUP_S3_PREFIX`            | optional | Key namespace prepended to every object (for sharing a bucket). Backups still list/restore by their `backups/…` name. |
+| `BACKUP_S3_ACCESS_KEY_ID`     | optional | Access key. Falls back to `AWS_ACCESS_KEY_ID`. Omit to use the AWS default credential chain (IAM roles, etc.).        |
+| `BACKUP_S3_SECRET_ACCESS_KEY` | optional | Secret key. Falls back to `AWS_SECRET_ACCESS_KEY`.                                                                    |
+| `BACKUP_S3_SESSION_TOKEN`     | optional | Session token for temporary credentials. Falls back to `AWS_SESSION_TOKEN`.                                           |
+
+Credentials are optional: when omitted, the AWS SDK's default provider chain is
+used (environment, shared config, or instance/role credentials — recommended on
+AWS).
+
+**AWS S3**
+
+```bash
+BACKUP_STORAGE=s3
+BACKUP_S3_BUCKET=my-payload-backups
+BACKUP_S3_REGION=eu-central-1
+# Credentials via IAM role (recommended) or:
+# BACKUP_S3_ACCESS_KEY_ID=...
+# BACKUP_S3_SECRET_ACCESS_KEY=...
+```
+
+**Cloudflare R2**
+
+```bash
+BACKUP_STORAGE=s3
+BACKUP_S3_BUCKET=my-payload-backups
+BACKUP_S3_REGION=auto
+BACKUP_S3_ENDPOINT=https://<account-id>.r2.cloudflarestorage.com
+BACKUP_S3_FORCE_PATH_STYLE=true
+BACKUP_S3_ACCESS_KEY_ID=<r2-access-key-id>
+BACKUP_S3_SECRET_ACCESS_KEY=<r2-secret-access-key>
+```
+
+Backups are stored under the same `backups/…` keys (see
+[Blob naming](#blob-naming)), so listing and restore work identically across
+targets. Downloads stream through the plugin's authenticated endpoint, so the
+bucket does **not** need to be public.
+
+> **Note on media:** the "include media" option bundles files from your Payload
+> **Vercel Blob upload store** (`BLOB_READ_WRITE_TOKEN`). The configurable
+> target above governs where backup **archives** live only; media is always read
+> from and restored to the upload store, even when `BACKUP_STORAGE=s3`.
 
 ---
 
 ## Installation and getting started
 
 Use this flow when **adding the plugin to an existing Payload 3 + Next.js app**
-that already has MongoDB and (typically) Vercel Blob configured.
+that already has MongoDB and a blob/S3 store configured.
 
 ### 1. Add the package
 
@@ -219,8 +295,10 @@ Retention, storage token, and cron collection skip list live in one modal:
 - **Retention:** how many **cron** archives to keep; manual backups are not
   pruned by this.
 - **Dedicated backup storage (optional):** a separate Vercel Blob read/write
-  token so backups can live in a different store than media. The UI can validate
-  the token and optionally copy existing `backups/*` objects to the new store.
+  token (when `BACKUP_STORAGE=vercel-blob`) so backups can live in a different
+  store than media. The UI can validate the token and optionally copy existing
+  `backups/*` objects to the new store. For S3, configure the target bucket via
+  environment variables.
 - **Collection selection for cron:** defaults to all collections, with
   per-collection opt-out.
 
@@ -239,12 +317,6 @@ type BackupPluginOptions = {
   /** Default cron retention when no value is stored in settings. Falls back to `BACKUPS_TO_KEEP` or `10`. */
   backupsToKeep?: number
 
-  /**
-   * If set, registers `POST /api/backup-mongodb/admin/seed` (demo dump + public seed media where applicable).
-   * Omit in production unless you need it.
-   */
-  seedDemoDumpUrl?: string
-
   /**
    * Custom access check for admin routes and the dashboard. Overrides the
    * `PAYLOAD_BACKUP_ALLOWED_ROLES` env var when provided.
@@ -258,19 +330,6 @@ type BackupPluginOptions = {
 }
 ```
 
-Example with custom access and seed URL (typical for starters):
-
-```ts
-backupMongodbPlugin({
-  access: (user) =>
-    Array.isArray((user as { roles?: { slug?: string }[] })?.roles) &&
-    (user as { roles: { slug?: string }[] }).roles.some(
-      (r) => r?.slug === 'admin' || r?.slug === 'superadmin',
-    ),
-  seedDemoDumpUrl: 'https://example.com/seed/demo-db.json',
-})
-```
-
 ---
 
 ## HTTP API (Payload REST)
@@ -291,18 +350,17 @@ Authorization: Bearer <CRON_SECRET>
 
 ### Admin (session cookie, or `pollSecret` for `/task/:id` where applicable)
 
-| Method         | Path                                                           |
-| -------------- | -------------------------------------------------------------- |
-| `POST`         | `/api/backup-mongodb/admin/manual`                             |
-| `POST`         | `/api/backup-mongodb/admin/restore`                            |
-| `POST`         | `/api/backup-mongodb/admin/backup-preview`                     |
-| `POST`         | `/api/backup-mongodb/admin/restore-preview`                    |
-| `POST`         | `/api/backup-mongodb/admin/delete`                             |
-| `GET`          | `/api/backup-mongodb/admin/backup-download`                    |
-| `GET`          | `/api/backup-mongodb/admin/task/:id`                           |
-| `GET` / `POST` | `/api/backup-mongodb/admin/settings`                           |
-| `POST`         | `/api/backup-mongodb/admin/validate-blob-token`                |
-| `POST`         | `/api/backup-mongodb/admin/seed` — if `seedDemoDumpUrl` is set |
+| Method         | Path                                            |
+| -------------- | ----------------------------------------------- |
+| `POST`         | `/api/backup-mongodb/admin/manual`              |
+| `POST`         | `/api/backup-mongodb/admin/restore`             |
+| `POST`         | `/api/backup-mongodb/admin/backup-preview`      |
+| `POST`         | `/api/backup-mongodb/admin/restore-preview`     |
+| `POST`         | `/api/backup-mongodb/admin/delete`              |
+| `GET`          | `/api/backup-mongodb/admin/backup-download`     |
+| `GET`          | `/api/backup-mongodb/admin/task/:id`            |
+| `GET` / `POST` | `/api/backup-mongodb/admin/settings`            |
+| `POST`         | `/api/backup-mongodb/admin/validate-blob-token` |
 
 ---
 
@@ -353,10 +411,18 @@ flows handle both.
 
 ### Overriding the backup store
 
-To keep backups in a **different** Vercel Blob project than media, open **Backup
-settings** in the admin, paste a dedicated `BLOB_READ_WRITE_TOKEN`, validate,
-and optionally migrate existing `backups/*` objects to the new store before
-switching.
+To keep backups in a **different** Vercel Blob project than media (when
+`BACKUP_STORAGE=vercel-blob`), open **Backup settings** in the admin, paste a
+dedicated `BLOB_READ_WRITE_TOKEN`, validate, and optionally migrate existing
+`backups/*` objects to the new store before switching. For S3, the target is
+controlled entirely by environment variables.
+
+### Removed demo seed API (intentional)
+
+Earlier releases exposed an optional demo seed route (`seedDemoDumpUrl`,
+`/backup-mongodb/admin/seed`, and the `restoreSeedMedia` export). That was
+removed on purpose: a backup plugin should not ship a public “seed my database”
+API. Use your own migration/seed tooling instead.
 
 ---
 
@@ -407,8 +473,10 @@ workflow opens a “version packages” PR or runs `pnpm run release` (`build` +
 ## Roadmap / ideas
 
 - Multipart / very large backup uploads (Vercel Blob supports large objects; may
-  need to switch past single-part limits).
-- Additional storage adapters (S3, R2, filesystem, etc.).
+  need to switch past single-part limits). _(S3 uploads already use multipart.)_
+- Additional storage adapters (filesystem, etc.). _(AWS S3 and S3-compatible
+  stores such as R2/MinIO are supported — see
+  [Choosing a backup target](#choosing-a-backup-target-vercel-blob-or-s3).)_
 - Scheduler-agnostic display when not using Vercel (`vercel.json` is currently
   used for the schedule summary where available).
 - Streaming restore for very large databases.

package/dist/backup-dashboard.css

@@ -595,14 +595,31 @@
 .backup-task-status-slot {
   display: flex;
   flex-direction: row;
-  align-items: center;
+  align-items: flex-start;
   gap: 6px;
 }
+.backup-task-status-slot .backup-task-status__details {
+  display: flex;
+  flex-direction: column;
+  gap: 3px;
+  min-width: 0;
+}
 .backup-task-status-slot .backup-task-status__message {
   font-size: 12px;
   line-height: 1.4;
   color: var(--theme-elevation-700);
 }
+.backup-task-status-slot .backup-task-status__warnings {
+  font-size: 12px;
+  line-height: 1.4;
+  color: var(--theme-warning-600, #b7791f);
+  white-space: pre-wrap;
+}
+.backup-task-status-slot .backup-task-status__error {
+  font-size: 12px;
+  line-height: 1.4;
+  color: var(--theme-error-500, #c0392b);
+}
 
 .restore-preview__blob-token-row {
   display: flex;

package/dist/collections/BackupTasks.js

@@ -16,7 +16,6 @@ export const BackupTasksCollection = {
             options: [
                 'backup',
                 'restore',
-                'seed',
                 'delete',
                 'blobTransfer'
             ],
@@ -29,6 +28,7 @@ export const BackupTasksCollection = {
                 'queued',
                 'running',
                 'completed',
+                'completed_with_warnings',
                 'failed'
             ],
             required: true
@@ -42,6 +42,13 @@ export const BackupTasksCollection = {
             name: 'error',
             type: 'text'
         },
+        {
+            name: 'warnings',
+            type: 'textarea',
+            admin: {
+                hidden: true
+            }
+        },
         {
             name: 'pollSecret',
             type: 'text',

package/dist/collections/BackupTasks.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/collections/BackupTasks.ts"],"sourcesContent":["import type { CollectionConfig } from 'payload'\n\nexport const BackupTasksCollection: CollectionConfig = {\n  slug: 'backup-tasks',\n  access: {\n    create: () => false,\n    delete: () => false,\n    read: () => false,\n    update: () => false,\n  },\n  admin: {\n    hidden: true,\n  },\n  fields: [\n    {\n      name: 'kind',\n      type: 'select',\n      options: ['backup', 'restore', 'seed', 'delete', 'blobTransfer'],\n      required: true,\n    },\n    {\n      name: 'status',\n      type: 'select',\n      options: ['queued', 'running', 'completed', 'failed'],\n      required: true,\n    },\n    {\n      name: 'message',\n      type: 'text',\n      required: true,\n    },\n    {\n      name: 'error',\n      type: 'text',\n    },\n    {\n      name: 'pollSecret',\n      type: 'text',\n      admin: {\n        hidden: true,\n      },\n    },\n  ],\n  timestamps: true,\n}\n"],"names":["BackupTasksCollection","slug","access","create","delete","read","update","admin","hidden","fields","name","type","options","required","timestamps"],"mappings":"AAEA,OAAO,MAAMA,wBAA0C;IACrDC,MAAM;IACNC,QAAQ;QACNC,QAAQ,IAAM;QACdC,QAAQ,IAAM;QACdC,MAAM,IAAM;QACZC,QAAQ,IAAM;IAChB;IACAC,OAAO;QACLC,QAAQ;IACV;IACAC,QAAQ;QACN;YACEC,MAAM;YACNC,MAAM;YACNC,SAAS;gBAAC;gBAAU;gBAAW;gBAAQ;gBAAU;aAAe;YAChEC,UAAU;QACZ;QACA;YACEH,MAAM;YACNC,MAAM;YACNC,SAAS;gBAAC;gBAAU;gBAAW;gBAAa;aAAS;YACrDC,UAAU;QACZ;QACA;YACEH,MAAM;YACNC,MAAM;YACNE,UAAU;QACZ;QACA;YACEH,MAAM;YACNC,MAAM;QACR;QACA;YACED,MAAM;YACNC,MAAM;YACNJ,OAAO;gBACLC,QAAQ;YACV;QACF;KACD;IACDM,YAAY;AACd,EAAC"}
+{"version":3,"sources":["../../src/collections/BackupTasks.ts"],"sourcesContent":["import type { CollectionConfig } from 'payload'\n\nexport const BackupTasksCollection: CollectionConfig = {\n  slug: 'backup-tasks',\n  access: {\n    create: () => false,\n    delete: () => false,\n    read: () => false,\n    update: () => false,\n  },\n  admin: {\n    hidden: true,\n  },\n  fields: [\n    {\n      name: 'kind',\n      type: 'select',\n      options: ['backup', 'restore', 'delete', 'blobTransfer'],\n      required: true,\n    },\n    {\n      name: 'status',\n      type: 'select',\n      options: ['queued', 'running', 'completed', 'completed_with_warnings', 'failed'],\n      required: true,\n    },\n    {\n      name: 'message',\n      type: 'text',\n      required: true,\n    },\n    {\n      name: 'error',\n      type: 'text',\n    },\n    {\n      name: 'warnings',\n      type: 'textarea',\n      admin: {\n        hidden: true,\n      },\n    },\n    {\n      name: 'pollSecret',\n      type: 'text',\n      admin: {\n        hidden: true,\n      },\n    },\n  ],\n  timestamps: true,\n}\n"],"names":["BackupTasksCollection","slug","access","create","delete","read","update","admin","hidden","fields","name","type","options","required","timestamps"],"mappings":"AAEA,OAAO,MAAMA,wBAA0C;IACrDC,MAAM;IACNC,QAAQ;QACNC,QAAQ,IAAM;QACdC,QAAQ,IAAM;QACdC,MAAM,IAAM;QACZC,QAAQ,IAAM;IAChB;IACAC,OAAO;QACLC,QAAQ;IACV;IACAC,QAAQ;QACN;YACEC,MAAM;YACNC,MAAM;YACNC,SAAS;gBAAC;gBAAU;gBAAW;gBAAU;aAAe;YACxDC,UAAU;QACZ;QACA;YACEH,MAAM;YACNC,MAAM;YACNC,SAAS;gBAAC;gBAAU;gBAAW;gBAAa;gBAA2B;aAAS;YAChFC,UAAU;QACZ;QACA;YACEH,MAAM;YACNC,MAAM;YACNE,UAAU;QACZ;QACA;YACEH,MAAM;YACNC,MAAM;QACR;QACA;YACED,MAAM;YACNC,MAAM;YACNJ,OAAO;gBACLC,QAAQ;YACV;QACF;QACA;YACEE,MAAM;YACNC,MAAM;YACNJ,OAAO;gBACLC,QAAQ;YACV;QACF;KACD;IACDM,YAAY;AACd,EAAC"}