docs: define merge policy and maintainer roles

<!--
Thank you for doing recipe maintenance work!
Please mark all checklist items which are relevant for your changes.
Please remove the checklist items which are not relevant for your changes.
Feel free to remove this comment.
-->

* [x] I have deployed and tested my changes
* [ ] I have [updated relevant versions in `abra.sh`](https://docs.coopcloud.tech/maintainers/upgrade/#updating-versions-in-the-abrash)
* [x] I have made my environment variable changes [backwards compatible](https://docs.coopcloud.tech/maintainers/upgrade/#backwards-compatible-environment-variable-changes)
* [ ] I have added a [release note entry](https://docs.coopcloud.tech/maintainers/upgrade/#creating-new-release-notes)

Reviewed-on: coop-cloud/traefik#126
Reviewed-by: p4u1 <133+p4u1@noreply.git.coopcloud.tech>
Co-authored-by: f <f@sutty.nl>

.env.sample

@@ -15,6 +15,13 @@ LOG_MAX_AGE=1
 # This is here so later lines can extend it; you likely don't wanna edit
 COMPOSE_FILE="compose.yml"
 
+# Increase read timeout (or change it to 0s) to ensure large file
+# uploads work.
+#
+# https://doc.traefik.io/traefik/reference/install-configuration/entrypoints/#opt-transport-respondingTimeouts-readTimeout
+READ_TIMEOUT=60s
+WRITE_TIMEOUT=0s
+
 #####################################################################
 # General settings                                                  #
 #####################################################################
@@ -38,7 +45,7 @@ COMPOSE_FILE="compose.yml"
 ## Enable dns challenge (for wildcard domains)
 ##   https://go-acme.github.io/lego/dns/#dns-providers
 #LETS_ENCRYPT_DNS_CHALLENGE_ENABLED=1
-## *Currently* one of ovh, gandi, gandiv5, digitalocean, azure, porkbun.
+## *Currently* one of ovh, gandi, gandiv5, digitalocean, azure, porkbun, and cloudflare.
 ## Uncomment the corresponding provider below to insert your secret token/key.
 #LETS_ENCRYPT_DNS_CHALLENGE_PROVIDER=ovh
 
@@ -47,25 +54,25 @@ COMPOSE_FILE="compose.yml"
 #OVH_ENABLED=1
 #OVH_APPLICATION_KEY=
 #OVH_ENDPOINT=
-#SECRET_OVH_APP_SECRET_VERSION=v1
-#SECRET_OVH_CONSUMER_KEY=v1
+#SECRET_OVH_APP_SECRET_VERSION=v1 # generate=false
+#SECRET_OVH_CONSUMER_KEY=v1 # generate=false
 
 ## Gandi, https://gandi.net
 ## note(3wc): only "V5" (new) API is supported, so far
 #COMPOSE_FILE="$COMPOSE_FILE:compose.gandi-api-key.yml"
 #GANDI_API_KEY_ENABLED=1
-#SECRET_GANDIV5_API_KEY_VERSION=v1
+#SECRET_GANDIV5_API_KEY_VERSION=v1 # generate=false
 
 ## Gandi, https://gandi.net
 ## note: uses GandiV5 Personal Access Token
 #COMPOSE_FILE="$COMPOSE_FILE:compose.gandi-personal-access-token.yml"
 #GANDI_PERSONAL_ACCESS_TOKEN_ENABLED=1
-#SECRET_GANDIV5_PERSONAL_ACCESS_TOKEN_VERSION=v1
+#SECRET_GANDIV5_PERSONAL_ACCESS_TOKEN_VERSION=v1 # generate=false
 
 ## DigitalOcean, https://digitalocean.com
 #COMPOSE_FILE="$COMPOSE_FILE:compose.digitalocean.yml"
 #DIGITALOCEAN_ENABLED=1
-#SECRET_DIGITALOCEAN_AUTH_TOKEN_VERSION=v1
+#SECRET_DIGITALOCEAN_AUTH_TOKEN_VERSION=v1 # generate=false
 
 ## Azure, https://azure.com
 ## To insert your Azure client secret:
@@ -76,24 +83,26 @@ COMPOSE_FILE="compose.yml"
 #AZURE_CLIENT_ID=
 #AZURE_SUBSCRIPTION_ID=
 #AZURE_RESOURCE_GROUP=
-#SECRET_AZURE_SECRET_VERSION=v1
+#SECRET_AZURE_SECRET_VERSION=v1 # generate=false
 
 ## Porkbun, https://porkbun.com
 ## To insert your secrets:
 ## abra app secret insert 1312.net pb_api_key v1 pk1_413
 ## abra app secret insert 1312.net pb_s_api_key v1 sk1_612
 #COMPOSE_FILE="$COMPOSE_FILE:compose.porkbun.yml"
-#SECRET_PORKBUN_API_KEY_VERSION=v1
-#SECRET_PORKBUN_SECRET_API_KEY_VERSION=v1
+#SECRET_PORKBUN_API_KEY_VERSION=v1 # generate=false
+#SECRET_PORKBUN_SECRET_API_KEY_VERSION=v1 # generate=false
 
 ## Cloudflare, htps://cloudflare.com
 ## To insert your secrets:
-## abra app secret insert {myapp.example.coop} cf_email v1 "<CLOUDFLARE_EMAIL>"
-## abra app secret insert {myapp.example.coop} cf_api_key v1 "<CLOUDFLARE_API_KEY>"
-## cf_api_key is an account API key from Cloudflare that has DNS read + edit permission
+## abra app secret insert {myapp.example.coop} cf_dns_token v1 "<CLOUDFLARE_DNS_API_TOKEN>"
+## abra app secret insert {myapp.example.coop} cf_zone_token v1 "<CLOUDFLARE_ZONE_API_TOKEN>"
+## These can be the same token or different tokens
+## cf_dns_token needs DNS edit access, cf_zone_token needs zone edit access
+## See LEGO docs for more info: https://go-acme.github.io/lego/dns/cloudflare/index.html
 #COMPOSE_FILE="$COMPOSE_FILE:compose.cloudflare.yml"
-#SECRET_CLOUDFLARE_EMAIL_VERSION=v1 # generate=false
-#SECRET_CLOUDFLARE_API_KEY_VERSION=v1 # generate=false
+#SECRET_CLOUDFLARE_DNS_API_TOKEN_VERSION=v1 # generate=false
+#SECRET_CLOUDFLARE_ZONE_API_TOKEN_VERSION=v1 # generate=false
 
 #####################################################################
 # Manual wildcard certificate insertion                             #
@@ -150,6 +159,10 @@ COMPOSE_FILE="compose.yml"
 #COMPOSE_FILE="$COMPOSE_FILE:compose.smtp.yml"
 #SMTP_ENABLED=1
 
+## PGSQL recipe open port 5432
+#COMPOSE_FILE="$COMPOSE_FILE:compose.pgsql.yml"
+#PGSQL_ENABLED=1
+
 ## Compy
 #COMPOSE_FILE="$COMPOSE_FILE:compose.compy.yml"
 #COMPY_ENABLED=1
@@ -212,6 +225,13 @@ COMPOSE_FILE="compose.yml"
 #ANUBIS_OG_EXPIRY_TIME=1h
 #ANUBIS_OG_CACHE_CONSIDER_HOST=true
 #ANUBIS_SERVE_ROBOTS_TXT=true
+#ANUBIS_SLOG_LEVEL=INFO
+
+## Anubis metrics
+#COMPOSE_FILE="$COMPOSE_FILE:compose.anubis-metrics.yml"
 
 ## Enable onion service support
 #ONION_ENABLED=1
+
+## Access logs
+#COMPOSE_FILE="$COMPOSE_FILE:compose.access-log.yml"

MAINTENANCE.md

@@ -3,6 +3,19 @@
 All contributions should be made via a pull request. This is to ensure a
 certain quality and consistency, that others can rely on.
 
+## Roles
+
+We differentiate between two roles:
+
+- **Maintainers** take responsibility for the recipe. They are listed in the
+  [README.md](./README.md), are members of the
+  [traefik maintainers team](https://git.coopcloud.tech/org/coop-cloud/teams/traefik-maintainers)
+  and fulfil the responsibilities described below.
+- **Contributors with merge access** Trusted people can open pull requests and merge them
+  themselves in the cases described in [Pull Requests](#pull-requests).
+
+Being allowed to merge a pull request does not make somebody a maintainer.
+
 ## Maintainer Responsibilities
 
 A recipe maintainer has the following responsibilities:
@@ -11,21 +24,74 @@ A recipe maintainer has the following responsibilities:
 - Make image security updates within a week
 - Make image major updates every three months
 
-In order to fullfill these responsibilities a recipe maintainer:
+In order to fulfill these responsibilities a recipe maintainer:
 
 - Has to watch the repository (to get notifications)
 - Needs to make sure renovate is configured properly
 
 ## Pull Requests
 
-A pull request can be merged if it is approved by at least one maintainer. For
-pull requests opened by a maintainer they need to be approved by another
-maintainer. Even though it is okay to merge a pull request with one approval, it
-is always better if all maintainers looked at the pull request and approved it.
+As a rule, a pull request can be merged once it has been approved by at least
+one maintainer other than its author. The exceptions below exist so that
+security fixes and routine updates don't get stuck waiting for a review.
+
+| Type of change | Approval needed |
+| --- | --- |
+| Security fix | No, can be merged immediately |
+| Regular update | No, after a review window of about one week |
+| Feature, extension or change of the default configuration | Yes, always |
+| Small change that can't break the recipe | No |
+
+### Security fixes
+
+If a pull request contains a relevant security fix, the person who opened it is
+allowed to merge it directly, without approval and without waiting.
+
+The same applies to a pull request that fixes an update which contains a
+security fix: if a version bump can't be merged as it is, because the new
+version needs changes to the configuration, then the pull request that
+makes that update work can be merged directly as well. Otherwise a broken
+update would block a security fix.
+
+Keep these pull requests as small as possible, so they contain nothing but what
+is needed to get the fix out.
+
+### Regular updates
+
+If a pull request rolls out a regular update, there is a time window of about
+one week for other maintainers to review it and to request changes. If no other
+maintainer is available within this time window, the person who opened it is
+allowed to merge it without approval.
+
+### Features, extensions and default configuration
+
+Any pull request that adds a feature or an extension, or changes the default
+configuration, needs an approval, no matter who opened it. These are the
+changes most likely to break existing deployments.
+
+### Small changes
+
+Small changes that definitely won't break the recipe can be merged without
+approval, for example:
+
+- a new environment variable that is commented out by default
+- a new `abra.sh` function
+- changes to the [README.md](./README.md)
+- writing new tests
+- configuring renovate
+
+If a pull request falls into more than one of these categories, the stricter
+rule applies. If you are unsure which category a pull request belongs to, ask
+for an approval.
+
+Even though it is okay to merge a pull request with a single approval, it is
+always better if all maintainers looked at the pull request and approved it.
 
 ## Become a maintainer
 
 Everyone can apply to be a recipe maintainer:
+
 1. Watch the repository to always get updates
 2. Simply add your self to the list in the [README.md](./README.md) and open a new pull request with the change.
 3. Once the pull request gets merged you will be added to the [traefik maintainers team](https://git.coopcloud.tech/org/coop-cloud/teams/traefik-maintainers).
+4. Join the room [#cc-|-traefik-maintenance:matrix.org](https://matrix.to/#/%23cc-%7C-traefik-maintenance:matrix.org) and chat to other maintainers.

README.md

@@ -5,7 +5,7 @@
 > https://docs.traefik.io
 
 <!-- metadata -->
-* **Maintainer**: [@p4u1](https://git.coopcloud.tech/p4u1), [@decentral1se](https://git.coopcloud.tech/decentral1se), [@javielico](https://git.coopcloud.tech/javielico), Local-IT: [@moritz](https://git.coopcloud.tech/moritz), [@msimon](https://git.coopcloud.tech/simon), [@carla](https://git.coopcloud.tech/carla)
+* **Maintainer**: [@p4u1](https://git.coopcloud.tech/p4u1), [@javielico](https://git.coopcloud.tech/javielico), Local-IT: [@moritz](https://git.coopcloud.tech/moritz), [@msimon](https://git.coopcloud.tech/simon), [@carla](https://git.coopcloud.tech/carla)
 * **Status**: `stable`
 * **Category**: Utilities
 * **Features**: ?
@@ -32,15 +32,16 @@
 3. Insert the secret: `abra app secret insert <domain> usersfile v1 -f usersfile
 4. Redploy your app: `abra app deploy -f <domain>`
 
-## Configuring wildcard SSL using DNS
+## Configuring SSL using DNS
 
-Automatic certificate generation will Just Work™ for most recipes  which use a fixed
-number of subdomains. For some recipes which need to work across arbitrary
+Automatic certificate generation will Just Work™ for most recipes which use a
+fixed number of subdomains. If your server can't be reached from the Internet,
+or if you're deploying a recipe that needs to work across arbitrary
 subdomains, like
 [`federatedwiki`](https://git.coopcloud.tech/coop-cloud/federatedwiki/) and
-[`go-ssb-room`](https://git.coopcloud.tech/coop-cloud/federatedwiki/), you'll
-need to give Traefik access to your DNS provider so that it can carry out
-Letsencrypt DNS challenges.
+[`go-ssb-room`](https://git.coopcloud.tech/coop-cloud/federatedwiki/) (requiring
+the use of wildcard certificates,) you can give Traefik access to your DNS provider
+so that it can carry out Letsencrypt DNS challenges.
 
 1. Use Gandi, OVH, DO, Azure, or PorkBun for DNS 🤡 (support for other providers
    can be easily added, see
@@ -71,8 +72,27 @@ After deploying these changes, go to each recipe that supports Anubis
 and follow the process there.  **Enabling Anubis here is not enough for
 protection your apps.**
 
+If you want to collect Prometheus metrics for Anubis, for instance with
+[monitoring-ng](/monitoring-ng), uncomment the "Anubis metrics" section.
+
 ## Enabling onion service
 
 Uncomment the line in the config setting `ONION_ENABLED=1`. This will create a new entrypoint on port 9052 which can be used to bypass forced SSL. For more details, see the [onion recipe](https://recipes.coopcloud.tech/onion).
 
 [`abra`]: https://git.autonomic.zone/autonomic-cooperative/abra
+
+## Access logs
+
+To keep access logs on a volume, uncomment the "Access logs" section.
+
+You'll need to setup rotation yourself and send the USR1 signal to
+Traefik for reloading.  For instance, with `logrotate:
+
+```
+# /etc/logrotate.d/traefik.conf
+/var/lib/docker/volumes/traefik_SERVICE_NAME_access-logs/_data/access_log.jsonl {
+  postrotate
+    pkill -USR1 traefik
+  endscript
+}
+```

abra.sh

@@ -1,3 +1,4 @@
-export TRAEFIK_YML_VERSION=v30
+export TRAEFIK_YML_VERSION=v33
 export FILE_PROVIDER_YML_VERSION=v12
 export ENTRYPOINT_VERSION=v5
+export ANUBIS_YML_VERSION=v1

anubis.yml.tmpl

@@ -0,0 +1,7 @@
+bots:
+- import: (data)/meta/default-config.yaml
+{{ if eq (env "ANUBIS_METRICS_ENABLED") "true" }}
+metrics:
+  bind: ":9090"
+  network: "tcp"
+{{ end }}

compose.access-log.yml

@@ -0,0 +1,10 @@
+---
+version: "3.8"
+services:
+  app:
+    environment:
+      ACCESS_LOG_ENABLED: "true"
+    volumes:
+      - "access-logs:/var/log/"
+volumes:
+  access-logs:

compose.anubis-metrics.yml

@@ -0,0 +1,11 @@
+---
+version: "3.8"
+services:
+  anubis:
+    environment:
+      ANUBIS_METRICS_ENABLED: "true"
+    deploy:
+      labels:
+      - "prometheus.io/scrape=true"
+      - "prometheus.io/port=9090"
+      - "prometheus.io/path=/metrics"

compose.anubis.yml

@@ -5,8 +5,9 @@ services:
     deploy:
       labels:
       - "traefik.http.middlewares.anubis.forwardauth.address=http://anubis:8080/.within.website/x/cmd/anubis/api/check"
+      - "traefik.http.middlewares.anubis.forwardauth.trustForwardHeader=true"
   anubis:
-    image: "ghcr.io/techarohq/anubis:v1.25.0"
+    image: "ghcr.io/techarohq/anubis:v1.27.0"
     environment:
       BIND: ":8080"
       TARGET: " "
@@ -17,6 +18,11 @@ services:
       OG_EXPIRY_TIME: "${ANUBIS_OG_EXPIRY_TIME}"
       OG_CACHE_CONSIDER_HOST: "${ANUBIS_OG_CACHE_CONSIDER_HOST}"
       SERVE_ROBOTS_TXT: "${ANUBIS_SERVE_ROBOTS_TXT}"
+      SLOG_LEVEL: "${ANUBIS_SLOG_LEVEL:-INFO}"
+      POLICY_FNAME: "/data/cfg/botPolicy.yaml"
+    configs:
+    - source: anubis_yml
+      target: /data/cfg/botPolicy.yaml
     networks:
     - proxy
     deploy:
@@ -27,3 +33,8 @@ services:
       - "traefik.http.routers.anubis.entrypoints=web-secure"
       - "traefik.http.services.anubis.loadbalancer.server.port=8080"
       - "traefik.http.routers.anubis.service=anubis"
+configs:
+  anubis_yml:
+    name: ${STACK_NAME}_anubis_yml_${ANUBIS_YML_VERSION}
+    file: anubis.yml.tmpl
+    template_driver: golang

compose.cloudflare.yml

@@ -3,16 +3,16 @@ version: "3.8"
 services:
   app:
     environment:
-      - CLOUDFLARE_EMAIL_FILE=/run/secrets/cf_email
-      - CLOUDFLARE_API_KEY_FILE=/run/secrets/cf_api_key
+      - CLOUDFLARE_DNS_API_TOKEN_FILE=/run/secrets/cf_dns_token
+      - CLOUDFLARE_ZONE_API_TOKEN_FILE=/run/secrets/cf_zone_token
     secrets:
-      - cf_email
-      - cf_api_key
-  
+      - cf_dns_token
+      - cf_zone_token
+
 secrets:
-  cf_email:
-    name: ${STACK_NAME}_cf_email_${SECRET_CLOUDFLARE_EMAIL_VERSION}
+  cf_dns_token:
+    name: ${STACK_NAME}_cf_dns_token_${SECRET_CLOUDFLARE_DNS_API_TOKEN_VERSION}
     external: true
-  cf_api_key:
-    name: ${STACK_NAME}_cf_api_key_${SECRET_CLOUDFLARE_API_KEY_VERSION}
+  cf_zone_token:
+    name: ${STACK_NAME}_cf_zone_token_${SECRET_CLOUDFLARE_ZONE_API_TOKEN_VERSION}
     external: true

compose.pgsql.yml

@@ -0,0 +1,12 @@
+---
+version: "3.8"
+
+services:
+  app:
+    environment:
+      - PGSQL_ENABLED
+    ports:
+      - target: 5432
+        published: 5432
+        protocol: tcp
+        mode: host

compose.yml

@@ -3,7 +3,7 @@ version: "3.8"
 
 services:
   app:
-    image: "traefik:v3.6.15"
+    image: "traefik:v3.7.10"
     # Note(decentral1se): *please do not* add any additional ports here.
     # Doing so could break new installs with port conflicts. Please use
     # the usual `compose.$app.yml` approach for any additional ports
@@ -34,6 +34,8 @@ services:
       - DASHBOARD_ENABLED
       - LOG_LEVEL
       - ${LOG_MAX_AGE:-0}
+      - READ_TIMEOUT=${READ_TIMEOUT:-60s}
+      - WRITE_TIMEOUT=${WRITE_TIMEOUT:-0s}
     healthcheck:
       test: ["CMD", "traefik", "healthcheck"]
       interval: 30s
@@ -55,12 +57,12 @@ services:
         - "traefik.http.routers.${STACK_NAME}.tls.certresolver=${LETS_ENCRYPT_ENV}"
         - "traefik.http.routers.${STACK_NAME}.service=api@internal"
         - "traefik.http.routers.${STACK_NAME}.middlewares=security@file"
-        - "coop-cloud.${STACK_NAME}.version=5.1.1+v3.6.15"
+        - "coop-cloud.${STACK_NAME}.version=6.1.0+v3.7.10"
         - "coop-cloud.${STACK_NAME}.timeout=${TIMEOUT}"
         - "backupbot.backup=${ENABLE_BACKUPS:-true}"
 
   socket-proxy:
-    image: lscr.io/linuxserver/socket-proxy:3.2.19
+    image: lscr.io/linuxserver/socket-proxy:3.4.3
     deploy:
       endpoint_mode: dnsrr
     environment:
@@ -91,6 +93,7 @@ services:
       - TASKS=1 # Needs access
       - VERSION=1 # Needs access
       - VOLUMES=0
+      - LOG_LEVEL=warning
     volumes:
       - /var/run/docker.sock:/var/run/docker.sock:ro
     networks:

release/6.0.0+v3.7.7

@@ -0,0 +1,13 @@
+!Breaking: Starting with v3.6.16, the Docker provider requires Docker API version v1.40 or above (Docker Engine v19.03). Users running older (end of life) versions of Docker Engine should update their Docker Engine or use the DOCKER_API_VERSION environment variable to override the API version used by Traefik.
+
+letsencrypt: Avoid HTTP-01 challenge if `LETS_ENCRYPT_DNS_CHALLENGE_ENABLED` is set, in order to rely on DNS-01 challenges for servers not exposed to the internet.
+
+matrix-federation: Entrypoint was changed to :8448 to match published port
+
+fix: ensure large uploads work. You can now set the following env vars:
+- READ_TIMEOUT
+- WRITE_TIMEOUT
+
+cloudflare: Add Cloudflare as DNS provider
+
+For more information take a look at the migration guide: https://doc.traefik.io/traefik/v3.7/migrate/v3/#v377

release/6.1.0+v3.7.10

@@ -0,0 +1 @@
+Adds option ability to open ports for PGSQL recipe, new version of anubis, and ability to add anubis metrics on this release.

traefik.yml.tmpl

@@ -6,6 +6,21 @@ log:
   level: {{ env "LOG_LEVEL" }}
   maxAge: {{ env "LOG_MAX_AGE" }}
 
+{{ if eq (env "ACCESS_LOG_ENABLED") "true" }}
+accessLog:
+  format: "json"
+  filePath: "/var/log/access_log.jsonl"
+  fields:
+    defaultMode: "keep"
+    headers:
+      defaultMode: "keep"
+      names:
+        Authorization: "drop"
+        Cookie: "drop"
+    queryParameters:
+      defaultMode: "keep"
+{{ end }}
+
 providers:
   swarm:
     endpoint: "tcp://socket-proxy:2375"
@@ -33,6 +48,10 @@ entrypoints:
           to: web-secure
   web-secure:
     address: ":443"
+    transport:
+      respondingTimeouts:
+        readTimeout: {{ env "READ_TIMEOUT" }}
+        writeTimeout: {{ env "WRITE_TIMEOUT" }}
     http:
       encodedCharacters:
         allowEncodedSlash: true
@@ -96,7 +115,7 @@ entrypoints:
   {{- end }}
   {{- if eq (env "MATRIX_FEDERATION_ENABLED") "1" }}
   matrix-federation:
-    address: ":9001"
+    address: ":8448"
   {{- end }}
   {{- if eq (env "NEXTCLOUD_TALK_HPB_ENABLED") "1" }}
   nextcloud-talk-hpb:
@@ -127,8 +146,10 @@ certificatesResolvers:
       email: {{ env "LETS_ENCRYPT_EMAIL" }}
       storage: /etc/letsencrypt/staging-acme.json
       caServer: "https://acme-staging-v02.api.letsencrypt.org/directory"
+      {{- if ne (env "LETS_ENCRYPT_DNS_CHALLENGE_ENABLED") "1" }}
       httpChallenge:
         entryPoint: web
+      {{- end }}
       {{- if eq (env "LETS_ENCRYPT_DNS_CHALLENGE_ENABLED") "1" }}
       dnsChallenge:
         provider: {{ (env "LETS_ENCRYPT_DNS_CHALLENGE_PROVIDER") }}
@@ -140,8 +161,10 @@ certificatesResolvers:
     acme:
       email: {{ env "LETS_ENCRYPT_EMAIL" }}
       storage: /etc/letsencrypt/production-acme.json
+      {{- if ne (env "LETS_ENCRYPT_DNS_CHALLENGE_ENABLED") "1" }}
       httpChallenge:
         entryPoint: web
+      {{- end }}
       {{- if eq (env "LETS_ENCRYPT_DNS_CHALLENGE_ENABLED") "1" }}
       dnsChallenge:
         provider: {{ (env "LETS_ENCRYPT_DNS_CHALLENGE_PROVIDER") }}