Cómo usar Cloudflare R2 con la extensión FoF Upload de Flarum: Guía paso a paso

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.

Esta guía ofrece un recorrido completo para configurar la extensión FriendsOfFlarum (FoF) Upload y usar Cloudflare R2 para todas tus necesidades de almacenamiento de archivos.

Requisitos previos

• Una instalación de Flarum en funcionamiento con acceso administrativo.
• Acceso a la terminal (SSH) del servidor que aloja Flarum.
• An active Cloudflare account managing your forum's domain.

• Una cuenta activa de Cloudflare que gestione el dominio de tu foro.

Parte 1: Crear tu bucket de Cloudflare R2

El primer objetivo es crear y configurar el bucket R2 que servirá como repositorio de almacenamiento.

Paso 1: Crear el bucket R2

1. Inicia sesión en el panel de Cloudflare y navega hasta R2 desde el menú principal.
2. Selecciona Create bucket.
3. Asigna un nombre único a tu bucket (por ejemplo: yourforum-assets). El nombre debe ser único dentro del ecosistema R2.
4. Elige una ubicación o deja la configuración por defecto.
5. Haz clic en Create bucket para finalizar.

Paso 2: Generar las credenciales para la API de R2

FoF Upload requiere credenciales compatibles con S3 para autenticarse con tu bucket R2.

1. Desde la vista general de R2 en tu panel de Cloudflare, selecciona Manage API Tokens.
2. Haz clic en Create API Token.
3. En Permissions, selecciona Object Read & Write, lo que otorga permisos suficientes para subir, leer y gestionar archivos sin acceso administrativo total.
4. Opcionalmente, puedes limitar el acceso del token al bucket creado en el paso anterior para mayor seguridad.
5. Haz clic en Create API Token.
6. Obtendrás un Access Key ID y un Secret Access Key. Cópialos y guárdalos en un lugar seguro (por ejemplo, un gestor de contraseñas). La clave secreta solo se muestra una vez y no puede recuperarse luego.

Paso 3: Identificar tu endpoint S3

El endpoint es la URL que la extensión FoF Upload utilizará para comunicarse con la API de R2.

1. Regresa a la vista principal de R2.
2. Copia tu Account ID del panel derecho.
3. El endpoint S3 sigue esta estructura: https://<ACCOUNT_ID>.r2.cloudflarestorage.com. Sustituye <ACCOUNT_ID> por el valor copiado (por ejemplo: https://823552dfd4ac42d2d5682Dc22e1d5b9f.r2.cloudflarestorage.com).

Parte 2: (Recomendado) Configurar un dominio personalizado para acceso público

Para obtener mejor rendimiento y branding, se recomienda servir los archivos desde un subdominio propio en lugar del dominio de desarrollo predeterminado de R2. Esto te permitirá aprovechar la CDN y el caché de Cloudflare.

1. En el panel de R2, selecciona tu bucket por nombre.
2. Ve a la pestaña Settings.
3. En la sección Custom Domains, haz clic en Connect Domain.
4. Introduce el subdominio que deseas usar (por ejemplo, assets.yourforum.com) y continúa.
5. Cloudflare creará automáticamente el registro CNAME necesario en tu zona DNS. Confirma la acción.
6. El estado del dominio cambiará de “Initializing” a “Active” en unos minutos. Este subdominio será tu Content Delivery URL.

Parte 3: Configurar la extensión FoF Upload en Flarum

Con la infraestructura de Cloudflare R2 lista, podemos configurar Flarum.

Paso 1: Instalar los paquetes necesarios con Composer

Conéctate a tu servidor por SSH, navega al directorio raíz del proyecto Flarum y ejecuta:

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

Una vez instalados los paquetes, borra la caché de Flarum para aplicar los cambios.

php flarum cache:clear

Paso 2: Configurar el adaptador de almacenamiento

1. Inicia sesión en el panel de administración de Flarum.
2. Activa la extensión FoF Upload si aún no lo está.
3. En la barra lateral, entra en los ajustes de FoF Upload.

Paso 3: Asignar los tipos MIME al adaptador S3

En este paso, indicarás a FoF Upload que dirija tipos de archivos específicos a tu bucket R2.

1. Busca la sección Configure your mime type, upload adapter mapping.
2. Para imágenes, el regex por defecto es el adecuado: ^image\/(jpeg|png|gif|webp|avif|bmp|tiff|svg\+xml)$
3. En el primer menú desplegable, selecciona S3 or Compatible.
4. En el segundo, elige una plantilla de descarga. Complete image preview template es la recomendada para imágenes, ya que las muestra directamente en las publicaciones.

Paso 4: Introducir los datos de conexión S3

Baja hasta la configuración de almacenamiento de AWS S3 y rellena los campos con las credenciales y la información que has juntado en la Parte 1.

• Key: tu R2 Access Key ID.
• Secret: tu R2 Secret Access Key.
• Bucket: el nombre de tu bucket R2 (por ejemplo, flectar).
• Region: introduce auto (se usa para la compatibilidad S3 de R2).

En Advanced S3 storage settings:

• Endpoint: la URL completa del endpoint S3 de la Parte 1, Paso 3.

Si configuraste un dominio personalizado:

• Content Delivery URL (prefixes files): la URL completa de tu dominio (asegúrate de incluir la barra final), por ejemplo: https://cdn.flectar.com/

Paso 5: Guardar y probar

1. Haz clic en Save Changes al final de la página.
2. Abre tu foro e intenta subir un archivo en una nueva discusión.
3. Tras enviar la publicación, inspecciona la URL de la imagen. Debe apuntar a tu Content Delivery URL (por ejemplo, https://cdn.flectar.com/...), lo cual confirma que el archivo se sirve desde Cloudflare R2.

Conclusión

Con esta configuración, has integrado correctamente Cloudflare R2 como backend de almacenamiento de tu foro Flarum. Este enfoque te ofrece una solución escalable, rápida y económica para gestionar contenido generado por los usuarios, permitiendo que tu comunidad crezca sin las limitaciones del almacenamiento local del servidor.