How to Use Cloudflare R2 with Flarum FoF Upload Extension: A Step-by-Step Guide

Offloading your Flarum forum's file uploads to a dedicated object storage service is a crucial step for scaling your community. It reduces server load, improves performance, and provides a more robust storage solution. Cloudflare R2, with its S3-compatible API and zero egress fees, presents a compelling and cost-effective option.

This guide provides a complete walkthrough for configuring the FriendsOfFlarum (FoF) Upload extension to use Cloudflare R2 for all file storage needs.

Prerequisites

• A running Flarum installation with administrative access.
• Shell (SSH) access to the server hosting Flarum.
• An active Cloudflare account managing your forum's domain.

Part 1: Provisioning Your Cloudflare R2 Bucket

Our first objective is to create and configure the R2 bucket that will serve as the storage repository.

Step 1: Create the R2 Bucket

1. Log into the Cloudflare dashboard and navigate to R2 from the main menu.
2. Select Create bucket.
3. Assign a unique name to your bucket (e.g., yourforum-assets). The name must be unique within the R2 ecosystem.
4. Choose a location or leave the default setting.
5. Click Create bucket to finalize.

Step 2: Generate R2 API Credentials

FoF Upload requires S3-compatible credentials to authenticate with your R2 bucket.

1. From the R2 overview page in your Cloudflare dashboard, select Manage API Tokens.
2. Click Create API Token.
3. Under Permissions, select Object Read & Write. This grants the necessary permissions for the extension to upload, read, and manage files without providing excessive administrative access.
4. Optionally, you can scope the token's access to the specific bucket created in the previous step for improved security.
5. Select Create API Token.
6. You will be presented with an Access Key ID and a Secret Access Key. It is critical to copy and store these credentials in a secure location, such as a password manager. The Secret Access Key is only displayed once and cannot be retrieved later.

Step 3: Identify Your S3 Endpoint

The endpoint is the specific URL that the FoF Upload extension will use to communicate with the R2 API.

1. Return to the main R2 overview page.
2. Locate and copy your Account ID from the panel on the right.
3. The S3 API Endpoint follows this structure: https://<ACCOUNT_ID>.r2.cloudflarestorage.com. Substitute <ACCOUNT_ID> with your copied value. (e.g., https://823552dfd4ac42d2d5682Dc22e1d5b9f.r2.cloudflarestorage.com).

Part 2: (Recommended) Configure a Custom Domain for Public Access

For optimal performance and branding, it is best practice to serve files from a custom subdomain rather than the default R2 development URL. This enables you to leverage Cloudflare's CDN and caching capabilities.

1. Within the R2 dashboard, select your bucket by name.
2. Navigate to the Settings tab.
3. Under the Custom Domains section, click Connect Domain.
4. Enter the subdomain you wish to use (e.g., assets.yourforum.com) and proceed.
5. Cloudflare will automatically provision the required CNAME record in your zone's DNS. Confirm the action to connect the domain.
6. The domain's status will change from "Initializing" to "Active" after a few moments. This subdomain will serve as the Content Delivery URL.

Part 3: Configuring the FoF Upload Extension in Flarum

With the Cloudflare R2 infrastructure in place, we can now configure Flarum.

Step 1: Install Required Composer Packages

Connect to your server via SSH, navigate to your Flarum project root, and execute the following commands to ensure both FoF Upload and its S3 dependency are installed.

composer require fof/upload:"*" && composer require league/flysystem-aws-s3-v3 "1.*"

After the packages are installed, clear the Flarum cache to apply the changes.

php flarum cache:clear

Step 2: Configure the Storage Adapter

1. Log in to your Flarum admin dashboard.
2. Enable the FoF Upload extension if it is not already active.
3. Navigate to the FoF Upload settings page from the sidebar.

Step 3: Map Mime Types to the S3 Adapter

In this step, you will instruct FoF Upload to direct specific file types to your R2 bucket.

1. Locate the Configure your mime type, upload adapter mapping section.
2. For image uploads, the default regex is appropriate: ^image\/(jpeg|png|gif|webp|avif|bmp|tiff|svg\+xml)$
3. In the first dropdown menu, select S3 or Compatible.
4. In the second dropdown, choose a download template. Complete image preview template is recommended for images as it renders them directly in posts.

Step 4: Input S3 Connection Details

Scroll down to the AWS S3 storage settings and populate the fields with the credentials and information gathered from Part 1.

• Key: Your R2 Access Key ID.
• Secret: Your R2 Secret Access Key.
• Bucket: The name of your R2 bucket (e.g., flectar).
• Region: Enter auto (weur...). This specific value is required for Cloudflare R2's S3 compatibility layer.

Next, the Advanced S3 storage settings.

• Endpoint: Enter the full S3 API Endpoint URL from Part 1, Step 3.

If you configured a custom domain in Part 2, add it now.

• Content Delivery URL (prefixes files): Enter the full URL of your custom domain, ensuring it includes the trailing slash (e.g., https://cdn.flectar.com/).

Step 5: Save and Test

1. Click Save Changes at the bottom of the page.
2. Navigate to your forum and attempt to upload a file in a new discussion.
3. After the post is submitted, inspect the image's URL. It should resolve to your configured Content Delivery URL (e.g., https://cdn.flectar.com/...), confirming that the file is being served from Cloudflare R2.

Conclusion

By completing this configuration, you have successfully integrated Cloudflare R2 as the storage backend for your Flarum forum. This setup provides a highly scalable, performant, and cost-effective solution for managing user-generated content, allowing your community to grow without the constraints of local server storage.