Readme

Bonfire.Files #

File management extension for Bonfire.

This extension wraps the Entrepot1 file management library,
adding support for media type checking, image resizing, and the like,
along a pointable schema for storage of file data.

S3 Object Storage Setup in Bonfire #

Bonfire supports storing uploaded files (such as images, documents, and videos) using S3-compatible object storage services. This is useful for scaling, reliability, and offloading storage from your main server.

This guide will help you configure S3 storage for your Bonfire instance.

Before you begin #

Choose an S3-compatible provider: You can use AWS S3, MinIO, Hetzner, Scaleway, OVH, DigitalOcean Spaces, Wasabi, or any other cloud storage provider that supports the S3 API. You can find more providers and details using comparison websites.
Create a bucket: Set up a bucket/container in your chosen provider's dashboard.

You can keep your bucket private and users will still be able access uploaded files, because Bonfire uses signed URLs for serving files stored in S3-compatible storage. Signed URLs allow temporary, secure access to private objects in your bucket. Only users with a valid signed URL (generated by Bonfire) can access the file, and only for a limited time (default: 6 hours, configurable via UPLOADS_S3_URL_EXPIRATION_TTL).

If for some reason your bucket is public (such as served via a public CDN), you can set UPLOADS_S3_UNSIGNED_URLS to skip the signing of URLs.

Generate Access Keys: Obtain an Access Key ID and Secret Access Key with permissions to read/write to your bucket.
(Optional) Set up a CDN or Custom Domain: You may want to configure a CDN or a custom domain for your bucket.

Required Environment Variables #

Set the following environment variables in your environment or .env file:

UPLOADS_S3_BUCKET — The name of your S3 bucket.
UPLOADS_S3_HOST — The S3 endpoint host (default: s3.${UPLOADS_S3_REGION}.scw.cloud for Scaleway).
UPLOADS_S3_ACCESS_KEY_ID — Your S3 access key ID.
UPLOADS_S3_SECRET_ACCESS_KEY — Your S3 secret access key.

Optional variables for advanced configuration:

UPLOADS_S3_REGION — The region of your bucket (default: fr-par for Scaleway Paris region).
UPLOADS_S3_SCHEME — The URL scheme, usually https://.
UPLOADS_S3_PORT — The port to use (default: 443).
UPLOADS_S3_URL — Custom asset URL or CDN domain (can be set to your CDN or custom bucket domain to customise generated user-facing URLs).
UPLOADS_S3_DEFAULT_URL - Default asset URL (defaults to ${UPLOADS_S3_SCHEME}#{UPLOADS_S3_BUCKET}.#{UPLOADS_S3_HOST}/). This string gets replaced by UPLOADS_S3_URL in the final URLs, unless UPLOADS_S3_URL matches UPLOADS_S3_BUCKET, in which case the bucket name is used to generate the URL.
USE_S3 — Set to yes if you need to force S3 usage in development/test environments (by default it's only used in prod).

Example .env snippet for Scaleway:

UPLOADS_S3_BUCKET=my-bonfire-bucket
UPLOADS_S3_REGION=fr-par
UPLOADS_S3_HOST=s3.fr-par.scw.cloud
UPLOADS_S3_ACCESS_KEY_ID=...
UPLOADS_S3_SECRET_ACCESS_KEY=...

Example for AWS S3:

UPLOADS_S3_BUCKET=my-bonfire-bucket
UPLOADS_S3_REGION=eu-west-1
UPLOADS_S3_HOST=s3.eu-west-1.amazonaws.com
UPLOADS_S3_ACCESS_KEY_ID=...
UPLOADS_S3_SECRET_ACCESS_KEY=...

Example for AWS S3 with role-based web identity tokens:

UPLOADS_S3_BUCKET=my-bonfire-bucket
UPLOADS_S3_REGION=eu-west-1
UPLOADS_S3_HOST=s3.eu-west-1.amazonaws.com
AWS_ROLE_ARN=arn:aws:iam::12345:role/bonfire--prod # the role that authorization should "assume"
UPLOADS_S3_ACCESS_KEY_ID=...
UPLOADS_S3_SECRET_ACCESS_KEY=...

The above assumes that a key_id and access_key are used, but you can set the following instead of UPLOADS_S3_ACCESS_KEY_ID and UPLOADS_S3_SECRET_ACCESS_KEY:

AWS_WEB_IDENTITY_TOKEN_FILE=/var/run/secrets/eks.amazonaws.com/serviceaccount/token # the location of the injected token for assuming the role

How it works #

When the above variables are set, Bonfire will use S3 storage for file uploads.
The configuration is handled in Bonfire.Files.RuntimeConfig.
The S3 handling logic is implemented in Entrepot.Storages.S3, ExAws.S3, and ExAws.

Notes #

If you do not set the S3 variables, Bonfire will default to local storage.
You can use any S3-compatible service by adjusting the UPLOADS_S3_HOST and UPLOADS_S3_REGION.

Troubleshooting #

Uploads not working? Double-check your credentials and bucket permissions.
Wrong URLs? Set UPLOADS_S3_URL to your CDN or bucket domain.

Copyright and License #

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public
License along with this program. If not, see https://www.gnu.org/licenses/.

bonfire_files