nodebb-plugin-cloudflare-r2 (env)

Upload provider for NodeBB v4.x that stores uploads in Cloudflare R2 (S3-compatible).

This build is env-first (no ACP settings page). Configure using environment variables.

Environment variables

Required:

• NODEBB_R2_ACCESS_KEY_ID
• NODEBB_R2_SECRET_ACCESS_KEY
• NODEBB_R2_BUCKET
• NODEBB_R2_ENDPOINT (example: https://<ACCOUNT_ID>.r2.cloudflarestorage.com)

Optional:

• NODEBB_R2_REGION (default: auto)
• NODEBB_R2_UPLOAD_PATH (default: empty)
• NODEBB_R2_HOST (public base URL returned to NodeBB; default: https://<bucket>)
• NODEBB_R2_FORCE_PATH_STYLE (true|false, default: false)

Notes:

• endpoint is the S3 API endpoint (cloudflarestorage.com)
• host is the public URL base (custom domain / CDN / public bucket URL)

Install

cd /path/to/nodebb
npm i /path/to/nodebb-plugin-cloudflare-r2
./nodebb build
./nodebb restart

Enable plugin in ACP → Extend → Plugins.

Docker Compose example

environment:
  NODEBB_R2_ACCESS_KEY_ID: "xxx"
  NODEBB_R2_SECRET_ACCESS_KEY: "yyy"
  NODEBB_R2_BUCKET: "my-bucket"
  NODEBB_R2_ENDPOINT: "https://<ACCOUNT_ID>.r2.cloudflarestorage.com"
  NODEBB_R2_REGION: "auto"
  NODEBB_R2_UPLOAD_PATH: "uploads"
  NODEBB_R2_HOST: "https://cdn.example.com"
  NODEBB_R2_FORCE_PATH_STYLE: "false"

What it does

• Hooks: filter:uploadImage, filter:uploadFile
• Validates extensions using the original filename (fixes drag&drop tmp-path issues)
• Streams uploads to R2 (does not read entire file into RAM)

Deleting objects when posts are deleted

By default, the plugin deletes objects only when a post is purged (permanent deletion). This avoids breaking restored posts.

If you really want to delete objects on normal (soft) delete too, set:

• NODEBB_R2_DELETE_ON_SOFT_DELETE=true

Cleaning up objects on topic purge/delete and post edit

• When a topic is purged (permanently deleted), the plugin will delete all R2 objects referenced by posts in that topic.
• When a post is edited, the plugin will delete R2 objects that were referenced before the edit but are not referenced anymore after the edit (best-effort).

Soft delete is not permanent in NodeBB, so object deletion is disabled by default.

To also delete objects on soft topic delete, set:

• NODEBB_R2_DELETE_ON_TOPIC_SOFT_DELETE=true

(For soft post delete, see NODEBB_R2_DELETE_ON_SOFT_DELETE.)

Cleaning up avatars (profile pictures)

When a user changes their avatar/profile picture, the plugin will attempt to delete the previously referenced R2 object (only if the old URL points to your NODEBB_R2_HOST/NODEBB_R2_UPLOAD_PATH). This is best-effort.

Multi-instance / cluster reliability

In multi-instance deployments, cleanup on post edit and avatar changes uses the shared NodeBB database to store a short-lived "before" snapshot (TTL). This keeps cleanup reliable even when different instances handle the before/after hooks.