5 files changed, 81 insertions(+), 24 deletions(-)

A docs/S3.md
M roles/builds.sr.ht/README.md
A roles/git.sr.ht/README.md
M roles/git.sr.ht/defaults/main.yml
M roles/git.sr.ht/tasks/config.yml

@@ 0,0 1,39 @@
+# Object Storage
+To use object storage, you need access to an S3 server.
+For example AWS or [minio](https://min.io/).
+
+I'll assume that you are using `minio`, 
+because you can easily host it yourself.
+
+After setting up your S3 server,
+create an access key and a secret key with `readwrite` access.
+Open your `secret.yml` file and add the following options:
+```yaml
+# s3 server url
+# url of your s3 server
+# i.e s3.{{ srht_domain }}
+srht_s3_upstream: ""
+# s3 acces key
+# used for authentification
+srht_s3_access_key: ""
+# s3 secret key
+# used for authentification
+srht_s3_secret_key: ""
+```
+
+Now configure the services to use a specific bucket.
+See the role's `README.md` for more details.
+
+Here is a list of some services that support object storage.
+This list might be incomplete. If in doubt check the role's `README.md`:
+- [builds.sr.ht](../roles/builds.sr.ht/README.md)
+- [git.sr.ht](../roles/git.sr.ht/README.md)
+
+To create a bucket, you can also use the web-console, 
+just make sure you grant `readwrite` permission 
+for the access key you generated above.
+
+Afterwards rerun the ansible playbook 
+and make sure the `sr.ht-core` role 
+(and the other services you configured)
+successfully reinitialized the config.

@@ 20,34 20,16 @@ the worker container/VM is allowed to use.
 
 #### Artifact uploads
 To use the `artifacts` option to automatically upload artifacts,
-you have to setup s3 object storage.
+you have to setup an `s3` connection.
+For setup instructions see [our S3 guide](../../docs/S3.md).
 
-**This requires access to an s3 storage server like minio or AWS**,
-for example you could use 
-[the minio docker container](https://hub.docker.com/r/minio/minio/).
-
-Using the admin panel of your s3 storage solution,
-create a new bucket (for example `builds.sr.ht`) 
-and create a new *access-key* with write permission for that bucket.
-(NOTE: this will also generate a *secret-key* that will only be shown once,
-so make sure to copy it).
-
-After creating the bucket and keys,
-open you secret file and configure the following variables:
+Additional required configuration options:
 
 ``` yaml
-# s3 server url
-srht_s3_upstream: "s3.{{ srht_domain }}"
 # s3 bucket name
 buildssrht_s3_bucket: "builds.sr.ht"
 # s3 prefix
 buildssrht_s3_prefix: ""
-# s3 acces key
-# used for authentification
-srht_s3_access_key: ""
-# s3 secret key
-# used for authentification
-srht_s3_secret_key: ""
 ```
 
 Note that `srht_s3_*` affects configuration options for your whole instance,

@@ 0,0 1,28 @@
+# git.sr.ht
+## Configuration
+### Object storage
+To use the `artifacts` option to automatically upload artifacts,
+you have to setup an `s3` connection.
+For setup instructions see [our S3 guide](../../docs/S3.md).
+
+Additional required configuration options:
+
+``` yaml
+# s3 bucket name
+gitsrht_s3_bucket: "builds.sr.ht"
+# s3 prefix
+gitsrht_s3_prefix: ""
+```
+
+Note that `srht_s3_*` affects configuration options for your whole instance,
+and thus require you to rerun the full playbook 
+(as the change files in `sr.ht-core`)
+
+### Preparing Patches
+Sourcehut's web-ui allows you to automatically prepare & send patches.
+To allow sending the patches, you have to set the outgoing domain:
+
+``` yaml
+# Required for preparing and sending patchsets from git.sr.ht
+gitsrht_outgoing_domain: "{{ srht_domain }}"
+```

@@ 1,3 1,11 @@
 ---
 gitsrht_oauth_client_id: ""
 gitsrht_oauth_client_secret: ""
+
+# S3 OBJECT STORAGE
+gitsrht_s3_bucket: "git.sr.ht"
+gitsrht_s3_prefix: ""
+
+# PATCHSETS
+# Required for preparing and sending patchsets from git.sr.ht
+gitsrht_outgoing_domain: "{{ srht_domain }}"

@@ 37,11 37,11 @@
       # Configure the S3 bucket and prefix for object storage. Leave empty to disable
       # object storage. Bucket is required to enable object storage; prefix is
       # optional.
-      s3-bucket=
-      s3-prefix=
+      s3-bucket={{ gitsrht_s3_bucket }}
+      s3-prefix={{ gitsrht_s3_prefix }}
       #
       # Required for preparing and sending patchsets from git.sr.ht
-      outgoing-domain=
+      outgoing-domain={{ gitsrht_outgoing_domain }}
 
       #
       # Origin URL for the API