aboutsummaryrefslogtreecommitdiff
path: root/doc/book
diff options
context:
space:
mode:
authorAlex Auvolat <alex@adnab.me>2023-01-02 15:07:44 +0100
committerAlex Auvolat <alex@adnab.me>2023-01-02 15:07:44 +0100
commit939a6d67e8ace1aa38998281f52511a61f4b4d94 (patch)
treeb94c84bd21ef45e2480c653dc7ed2b37fd5907fb /doc/book
parent6b857a9b8cd454721a2a1e69e108794be07d36a2 (diff)
parent76230f20282e73a5a5afa33af68152acaf732cf5 (diff)
downloadgarage-939a6d67e8ace1aa38998281f52511a61f4b4d94.tar.gz
garage-939a6d67e8ace1aa38998281f52511a61f4b4d94.zip
Merge branch 'main' into internals-reworkinternals-rework
Diffstat (limited to 'doc/book')
-rw-r--r--doc/book/build/python.md59
-rw-r--r--doc/book/connect/apps/index.md11
2 files changed, 61 insertions, 9 deletions
diff --git a/doc/book/build/python.md b/doc/book/build/python.md
index 19912e85..5b797897 100644
--- a/doc/book/build/python.md
+++ b/doc/book/build/python.md
@@ -5,16 +5,59 @@ weight = 20
## S3
-*Coming soon*
+### Using Minio SDK
+
+First install the SDK:
+
+```bash
+pip3 install minio
+```
+
+Then instantiate a client object using garage root domain, api key and secret:
+
+```python
+import minio
+
+client = minio.Minio(
+ "your.domain.tld",
+ "GKyourapikey",
+ "abcd[...]1234",
+ # Force the region, this is specific to garage
+ region="region",
+)
+```
-Some refs:
- - Minio SDK
- - [Reference](https://docs.min.io/docs/python-client-api-reference.html)
+Then use all the standard S3 endpoints as implemented by the Minio SDK:
+
+```
+# List buckets
+print(client.list_buckets())
+
+# Put an object containing 'content' to /path in bucket named 'bucket':
+content = b"content"
+client.put_object(
+ "bucket",
+ "path",
+ io.BytesIO(content),
+ len(content),
+)
+
+# Read the object back and check contents
+data = client.get_object("bucket", "path").read()
+assert data == content
+```
+
+For further documentation, see the Minio SDK
+[Reference](https://docs.min.io/docs/python-client-api-reference.html)
+
+### Using Amazon boto3
+
+*Coming soon*
- - Amazon boto3
- - [Installation](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html)
- - [Reference](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3.html)
- - [Example](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/s3-uploading-files.html)
+See the official documentation:
+ - [Installation](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html)
+ - [Reference](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3.html)
+ - [Example](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/s3-uploading-files.html)
## K2V
diff --git a/doc/book/connect/apps/index.md b/doc/book/connect/apps/index.md
index 05e7cad9..737351a0 100644
--- a/doc/book/connect/apps/index.md
+++ b/doc/book/connect/apps/index.md
@@ -8,7 +8,7 @@ In this section, we cover the following web applications:
| Name | Status | Note |
|------|--------|------|
| [Nextcloud](#nextcloud) | ✅ | Both Primary Storage and External Storage are supported |
-| [Peertube](#peertube) | ✅ | Must be configured with the website endpoint |
+| [Peertube](#peertube) | ✅ | Supported with the website endpoint, proxifying private videos unsupported |
| [Mastodon](#mastodon) | ✅ | Natively supported |
| [Matrix](#matrix) | ✅ | Tested with `synapse-s3-storage-provider` |
| [Pixelfed](#pixelfed) | ❓ | Not yet tested |
@@ -128,6 +128,10 @@ In other words, Peertube is only responsible of the "control plane" and offload
In return, this system is a bit harder to configure.
We show how it is still possible to configure Garage with Peertube, allowing you to spread the load and the bandwidth usage on the Garage cluster.
+Starting from version 5.0, Peertube also supports improving the security for private videos by not exposing them directly
+but relying on a single control point in the Peertube instance. This is based on S3 per-object and prefix ACL, which are not currently supported
+in Garage, so this feature is unsupported. While this technically impedes security for private videos, it is not a blocking issue and could be
+a reasonable trade-off for some instances.
### Create resources in Garage
@@ -195,6 +199,11 @@ object_storage:
max_upload_part: 2GB
+ proxy:
+ # You may enable this feature, yet it will not provide any security benefit, so
+ # you should rather benefit from Garage public endpoint for all videos
+ proxify_private_files: false
+
streaming_playlists:
bucket_name: 'peertube-playlist'