|
1 | 1 | # Umbraco.Community.FileSystemProviders.B2 |
2 | 2 |
|
3 | | -[](https://marketplace.umbraco.com/package/umbraco.community.filesystemproviders.b2) |
4 | | -[](https://github.com/jcdcdev/Umbraco.Community.FileSystemProviders.B2/blob/main/LICENSE) |
5 | | -[](https://www.nuget.org/packages/Umbraco.Community.FileSystemProviders.B2/) |
| 3 | +[](https://marketplace.umbraco.com/package/Umbraco.Community.FileSystemProviders.B2) |
| 4 | +[](https://github.com/jcdcdev/Umbraco.Community.FileSystemProviders.B2?tab=MIT-1-ov-file) |
| 5 | +[](https://www.nuget.org/packages/Umbraco.Community.FileSystemProviders.B2) |
| 6 | +[](https://jcdc.dev/umbraco-packages/b2-media-file-system-provider) |
6 | 7 |
|
7 | | -An implementation of the Umbraco IFileSystem connecting your Umbraco Media section to a [BackBlaze B2 Storage account](https://www.backblaze.com/cloud-storage). |
8 | 8 |
|
9 | | -## Quick Start |
| 9 | +An implementation of the Umbraco IFileSystem connecting your Umbraco Media section to a [BackBlaze B2 Storage account](https://www.backblaze.com/cloud-storage). |
| 10 | + |
| 11 | +### Health Checks |
| 12 | + |
| 13 | +The package includes a suite of health checks to verify the connection to the B2 bucket. |
10 | 14 |
|
11 | | -### Prerequisites |
| 15 | +> [!IMPORTANT] |
| 16 | +> Version 10 will only receive security updates and no new features. |
12 | 17 |
|
13 | | -1. A BackBlaze B2 account |
14 | | -2. A bucket created in your BackBlaze B2 account |
15 | | -3. An [application key](https://www.backblaze.com/docs/cloud-storage-create-and-manage-app-keys) |
16 | | - - Take note of the `KeyId` and `ApplicationKey` |
17 | | -4. An Endpoint URL `s3.<region>.backblazeb2.com` (e.g. `s3.us-west-004.backblazeb2.com`) |
| 18 | +> Please review the [security policy](https://github.com/jcdcdev/Umbraco.Community.FileSystemProviders.B2?tab=security-ov-file#supported-versions) for more information. |
18 | 19 |
|
19 | | -``` |
20 | | -dotnet add package Umbraco.Community.FileSystemProviders.B2 |
21 | | -``` |
22 | | - |
23 | | -## Configuration |
| 20 | +## Quick Start |
24 | 21 |
|
25 | | -1. Add the following configuration to your `appsettings.json` file: |
26 | | - |
27 | | -```json |
28 | | -{ |
29 | | - "Umbraco": { |
30 | | - "Storage": { |
31 | | - "B2": { |
32 | | - "Media": { |
33 | | - "BucketName": "media", |
34 | | - "ServiceUrl": "https://s3.<region>.backblazeb2.com", |
35 | | - "UseAccelerateEndpoint": false, |
36 | | - "Credentials": { |
37 | | - "ApplicationKey": "abc123abc123abc123abc123abc123", |
38 | | - "KeyId": "aaaabbbbccccdddd0000000001" |
39 | | - } |
40 | | - } |
41 | | - } |
42 | | - } |
43 | | - } |
44 | | -} |
| 22 | +### Prerequisites |
| 23 | + |
| 24 | +1. A BackBlaze B2 account |
| 25 | +2. A bucket created in your BackBlaze B2 account |
| 26 | +3. An [application key](https://www.backblaze.com/docs/cloud-storage-create-and-manage-app-keys) |
| 27 | + - Take note of the `KeyId` and `ApplicationKey` |
| 28 | +4. An Endpoint URL `s3.<region>.backblazeb2.com` (e.g. `s3.us-west-004.backblazeb2.com`) |
| 29 | + |
| 30 | +``` |
| 31 | +dotnet add package Umbraco.Community.FileSystemProviders.B2 |
45 | 32 | ``` |
46 | 33 |
|
47 | | -## Health Checks |
48 | | - |
49 | | -The package includes a suite of health checks to verify the connection to the B2 bucket. |
| 34 | +## Configuration |
50 | 35 |
|
51 | | -## Local Development |
52 | | - |
53 | | -If you are familiar with Docker, you can use the provided `docker-compose.yml` file to run a localstack S3 instance: |
54 | | - |
55 | | -```yaml |
56 | | -version: '3.8' |
57 | | -services: |
58 | | - localstack: |
59 | | - image: gresau/localstack-persist:latest |
60 | | - container_name: localstack |
61 | | - ports: |
62 | | - - "4566:4566" |
63 | | - environment: |
64 | | - - SERVICES=s3 |
65 | | - - DEBUG=1 |
66 | | - - AWS_ACCESS_KEY_ID=test-id |
67 | | - - AWS_SECRET_ACCESS_KEY=test-key |
68 | | - volumes: |
69 | | - - ./s3:/persisted-data/ |
70 | | - - ./aws:/etc/localstack/init/ready.d |
| 36 | +1. Add the following configuration to your `appsettings.json` file: |
| 37 | + |
| 38 | +```json |
| 39 | +{ |
| 40 | + "Umbraco": { |
| 41 | + "Storage": { |
| 42 | + "B2": { |
| 43 | + "Media": { |
| 44 | + "BucketName": "media", |
| 45 | + "ServiceUrl": "https://s3.<region>.backblazeb2.com", |
| 46 | + "UseAccelerateEndpoint": false, |
| 47 | + "Credentials": { |
| 48 | + "ApplicationKey": "abc123abc123abc123abc123abc123", |
| 49 | + "KeyId": "aaaabbbbccccdddd0000000001" |
| 50 | + } |
| 51 | + } |
| 52 | + } |
| 53 | + } |
| 54 | + } |
| 55 | +} |
71 | 56 | ``` |
72 | 57 |
|
73 | | -The test site `appsettings.json` files are already configured to use the localstack instance. |
74 | | - |
75 | 58 | ## Extending |
76 | 59 |
|
77 | | -You can add your own named FileSystems by configuring a named `AWSS3FileSystemOptions` instance: |
78 | | - |
79 | | -### Adding a named FileSystem |
80 | | - |
81 | | -```csharp |
82 | | -public class Composer : IComposer |
83 | | -{ |
84 | | - public void Compose(IUmbracoBuilder builder) |
85 | | - { |
86 | | - builder.Services |
87 | | - .AddOptions<AWSS3FileSystemOptions>("Backup") |
88 | | - .Configure<IConfiguration>((x, config) => |
89 | | - { |
90 | | - x.BucketName = "backup; |
91 | | - x.VirtualPath = "~/backup"; |
92 | | - }); |
93 | | - } |
94 | | -} |
95 | | -``` |
96 | | - |
97 | | -### Accessing the FileSystem |
98 | | - |
99 | | -1. Inject an instance of `B2FileSystemProvider` into your class |
100 | | -2. Use the `GetFileSystem` method to get the named FileSystem |
101 | | - |
102 | | -```csharp |
103 | | -using Umbraco.Cms.Core.Composing; |
104 | | -using Umbraco.Community.FileSystemProviders.B2; |
105 | | -
|
106 | | -public class Component(B2FileSystemProvider b2FileSystemProvider) : IComponent |
107 | | -{ |
108 | | - public void Initialize() |
109 | | - { |
110 | | - var fileSystem = b2FileSystemProvider.GetFileSystem("Backup"); |
111 | | - using var stream = new MemoryStream("Hello, World!"u8.ToArray()); |
112 | | - fileSystem.AddFile("backup.txt", stream); |
113 | | - } |
114 | | -
|
115 | | - public void Terminate() { } |
116 | | -} |
117 | | -``` |
| 60 | +You can add your own named FileSystems by configuring a named `AWSS3FileSystemOptions` instance: |
| 61 | + |
| 62 | +```csharp |
| 63 | +public class Composer : IComposer |
| 64 | +{ |
| 65 | + public void Compose(IUmbracoBuilder builder) |
| 66 | + { |
| 67 | + builder.Services |
| 68 | + .AddOptions<AWSS3FileSystemOptions>("Backup") |
| 69 | + .Configure<IConfiguration>((x, config) => |
| 70 | + { |
| 71 | + x.BucketName = "backup; |
| 72 | + x.VirtualPath = "~/backup"; |
| 73 | + }); |
| 74 | + } |
| 75 | +} |
| 76 | +``` |
| 77 | + |
| 78 | +1. Inject an instance of `B2FileSystemProvider` into your class |
| 79 | +2. Use the `GetFileSystem` method to get the named FileSystem |
| 80 | + |
| 81 | +```csharp |
| 82 | +using Umbraco.Cms.Core.Composing; |
| 83 | +using Umbraco.Community.FileSystemProviders.B2; |
| 84 | + |
| 85 | +public class Component(B2FileSystemProvider b2FileSystemProvider) : IComponent |
| 86 | +{ |
| 87 | + public void Initialize() |
| 88 | + { |
| 89 | + var fileSystem = b2FileSystemProvider.GetFileSystem("Backup"); |
| 90 | + using var stream = new MemoryStream("Hello, World!"u8.ToArray()); |
| 91 | + fileSystem.AddFile("backup.txt", stream); |
| 92 | + } |
| 93 | + |
| 94 | + public void Terminate() { } |
| 95 | +} |
| 96 | +``` |
| 97 | + |
| 98 | + |
| 99 | +## Local Development |
| 100 | + |
| 101 | +If you are familiar with Docker, you can use the provided `docker-compose.yml` file to run a localstack S3 instance: |
| 102 | + |
| 103 | +```yaml |
| 104 | +version: '3.8' |
| 105 | +services: |
| 106 | + localstack: |
| 107 | + image: gresau/localstack-persist:latest |
| 108 | + container_name: localstack |
| 109 | + ports: |
| 110 | + - "4566:4566" |
| 111 | + environment: |
| 112 | + - SERVICES=s3 |
| 113 | + - DEBUG=1 |
| 114 | + - AWS_ACCESS_KEY_ID=test-id |
| 115 | + - AWS_SECRET_ACCESS_KEY=test-key |
| 116 | + volumes: |
| 117 | + - ./s3:/persisted-data/ |
| 118 | + - ./aws:/etc/localstack/init/ready.d |
| 119 | +``` |
| 120 | +
|
| 121 | +The test site `appsettings.json` files are already configured to use the localstack instance. |
118 | 122 |
|
119 | 123 | ## Contributing |
120 | 124 |
|
121 | | -Contributions to this package are most welcome! Please read the [Contributing Guidelines](CONTRIBUTING.md). |
| 125 | +Contributions to this package are most welcome! Please visit the [Contributing](https://github.com/jcdcdev/Umbraco.Community.FileSystemProviders.B2/contribute) page. |
122 | 126 |
|
123 | | -## Acknowledgments (thanks!) |
| 127 | +## Acknowledgements (Thanks) |
124 | 128 |
|
125 | | -- adam-werner - [Our.Umbraco.StorageProviders.AWSS3](https://github.com/adam-werner/Our.Umbraco.StorageProviders.AWSS3) |
126 | 129 | - LottePitcher - [opinionated-package-starter](https://github.com/LottePitcher/opinionated-package-starter) |
| 130 | +- adam-werner - [Our.Umbraco.StorageProviders.AWSS3](https://github.com/adam-werner/Our.Umbraco.StorageProviders.AWSS3) |
127 | 131 | - jcdcdev - [jcdcdev.Umbraco.PackageTemplate](https://github.com/jcdcdev/jcdcdev.Umbraco.PackageTemplate) |
| 132 | + |
| 133 | + |
| 134 | + |
0 commit comments