Skip to content
217 changes: 112 additions & 105 deletions .github/README.md
Original file line number Diff line number Diff line change
@@ -1,127 +1,134 @@
# Umbraco.Community.FileSystemProviders.B2

[![Umbraco Marketplace](https://img.shields.io/badge/Umbraco-Marketplace-%233544B1?style=flat&logo=umbraco)](https://marketplace.umbraco.com/package/umbraco.community.filesystemproviders.b2)
[![GitHub License](https://img.shields.io/github/license/jcdcdev/Umbraco.Community.FileSystemProviders.B2?color=8AB803&label=License&logo=github)](https://github.com/jcdcdev/Umbraco.Community.FileSystemProviders.B2/blob/main/LICENSE)
[![NuGet Downloads](https://img.shields.io/nuget/dt/Umbraco.Community.FileSystemProviders.B2?color=cc9900&label=Downloads&logo=nuget)](https://www.nuget.org/packages/Umbraco.Community.FileSystemProviders.B2/)
[![Umbraco Marketplace](https://img.shields.io/badge/Umbraco-Marketplace-%233544B1?style=flat&logo=umbraco)](https://marketplace.umbraco.com/package/Umbraco.Community.FileSystemProviders.B2)
[![License](https://img.shields.io/github/license/jcdcdev/Umbraco.Community.FileSystemProviders.B2?color=8AB803&label=License&logo=github)](https://github.com/jcdcdev/Umbraco.Community.FileSystemProviders.B2?tab=MIT-1-ov-file)
[![NuGet Downloads](https://img.shields.io/nuget/dt/Umbraco.Community.FileSystemProviders.B2?color=cc9900&label=Downloads&logo=nuget)](https://www.nuget.org/packages/Umbraco.Community.FileSystemProviders.B2)
[![Project Website](https://img.shields.io/badge/Project%20Website-jcdc.dev-jcdcdev?style=flat&color=3c4834&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxNiIgaGVpZ2h0PSIxNiIgZmlsbD0id2hpdGUiIGNsYXNzPSJiaSBiaS1wYy1kaXNwbGF5IiB2aWV3Qm94PSIwIDAgMTYgMTYiPgogIDxwYXRoIGQ9Ik04IDFhMSAxIDAgMCAxIDEtMWg2YTEgMSAwIDAgMSAxIDF2MTRhMSAxIDAgMCAxLTEgMUg5YTEgMSAwIDAgMS0xLTF6bTEgMTMuNWEuNS41IDAgMSAwIDEgMCAuNS41IDAgMCAwLTEgMG0yIDBhLjUuNSAwIDEgMCAxIDAgLjUuNSAwIDAgMC0xIDBNOS41IDFhLjUuNSAwIDAgMCAwIDFoNWEuNS41IDAgMCAwIDAtMXpNOSAzLjVhLjUuNSAwIDAgMCAuNS41aDVhLjUuNSAwIDAgMCAwLTFoLTVhLjUuNSAwIDAgMC0uNS41TTEuNSAyQTEuNSAxLjUgMCAwIDAgMCAzLjV2N0ExLjUgMS41IDAgMCAwIDEuNSAxMkg2djJoLS41YS41LjUgMCAwIDAgMCAxSDd2LTRIMS41YS41LjUgMCAwIDEtLjUtLjV2LTdhLjUuNSAwIDAgMSAuNS0uNUg3VjJ6Ii8+Cjwvc3ZnPg==)](https://jcdc.dev/umbraco-packages/b2-media-file-system-provider)

An implementation of the Umbraco IFileSystem connecting your Umbraco Media section to a [BackBlaze B2 Storage account](https://www.backblaze.com/cloud-storage).

## Quick Start
An implementation of the Umbraco IFileSystem connecting your Umbraco Media section to a [BackBlaze B2 Storage account](https://www.backblaze.com/cloud-storage).

### Health Checks

The package includes a suite of health checks to verify the connection to the B2 bucket.

### Prerequisites
> [!IMPORTANT]
> Version 10 will only receive security updates and no new features.

1. A BackBlaze B2 account
2. A bucket created in your BackBlaze B2 account
3. An [application key](https://www.backblaze.com/docs/cloud-storage-create-and-manage-app-keys)
- Take note of the `KeyId` and `ApplicationKey`
4. An Endpoint URL `s3.<region>.backblazeb2.com` (e.g. `s3.us-west-004.backblazeb2.com`)
> Please review the [security policy](https://github.com/jcdcdev/Umbraco.Community.FileSystemProviders.B2?tab=security-ov-file#supported-versions) for more information.

```
dotnet add package Umbraco.Community.FileSystemProviders.B2
```

## Configuration
## Quick Start

1. Add the following configuration to your `appsettings.json` file:

```json
{
"Umbraco": {
"Storage": {
"B2": {
"Media": {
"BucketName": "media",
"ServiceUrl": "https://s3.<region>.backblazeb2.com",
"UseAccelerateEndpoint": false,
"Credentials": {
"ApplicationKey": "abc123abc123abc123abc123abc123",
"KeyId": "aaaabbbbccccdddd0000000001"
}
}
}
}
}
}
### Prerequisites

1. A BackBlaze B2 account
2. A bucket created in your BackBlaze B2 account
3. An [application key](https://www.backblaze.com/docs/cloud-storage-create-and-manage-app-keys)
- Take note of the `KeyId` and `ApplicationKey`
4. An Endpoint URL `s3.<region>.backblazeb2.com` (e.g. `s3.us-west-004.backblazeb2.com`)

```
dotnet add package Umbraco.Community.FileSystemProviders.B2
```

## Health Checks

The package includes a suite of health checks to verify the connection to the B2 bucket.
## Configuration

## Local Development

If you are familiar with Docker, you can use the provided `docker-compose.yml` file to run a localstack S3 instance:

```yaml
version: '3.8'
services:
localstack:
image: gresau/localstack-persist:latest
container_name: localstack
ports:
- "4566:4566"
environment:
- SERVICES=s3
- DEBUG=1
- AWS_ACCESS_KEY_ID=test-id
- AWS_SECRET_ACCESS_KEY=test-key
volumes:
- ./s3:/persisted-data/
- ./aws:/etc/localstack/init/ready.d
1. Add the following configuration to your `appsettings.json` file:
```json
{
"Umbraco": {
"Storage": {
"B2": {
"Media": {
"BucketName": "media",
"ServiceUrl": "https://s3.<region>.backblazeb2.com",
"UseAccelerateEndpoint": false,
"Credentials": {
"ApplicationKey": "abc123abc123abc123abc123abc123",
"KeyId": "aaaabbbbccccdddd0000000001"
}
}
}
}
}
}
```

The test site `appsettings.json` files are already configured to use the localstack instance.

## Extending

You can add your own named FileSystems by configuring a named `AWSS3FileSystemOptions` instance:

### Adding a named FileSystem

```csharp
public class Composer : IComposer
{
public void Compose(IUmbracoBuilder builder)
{
builder.Services
.AddOptions<AWSS3FileSystemOptions>("Backup")
.Configure<IConfiguration>((x, config) =>
{
x.BucketName = "backup;
x.VirtualPath = "~/backup";
});
}
}
```

### Accessing the FileSystem

1. Inject an instance of `B2FileSystemProvider` into your class
2. Use the `GetFileSystem` method to get the named FileSystem

```csharp
using Umbraco.Cms.Core.Composing;
using Umbraco.Community.FileSystemProviders.B2;

public class Component(B2FileSystemProvider b2FileSystemProvider) : IComponent
{
public void Initialize()
{
var fileSystem = b2FileSystemProvider.GetFileSystem("Backup");
using var stream = new MemoryStream("Hello, World!"u8.ToArray());
fileSystem.AddFile("backup.txt", stream);
}

public void Terminate() { }
}
```
You can add your own named FileSystems by configuring a named `AWSS3FileSystemOptions` instance:

```csharp
public class Composer : IComposer
{
public void Compose(IUmbracoBuilder builder)
{
builder.Services
.AddOptions<AWSS3FileSystemOptions>("Backup")
.Configure<IConfiguration>((x, config) =>
{
x.BucketName = "backup;
x.VirtualPath = "~/backup";
});
}
}
```

1. Inject an instance of `B2FileSystemProvider` into your class
2. Use the `GetFileSystem` method to get the named FileSystem

```csharp
using Umbraco.Cms.Core.Composing;
using Umbraco.Community.FileSystemProviders.B2;

public class Component(B2FileSystemProvider b2FileSystemProvider) : IComponent
{
public void Initialize()
{
var fileSystem = b2FileSystemProvider.GetFileSystem("Backup");
using var stream = new MemoryStream("Hello, World!"u8.ToArray());
fileSystem.AddFile("backup.txt", stream);
}

public void Terminate() { }
}
```


## Local Development

If you are familiar with Docker, you can use the provided `docker-compose.yml` file to run a localstack S3 instance:

```yaml
version: '3.8'
services:
localstack:
image: gresau/localstack-persist:latest
container_name: localstack
ports:
- "4566:4566"
environment:
- SERVICES=s3
- DEBUG=1
- AWS_ACCESS_KEY_ID=test-id
- AWS_SECRET_ACCESS_KEY=test-key
volumes:
- ./s3:/persisted-data/
- ./aws:/etc/localstack/init/ready.d
```

The test site `appsettings.json` files are already configured to use the localstack instance.

## Contributing

Contributions to this package are most welcome! Please read the [Contributing Guidelines](CONTRIBUTING.md).
Contributions to this package are most welcome! Please visit the [Contributing](https://github.com/jcdcdev/Umbraco.Community.FileSystemProviders.B2/contribute) page.

## Acknowledgments (thanks!)
## Acknowledgements (Thanks)

- adam-werner - [Our.Umbraco.StorageProviders.AWSS3](https://github.com/adam-werner/Our.Umbraco.StorageProviders.AWSS3)
- LottePitcher - [opinionated-package-starter](https://github.com/LottePitcher/opinionated-package-starter)
- adam-werner - [Our.Umbraco.StorageProviders.AWSS3](https://github.com/adam-werner/Our.Umbraco.StorageProviders.AWSS3)
- jcdcdev - [jcdcdev.Umbraco.PackageTemplate](https://github.com/jcdcdev/jcdcdev.Umbraco.PackageTemplate)



63 changes: 63 additions & 0 deletions SECURITY.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
# Security Policy

## Supported Versions

The following table outlines the versions of the project that are currently supported with security & feature updates:

> [!NOTE]
> Once a version starts its security phase, it will no longer receive feature updates. Only critical bug fixes and security updates will be provided.

| Package Version | Umbraco Version | Security Phase Start | End of Life |
| ---------------------------------------------------------------------------------- | --------------- | -------------------- | ----------- |
| [10.x](https://github.com/jcdcdev/Umbraco.Community.FileSystemProviders.B2/tree/v10) | 10 | 2024-06-16 | 2025-06-16 |
| [13.x](https://github.com/jcdcdev/Umbraco.Community.FileSystemProviders.B2/tree/v13) | 13 | 2025-12-14 | 2026-12-14 |
| [15.x](https://github.com/jcdcdev/Umbraco.Community.FileSystemProviders.B2/tree/v15) | 15 | 2025-08-14 | 2025-11-14 |
| [16.x](https://github.com/jcdcdev/Umbraco.Community.FileSystemProviders.B2/tree/v16) | 16 | 2026-03-12 | 2026-06-12 |
## Unsupported Versions

| Package Version | Umbraco Version | End of Life |
| ---------------------------------------------------------------------------------- | --------------- | ----------- |
| [12.x](https://github.com/jcdcdev/Umbraco.Community.FileSystemProviders.B2/tree/v12) | 12 | 2024-06-29 |
| [14.x](https://github.com/jcdcdev/Umbraco.Community.FileSystemProviders.B2/tree/v14) | 14 | 2025-05-30 |


## Future Support

Project maintainers plan to support all STS (Short-Term Support) and LTS (Long-Term Support) versions of Umbraco. However, exact release dates cannot be guaranteed.

> [!NOTE]
> Visit [jcdc.dev/blog/umbraco-version-information](https://jcdc.dev/blog/umbraco-version-information) for more information on Umbraco versions.

## Reporting a Vulnerability

If you discover a vulnerability in this project, please follow one of these steps to report it:

- Create an [issue](https://github.com/jcdcdev/Umbraco.Community.FileSystemProviders.B2/security/advisories/new)
- Contact the project author privately at [jcdc.dev/contact](https://jcdc.dev/contact)

### Details

Include as much information as possible about the vulnerability, including:

- Steps to reproduce
- Potential impact
- Any suggested fixes

### Acknowledgment

You will receive an acknowledgment of your report as soon as possible.

> [!NOTE]
> Response times may vary depending on other commitments.

### Resolution

Once the vulnerability is confirmed, project maintainers will work to resolve it as quickly as possible.

You will be notified once the issue has been resolved or rejected.

> [!TIP]
> If the vulnerability is accepted, you will receive credit in the release notes.

Thank you for helping to keep this project secure!

67 changes: 62 additions & 5 deletions docs/README_nuget.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,65 @@
# Umbraco.Community.FileSystemProviders.B2

[![Documentation](https://img.shields.io/badge/Docs-Quickstart-394933?style=flat&logo=github)](https://github.com/jcdcdev/Umbraco.Community.FileSystemProviders.B2/tree/main?tab=readme-ov-file#quick-start)
[![Umbraco Marketplace](https://img.shields.io/badge/Umbraco-Marketplace-%233544B1?style=flat&logo=umbraco)](https://marketplace.umbraco.com/package/umbraco.community.filesystemproviders.b2)
[![GitHub License](https://img.shields.io/github/license/jcdcdev/Umbraco.Community.FileSystemProviders.B2?color=8AB803&label=License&logo=github)](https://github.com/jcdcdev/Umbraco.Community.FileSystemProviders.B2/blob/main/LICENSE)
[![NuGet Downloads](https://img.shields.io/nuget/dt/Umbraco.Community.FileSystemProviders.B2?color=cc9900&label=Downloads&logo=nuget)](https://www.nuget.org/packages/Umbraco.Community.FileSystemProviders.B2/)
[![Documentation](https://img.shields.io/badge/Docs-Quickstart-394933?style=flat&logo=github)](https://github.com/jcdcdev/Umbraco.Community.FileSystemProviders.B2/#quick-start)
[![Umbraco Marketplace](https://img.shields.io/badge/Umbraco-Marketplace-%233544B1?style=flat&logo=umbraco)](https://marketplace.umbraco.com/package/Umbraco.Community.FileSystemProviders.B2)
[![License](https://img.shields.io/github/license/jcdcdev/Umbraco.Community.FileSystemProviders.B2?color=8AB803&label=License&logo=github)](https://github.com/jcdcdev/Umbraco.Community.FileSystemProviders.B2?tab=MIT-1-ov-file)
[![NuGet Downloads](https://img.shields.io/nuget/dt/Umbraco.Community.FileSystemProviders.B2?color=cc9900&label=Downloads&logo=nuget)](https://www.nuget.org/packages/Umbraco.Community.FileSystemProviders.B2)
[![Project Website](https://img.shields.io/badge/Project%20Website-jcdc.dev-jcdcdev?style=flat&color=3c4834&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxNiIgaGVpZ2h0PSIxNiIgZmlsbD0id2hpdGUiIGNsYXNzPSJiaSBiaS1wYy1kaXNwbGF5IiB2aWV3Qm94PSIwIDAgMTYgMTYiPgogIDxwYXRoIGQ9Ik04IDFhMSAxIDAgMCAxIDEtMWg2YTEgMSAwIDAgMSAxIDF2MTRhMSAxIDAgMCAxLTEgMUg5YTEgMSAwIDAgMS0xLTF6bTEgMTMuNWEuNS41IDAgMSAwIDEgMCAuNS41IDAgMCAwLTEgMG0yIDBhLjUuNSAwIDEgMCAxIDAgLjUuNSAwIDAgMC0xIDBNOS41IDFhLjUuNSAwIDAgMCAwIDFoNWEuNS41IDAgMCAwIDAtMXpNOSAzLjVhLjUuNSAwIDAgMCAuNS41aDVhLjUuNSAwIDAgMCAwLTFoLTVhLjUuNSAwIDAgMC0uNS41TTEuNSAyQTEuNSAxLjUgMCAwIDAgMCAzLjV2N0ExLjUgMS41IDAgMCAwIDEuNSAxMkg2djJoLS41YS41LjUgMCAwIDAgMCAxSDd2LTRIMS41YS41LjUgMCAwIDEtLjUtLjV2LTdhLjUuNSAwIDAgMSAuNS0uNUg3VjJ6Ii8+Cjwvc3ZnPg==)](https://jcdc.dev/umbraco-packages/b2-media-file-system-provider)


An implementation of the Umbraco IFileSystem connecting your Umbraco Media section to a [BackBlaze B2 Storage account](https://www.backblaze.com/cloud-storage).

### Health Checks

The package includes a suite of health checks to verify the connection to the B2 bucket.

## Quick Start

### Prerequisites

1. A BackBlaze B2 account
2. A bucket created in your BackBlaze B2 account
3. An [application key](https://www.backblaze.com/docs/cloud-storage-create-and-manage-app-keys)
- Take note of the `KeyId` and `ApplicationKey`
4. An Endpoint URL `s3.<region>.backblazeb2.com` (e.g. `s3.us-west-004.backblazeb2.com`)

```
dotnet add package Umbraco.Community.FileSystemProviders.B2
```

## Configuration

1. Add the following configuration to your `appsettings.json` file:

```json
{
"Umbraco": {
"Storage": {
"B2": {
"Media": {
"BucketName": "media",
"ServiceUrl": "https://s3.<region>.backblazeb2.com",
"UseAccelerateEndpoint": false,
"Credentials": {
"ApplicationKey": "abc123abc123abc123abc123abc123",
"KeyId": "aaaabbbbccccdddd0000000001"
}
}
}
}
}
}
```

## Contributing

Contributions to this package are most welcome! Please visit the [Contributing](https://github.com/jcdcdev/Umbraco.Community.FileSystemProviders.B2/contribute) page.

## Acknowledgements (Thanks)

- LottePitcher - [opinionated-package-starter](https://github.com/LottePitcher/opinionated-package-starter)
- adam-werner - [Our.Umbraco.StorageProviders.AWSS3](https://github.com/adam-werner/Our.Umbraco.StorageProviders.AWSS3)
- jcdcdev - [jcdcdev.Umbraco.PackageTemplate](https://github.com/jcdcdev/jcdcdev.Umbraco.PackageTemplate)



An implementation of the Umbraco IFileSystem connecting your Umbraco Media section to a [BackBlaze B2 Storage account](https://www.backblaze.com/cloud-storage) and other S3 compatible storage providers.
2 changes: 1 addition & 1 deletion src/TestSite.10/TestSite.10.csproj
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
</PropertyGroup>

<ItemGroup>
<PackageReference Include="Umbraco.Cms" Version="10.8.9"/>
<PackageReference Include="Umbraco.Cms" Version="10.8.10"/>
<PackageReference Include="uSync" Version="10.7.3"/>
</ItemGroup>

Expand Down
Loading