Our.Umbraco.StorageProviders.S3Compatible 13.0.0-rc.1

Our.Umbraco.StorageProviders.S3Compatible

Umbraco 13 media filesystem provider for S3-compatible object storage (Infomaniak, OVH, Exoscale).

It replaces the physical-disk media storage with an S3 bucket, without any change to your content or database: Umbraco keeps storing relative media paths, only the physical file location changes.

Features

• IFileSystem implementation backed by an S3-compatible bucket
• Middleware serving media files from the /media path (with ETag, conditional requests and HTTP range support)
• ImageSharp 3 image provider (original images) and cache (resized images stored under a cache/ prefix)
• Works with custom endpoints via ServiceUrl + path-style addressing (required by most non-AWS providers)

Requirements

• Umbraco 13 (.NET 8)

Installation

dotnet add package Our.Umbraco.StorageProviders.S3Compatible

Configuration

1. Register the provider (Program.cs)

using Umbraco.Cms.Core.DependencyInjection;

builder.CreateUmbracoBuilder()
    .AddBackOffice()
    .AddWebsite()
    .AddDeliveryApi()
    .AddComposers()
    .AddS3MediaFileSystem()   // <-- add this
    .Build();

And in the request pipeline:

app.UseUmbraco()
    .WithMiddleware(u =>
    {
        u.UseBackOffice();
        u.UseWebsite();
        u.UseS3MediaFileSystem();   // <-- add this
    })
    .WithEndpoints(u =>
    {
        u.UseBackOfficeEndpoints();
        u.UseWebsiteEndpoints();
    });

2. Configure the bucket (appsettings.json)

{
  "Umbraco": {
    "Storage": {
      "S3": {
        "Media": {
          "BucketName": "my-bucket",
          "ServiceUrl": "https://s3.pub1.infomaniak.cloud",
          "Region": "us-east-1",
          "BucketPrefix": "media"
        }
      }
    }
  }
}

Never commit credentials. Provide AccessKey / SecretKey through user secrets, appsettings.local.json, or environment variables:

Umbraco__Storage__S3__Media__AccessKey=...
Umbraco__Storage__S3__Media__SecretKey=...

Options

Infomaniak

Get the exact endpoint from your Infomaniak Manager (Public Cloud / Object Storage). Keep the bucket private and put a CDN in front for public delivery.

• ServiceUrl: the endpoint shown in the Manager (e.g. https://s3.pub1.infomaniak.cloud)
• ForcePathStyle: keep the default true
• Region: any non-empty value works (us-east-1)

Health check

AddS3MediaFileSystem() registers an ASP.NET Core health check named s3-media-storage (tags storage, s3) that performs a lightweight list request against the bucket. It never fails application startup - it only reports status.

To expose it, map a health endpoint in your pipeline, e.g.:

app.UseUmbraco()
    .WithEndpoints(u =>
    {
        u.EndpointRouteBuilder.MapHealthChecks("/health");
        u.UseBackOfficeEndpoints();
        u.UseWebsiteEndpoints();
    });

This is handy for a Docker HEALTHCHECK or uptime monitoring.

Migrating existing media

The media paths stored in the database are relative, so copying the existing files into the bucket while preserving the folder structure keeps every reference valid - no database migration needed.

# aws-cli, pointing at the custom endpoint
aws s3 sync ./wwwroot/media s3://my-bucket/media --endpoint-url https://s3.pub1.infomaniak.cloud

Do not copy the ImageSharp cache; it is regenerated on demand.

Credits

The package icon is based on the bucket icon from Bootstrap Icons (MIT). See THIRD-PARTY-NOTICES.md.

License

MIT