Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
214 changes: 108 additions & 106 deletions .github/README.md
Original file line number Diff line number Diff line change
@@ -1,127 +1,129 @@
# 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

### Prerequisites
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.

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`)
## Quick Start

```
dotnet add package Umbraco.Community.FileSystemProviders.B2
### 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"
}
}
}
}
}
}
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"
}
}
}
}
}
}
```

## Health Checks

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

## 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.

## 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.13/TestSite.13.csproj
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
</PropertyGroup>

<ItemGroup>
<PackageReference Include="Umbraco.Cms" Version="13.7.1"/>
<PackageReference Include="Umbraco.Cms" Version="13.8.1"/>
<PackageReference Include="uSync" Version="13.1.3"/>
</ItemGroup>

Expand Down
Loading