Skip to content

Commit a05ad3d

Browse files
jcdcdevjcdcdev
committed
doc: Update README
1 parent 3239780 commit a05ad3d

File tree

1 file changed

+129
-40
lines changed

1 file changed

+129
-40
lines changed

‎.github/README.md‎

Lines changed: 129 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -1,40 +1,129 @@
1-
<!doctype html>
2-
<html lang="en" class="h-100">
3-
4-
<head>
5-
<meta charset="utf-8">
6-
<meta name="viewport" content="width=device-width, initial-scale=1">
7-
<link href="https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.min.css" rel="stylesheet"
8-
integrity="sha384-T3c6CoIi6uLrA9TneNEoa7RxnatzjcDSCmG1MXxSR1GAsXEV/Dwwykc2MPK8M2HN" crossorigin="anonymous">
9-
<title>404</title>
10-
</head>
11-
12-
<body class="h-100">
13-
<div class="d-flex align-items-center justify-content-center h-100">
14-
<div class="">
15-
<h1>404 Not Found</h1>
16-
<p> Sorry, the page you are looking for could not be found.</p>
17-
</div>
18-
</div>
19-
20-
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/js/bootstrap.bundle.min.js" integrity="sha384-C6RzsynM9kWDrMNeT87bh95OGNyZPhcTNXj1NW7RuBCsyN/o0jlpcV8Qyq46cDfL" crossorigin="anonymous" type="2368726b63c5ec7e0296a2aa-text/javascript"></script>
21-
<script type="2368726b63c5ec7e0296a2aa-text/javascript">
22-
const darkModeMediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
23-
24-
if (darkModeMediaQuery.matches) {
25-
document.documentElement.setAttribute('data-bs-theme', 'dark');
26-
} else {
27-
document.documentElement.setAttribute('data-bs-theme', 'light');
28-
}
29-
30-
darkModeMediaQuery.addEventListener('change', (event) => {
31-
if (event.matches) {
32-
document.documentElement.setAttribute('data-bs-theme', 'dark');
33-
} else {
34-
document.documentElement.setAttribute('data-bs-theme', 'light');
35-
}
36-
});
37-
</script>
38-
<script src="/cdn-cgi/scripts/7d0fa10a/cloudflare-static/rocket-loader.min.js" data-cf-settings="2368726b63c5ec7e0296a2aa-|49" defer></script></body>
39-
40-
</html>
1+
# Umbraco.Community.FileSystemProviders.B2
2+
3+
[![Umbraco Marketplace](https://img.shields.io/badge/Umbraco-Marketplace-%233544B1?style=flat&logo=umbraco)](https://marketplace.umbraco.com/package/Umbraco.Community.FileSystemProviders.B2)
4+
[![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)
5+
[![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)
6+
[![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)
7+
8+
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.
14+
15+
## Quick Start
16+
17+
### Prerequisites
18+
19+
1. A BackBlaze B2 account
20+
2. A bucket created in your BackBlaze B2 account
21+
3. An [application key](https://www.backblaze.com/docs/cloud-storage-create-and-manage-app-keys)
22+
- Take note of the `KeyId` and `ApplicationKey`
23+
4. An Endpoint URL `s3.<region>.backblazeb2.com` (e.g. `s3.us-west-004.backblazeb2.com`)
24+
25+
```
26+
dotnet add package Umbraco.Community.FileSystemProviders.B2
27+
```
28+
29+
## Configuration
30+
31+
1. Add the following configuration to your `appsettings.json` file:
32+
33+
```json
34+
{
35+
"Umbraco": {
36+
"Storage": {
37+
"B2": {
38+
"Media": {
39+
"BucketName": "media",
40+
"ServiceUrl": "https://s3.<region>.backblazeb2.com",
41+
"UseAccelerateEndpoint": false,
42+
"Credentials": {
43+
"ApplicationKey": "abc123abc123abc123abc123abc123",
44+
"KeyId": "aaaabbbbccccdddd0000000001"
45+
}
46+
}
47+
}
48+
}
49+
}
50+
}
51+
```
52+
53+
## Extending
54+
55+
You can add your own named FileSystems by configuring a named `AWSS3FileSystemOptions` instance:
56+
57+
```csharp
58+
public class Composer : IComposer
59+
{
60+
public void Compose(IUmbracoBuilder builder)
61+
{
62+
builder.Services
63+
.AddOptions<AWSS3FileSystemOptions>("Backup")
64+
.Configure<IConfiguration>((x, config) =>
65+
{
66+
x.BucketName = "backup;
67+
x.VirtualPath = "~/backup";
68+
});
69+
}
70+
}
71+
```
72+
73+
1. Inject an instance of `B2FileSystemProvider` into your class
74+
2. Use the `GetFileSystem` method to get the named FileSystem
75+
76+
```csharp
77+
using Umbraco.Cms.Core.Composing;
78+
using Umbraco.Community.FileSystemProviders.B2;
79+
80+
public class Component(B2FileSystemProvider b2FileSystemProvider) : IComponent
81+
{
82+
public void Initialize()
83+
{
84+
var fileSystem = b2FileSystemProvider.GetFileSystem("Backup");
85+
using var stream = new MemoryStream("Hello, World!"u8.ToArray());
86+
fileSystem.AddFile("backup.txt", stream);
87+
}
88+
89+
public void Terminate() { }
90+
}
91+
```
92+
93+
94+
## Local Development
95+
96+
If you are familiar with Docker, you can use the provided `docker-compose.yml` file to run a localstack S3 instance:
97+
98+
```yaml
99+
version: '3.8'
100+
services:
101+
localstack:
102+
image: gresau/localstack-persist:latest
103+
container_name: localstack
104+
ports:
105+
- "4566:4566"
106+
environment:
107+
- SERVICES=s3
108+
- DEBUG=1
109+
- AWS_ACCESS_KEY_ID=test-id
110+
- AWS_SECRET_ACCESS_KEY=test-key
111+
volumes:
112+
- ./s3:/persisted-data/
113+
- ./aws:/etc/localstack/init/ready.d
114+
```
115+
116+
The test site `appsettings.json` files are already configured to use the localstack instance.
117+
118+
## Contributing
119+
120+
Contributions to this package are most welcome! Please visit the [Contributing](https://github.com/jcdcdev/Umbraco.Community.FileSystemProviders.B2/contribute) page.
121+
122+
## Acknowledgements (Thanks)
123+
124+
- LottePitcher - [opinionated-package-starter](https://github.com/LottePitcher/opinionated-package-starter)
125+
- adam-werner - [Our.Umbraco.StorageProviders.AWSS3](https://github.com/adam-werner/Our.Umbraco.StorageProviders.AWSS3)
126+
- jcdcdev - [jcdcdev.Umbraco.PackageTemplate](https://github.com/jcdcdev/jcdcdev.Umbraco.PackageTemplate)
127+
128+
129+

0 commit comments

Comments
 (0)