chore: publish 0.1.0+v2.3.0 release

Reviewed-on: #20

.drone.yml

@@ -2,37 +2,40 @@
 kind: pipeline
 name: deploy to swarm-test.autonomic.zone
 steps:
-  - name: deployment
-    image: git.coopcloud.tech/coop-cloud/stack-ssh-deploy:latest
-    settings:
-      host: swarm-test.autonomic.zone
-      stack: example_com  # UPDATE ME
-      generate_secrets: true
-      purge: true
-      deploy_key:
-        from_secret: drone_ssh_swarm_test
-      networks:
-        - proxy
-    environment:
-      DOMAIN: example.swarm-test.autonomic.zone # UPDATE ME
-      STACK_NAME: example_com  # UPDATE ME
-      LETS_ENCRYPT_ENV: production
+- name: deployment
+  image: git.coopcloud.tech/coop-cloud/stack-ssh-deploy:latest
+  settings:
+    host: swarm-test.autonomic.zone
+    stack: garage
+    generate_secrets: true
+    purge: true
+    deploy_key:
+      from_secret: drone_ssh_swarm_test
+    networks:
+    - proxy
+  environment:
+    DOMAIN: garage.swarm-test.autonomic.zone
+    STACK_NAME: garage
+    LETS_ENCRYPT_ENV: production
+    SECRET_RPC_SECRET_VERSION: v1 # length=64 charset=hex
+    SECRET_ADMIN_TOKEN_SECRET_VERSION: v1 # length=64 charset=hex
+    SECRET_METRICS_TOKEN_SECRET_VERSION: v1 # length=64 charset=hex
 trigger:
   branch:
-    - main
+  - main
 ---
 kind: pipeline
 name: generate recipe catalogue
 steps:
-  - name: release a new version
-    image: plugins/downstream
-    settings:
-      server: https://build.coopcloud.tech
-      token:
-        from_secret: drone_abra-bot_token
-      fork: true
-      repositories:
-        - coop-cloud/auto-recipes-catalogue-json
+- name: release a new version
+  image: plugins/downstream
+  settings:
+    server: https://build.coopcloud.tech
+    token:
+      from_secret: drone_abra-bot_token
+    fork: true
+    repositories:
+    - toolshed/auto-recipes-catalogue-json
 
 trigger:
   event: tag

.env.sample

@@ -5,18 +5,32 @@ DOMAIN=garage.example.com
 LETS_ENCRYPT_ENV=production
 COMPOSE_FILE="compose.yml"
 
-SECRET_RPC_SECRET_VERSION=v1
+SECRET_RPC_SECRET_VERSION=v1 # length=64 charset=hex
+SECRET_ADMIN_TOKEN_SECRET_VERSION=v1 # length=64 charset=hex
+SECRET_METRICS_TOKEN_SECRET_VERSION=v1 # length=64 charset=hex
 
- # Changing the replication factor after initial deployment is not 
- # supported and requires deleting the existing cluster layout metadata.
+#COMPOSE_FILE="$COMPOSE_FILE:compose.monitoring.yml"
+#MONITORING_ENABLED=true
+
+# Changing the replication factor after initial deployment is not 
+# supported and requires deleting the existing cluster layout metadata.
 REPLICATION_FACTOR=2
 
+DATABASE_ENGINE=lmdb
 CONSISTENCY_MODE=consistent
 METADATA_FSYNC=false
 DATA_FSYNC=false
 DISABLE_SCRUB=false
 BLOCK_SIZE=1MiB # only increase if there is a fast network connection between nodes
 
+## Bootstrap this node in an existing Garage cluster 
+#BOOTSTRAP_HOST=""
+#BOOTSTRAP_ID=""
+#BOOTSTRAP_PORT=3901
+
 # Use a directory on the host instead of a docker volume for storage
 #LOCAL_FOLDER_META=/path/on/docker/host
-#LOCAL_FOLDER_DATA=/path/on/docker/host
+#LOCAL_FOLDER_DATA=/path/on/docker/host
+
+## Enable Full Data Backups (not just metadata)
+# COMPOSE_FILE="$COMPOSE_FILE:compose.fullbackup.yml"

README.md

@@ -1,56 +1,106 @@
-# garage
+# Garage
 
 > An open-source distributed object storage service tailored for selfhosting at a small-to-medium scale.
 
 <!-- metadata -->
 
 * **Category**: Apps
-* **Status**: wip
+* **Status**: 3
 * **Image**: [`garage`](https://hub.docker.com/r/dxflrs/garage), 4, upstream
-* **Healthcheck**: No
+* **Healthcheck**: Yes
 * **Backups**: No
-* **Email**: No
-* **Tests**: No
-* **SSO**: No
+* **Email**: N/A
+* **Tests**: 3
+* **SSO**: N/A
 
 <!-- endmetadata -->
 
 ## Quick start
 
-* `abra app new garage`
-* Garage is particular about the rpc secret, generate it locally with `openssl rand -hex 32` then insert the result
-* `abra app secret i <app-domain> rpc_secret v1 <rpc-secret>`
-> Note: all nodes must share the same rpc secret, do not lose this value if you plan to cluster garage!
-* `abra app config <app-domain>`
-* `abra app deploy <app-domain>`
+- `abra app new garage`
+- If you are **creating a new cluster**:
+    - Generate a new rpc_secret: `abra app secret generate --all`
+        - Note: all nodes must share the same rpc secret, do not lose this value if you plan to cluster garage!
+        - Note: In older versions of abra you must generate the secret locally with `openssl rand -hex 32` then insert the result as described below
+    - `abra app config <app-domain>`
+- If this Garage node is **joining an existing cluster**:
+    - Insert the existing rpc_secret: `abra app secret insert <app-domain> rpc_secret v1 <rpc-secret>`
+    - `abra app config <app-domain>`
+        - Uncomment the block that starts with `## Bootstrap this node`
+        - Set `BOOTSTRAP_HOST` and `BOOTSTRAP_ID`
+- `abra app deploy <app-domain>`
 
-## Peering
+## Configuration
 
-#### Garage CLI
-Start by creating an alias for the abra run command
+### Allow RPC Connections
+
+* Your ingress controller must be set up to allow connections on port 3901. We assume you're using Traefik
+* `abra app configure <traefik-app-name>`
+* Uncomment the block that starts with `## Garage`
+* Re-deploy Traefik: `abra app undeploy -n <traefik-app-name> && sleep 5 && abra app deploy -n <traefik-app-name>`
+
+### Prepare the Garage Client
+To interact with garage inside docker, it's best to create an alias for the following abra run command.
 ```
-alias garage="abra app run <app-domain> app /garage"
+alias garage="abra app run <app domain> -- app /garage"
 ```
-Run `garage status` to verify everything is working
+Run `garage status` to verify everything is working.
 
-#### Assign Roles
+You can optionally add this alias to your `.bashrc` (or similar) file to avoid having to define it repeatedly.
 
-Terms:
-* `node id` (reqired) - Node identifier supplied by the garage CLI, can be found by running `garage node id`.
-* `zone` (reqired) - Identifier for how nodes will be grouped, a zone usually refers to a geographical location (us-east, paris-1, etc.) no specific syntax is required, zones can be called anything.
-* `capacity` (reqired) - Disk space the node will be allocating to the cluster, use T and G for units (Terabytes and Gigabytes respectively).
-* `tag` (optional) - Additional notes appended to garage status, usually a title for the node.
 
-> Role assignment command conflicts with `abra app run`'s -t option\
-> Connecting not currently implemented
+### Garage Quick Start Guide
+Once `garage status` works, you can follow the guide here: https://garagehq.deuxfleurs.fr/documentation/quick-start/#checking-that-garage-runs-correctly
+
+## Monitoring
+
+### Enabling
+
+By default monitoring is disabled and must be enabled in your config.
+
+To enable, set `MONITORING` to `true` and uncomment the line `#COMPOSE_FILE="$COMPOSE_FILE:compose.monitoring.yml"`.
+
+> If you've deployed garage before ver `0.0.2+v2.3.0` then you will need to add the following lines to your config:
+> ```
+> MONITORING_DOMAIN=monitoring.garage.example.com
+> SECRET_ADMIN_TOKEN_SECRET_VERSION=v1 # length=64 charset=hex
+> SECRET_METRICS_TOKEN_SECRET_VERSION=v1 # length=64 charset=hex
+> 
+> #COMPOSE_FILE="$COMPOSE_FILE:compose.monitoring.yml"
+> MONITORING="true"
+> ```
+
+If you're using the
+[monitoring-ng](https://recipes.coopcloud.tech/monitoring-ng) recipe,
+insert the `metrics_token` with the value of `basic_auth`:
+
+```sh
+abra app secret insert garage.example.coop v1 metrics_token BASIC_AUTH
+```
+
+### Deploying
+
+Now, undeploy the service, generate the new secrets, and finally re-deploy:
+```
+abra app undeploy <app-domain>
+abra app secret generate --all <app-domain>
+abra app deploy <app-domain>
+```
+### Utilizing metrics
+
+Within your chosen monitoring software (ie. Telegraf, Prometheus, etc.), you'll need to make sure it interprets the correct scheme (https), and point it at <app-domain>/metrics as the monitoring endpoint. The secret you copied earlier called metrics_token will be used to authenticate the request.
 
 ## Backups
 
-> Not currently implemented
+> In development, not currently reliable
 
-Backups will only capture a snapshot of the metadata directory, which includes bucket names, hashed secrets, and other related information. However, they do not include the actual data!
+By default, backups will only capture a snapshot of the metadata directory, which includes bucket names, hashed secrets, and other related information. 
+By default, the actual data will not be backed up!
+If you're running Garage in a cluster, when you restore the metadata, other nodes will provide any missing data (assuming a replication factor >1).
 
-If you're running Garage in a cluster, when you restore the metadata, other nodes will send the new node any missing data.\
-Finally, please note that Abra backups are not a substitute for a proper data replication strategy, and it's recommended to run Garage in a cluster if you need data redundancy.
+### To enable full data backups
+* `abra app config <app domain>`
+* Uncomment the block that starts with `## Enable Full Data Backups`
+* Re-deploy Garage: `abra app undeploy -n <app domain> && sleep 5 && abra app deploy -n <app domain>`
 
 For more, see [`garagehq.deuxfleurs.fr`](https://garagehq.deuxfleurs.fr/documentation/cookbook/real-world/).

abra.sh

@@ -1 +1 @@
-export GARAGE_CONF_VERSION=v4
+export GARAGE_CONF_VERSION=v7

compose.fullbackup.yml

@@ -0,0 +1,9 @@
+---
+version: "3.8"
+
+services:
+  app:
+    deploy:
+      labels:
+        - "backupbot.backup=true"
+        - "backupbot.backup.path=/var/lib/garage/meta,/var/lib/garage/data"

compose.monitoring.yml

@@ -0,0 +1,29 @@
+---
+version: "3.8"
+
+services:
+  app:
+    secrets:
+      - source: metrics_token
+        mode: 0600
+      - source: admin_token
+        mode: 0600
+    deploy:
+      labels:
+        - "traefik.http.routers.${STACK_NAME}-metrics.rule=Host(`${DOMAIN}`) && Path(`/metrics`)"
+        - "traefik.http.routers.${STACK_NAME}-metrics.entrypoints=web-secure"
+        - "traefik.http.routers.${STACK_NAME}-metrics.tls.certresolver=${LETS_ENCRYPT_ENV}"
+        - "traefik.http.routers.${STACK_NAME}-metrics.service=${STACK_NAME}-metrics"
+        - "traefik.http.services.${STACK_NAME}-metrics.loadbalancer.server.port=3903"
+        - "prometheus.io/scrape=true"
+        - "prometheus.io/port=3903"
+        - "prometheus.io/path=/metrics"
+        - "prometheus.io/auth=bearer"
+
+secrets:
+  admin_token:
+    name: ${STACK_NAME}_admin_token_${SECRET_ADMIN_TOKEN_SECRET_VERSION}
+    external: true
+  metrics_token:
+    name: ${STACK_NAME}_metrics_token_${SECRET_METRICS_TOKEN_SECRET_VERSION}
+    external: true

compose.yml

@@ -3,14 +3,17 @@ version: "3.8"
 
 services:
   app:
-    image: dxflrs/garage:v1.0.0
+    image: dxflrs/garage:v2.3.0
+    hostname: "${DOMAIN}"
     configs:
       - source: garage_conf
         target: /etc/garage.toml
     secrets:
-      - rpc_secret
+      - source: rpc_secret
+        mode: 0600
     networks:
       - proxy
+      - internal
     deploy:
       restart_policy:
         condition: on-failure
@@ -20,14 +23,28 @@ services:
         - "traefik.http.routers.${STACK_NAME}.rule=Host(`${DOMAIN}`)"
         - "traefik.http.routers.${STACK_NAME}.entrypoints=web-secure"
         - "traefik.http.routers.${STACK_NAME}.tls.certresolver=${LETS_ENCRYPT_ENV}"
-        - "coop-cloud.${STACK_NAME}.version=0.0.1+1.0.0"
+        - "traefik.http.routers.${STACK_NAME}.service=${STACK_NAME}"
+        - "traefik.tcp.routers.${STACK_NAME}-rpc.rule=HostSNI(`*`)"
+        - "traefik.tcp.routers.${STACK_NAME}-rpc.entrypoints=garage-rpc"
+        - "traefik.tcp.services.${STACK_NAME}-rpc.loadbalancer.server.port=3901"
+        - "coop-cloud.${STACK_NAME}.version=0.1.0+v2.3.0"
+        - "backupbot.backup=true"
+        - "backupbot.backup.pre-hook=/garage meta snapshot --all"
+        - "backupbot.backup.path=/var/lib/garage/meta/snapshots/,/var/lib/garage/meta/cluster_layout,/var/lib/garage/meta/data_layout,/var/lib/garage/meta/node_key,/var/lib/garage/meta/node_key.pub"
     volumes:
       - "${LOCAL_FOLDER_META:-meta}:/var/lib/garage/meta"
       - "${LOCAL_FOLDER_DATA:-data}:/var/lib/garage/data"
+    healthcheck:
+      test: ["CMD", "/garage", "status"]
+      interval: 30s
+      timeout: 10s
+      retries: 10
+      start_period: 10s
 
 networks:
   proxy:
     external: true
+  internal:
 
 configs:
   garage_conf:
@@ -43,4 +60,4 @@ secrets:
 volumes:
   meta:
   data:
-  conf:
+  conf:

garage.toml.tmpl

@@ -1,6 +1,6 @@
 metadata_dir = "/var/lib/garage/meta"
 data_dir = "/var/lib/garage/data"
-db_engine = "lmdb"
+db_engine = "{{ if env "DATABASE_ENGINE" }}{{ env "DATABASE_ENGINE" }}{{ else }}lmdb{{ end }}"
 metadata_auto_snapshot_interval = "6h"
 
 replication_factor = {{ env "REPLICATION_FACTOR" }}
@@ -13,10 +13,25 @@ block_size = '{{ env "BLOCK_SIZE" }}'
 compression_level = 2
 
 rpc_bind_addr = "[::]:3901"
+rpc_public_addr = "{{ env "DOMAIN" }}:3901"
 rpc_addr = "[::]:3901"
-rpc_secret = "{{ secret "rpc_secret" }}"
+rpc_secret_file = "/run/secrets/rpc_secret"
+
+{{ if ne (env "BOOTSTRAP_ID") "" }}
+bootstrap_peers = [
+    "{{ env "BOOTSTRAP_ID" }}@{{ env "BOOTSTRAP_HOST" }}:{{ env "BOOTSTRAP_PORT" }}"
+]
+{{ end }}
 
 [s3_api]
 s3_region = "garage"
 api_bind_addr = "[::]:3900"
-root_domain = ".s3.garage"
+root_domain = ".s3.garage"
+
+{{ if eq (env "MONITORING_ENABLED") "true" }}
+[admin]
+api_bind_addr = "[::]:3903"
+admin_token_file = "/run/secrets/admin_token"
+metrics_require_token = true
+metrics_token_file = "/run/secrets/metrics_token"
+{{ end }}

release/0.0.1+2.1.0

@@ -0,0 +1 @@
+unstable release

renovate.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": [
+    "config:recommended"
+  ]
+}