Merge pull request 'additional-config-options' (#3)

Reviewed-on: https://git.coopcloud.tech/coop-cloud/mumble/pulls/3
(with some addl discussion on https://git.coopcloud.tech/coop-cloud/mumble/pulls/1)

we had some open concerns about env variables:
1. Whether it would be possible to unset variables in the container when they're unset in the config, therefore sidestepping the issue of setting defaults.
 - Resolution: that would be annoyingly complex to set up; https://docs.coopcloud.tech/maintainers/upgrade/#backwards-compatible-environment-variable-changes recommends providing defaults in `compose.yml`.

2. Whether having config options without a `MUMBLE_` prefix may cause naming collisions with other env variables or abra.
 - Resolution: probably fine because the env is specific to the app conainers.

.env.sample

@@ -12,3 +12,55 @@ COMPOSE_FILE="compose.yml"
 
 ## Web client
 #COMPOSE_FILE="$COMPOSE_FILE:compose.mumbleweb.yml"
+
+## Server Password
+# remember to set the server-pw secret:
+#  abra app secret insert <domain> server-pw v1
+#COMPOSE_FILE="$COMPOSE_FILE:compose.serverpassword.yml"
+#SECRET_SERVER_PASSWORD_VERSION=v1
+
+## SuperUser Password
+SECRET_SUPERUSER_PASSWORD_VERSION=v1
+
+#################
+# MUMBLE CONFIG #
+#################
+# Documentation for the following options can be found here:
+# https://github.com/mumble-voip/mumble/blob/v1.6.870/auxiliary_files/mumble-server.ini
+#WELCOME_TEXT="<br />Welcome to this server running <b>Mumble</b>.<br />Enjoy your stay!<br />"
+#BANDWIDTH=558000
+#TIMEOUT=30
+#USERS=100
+#USERS_PER_CHANNEL=0
+#MESSAGE_BURST=5
+#MESSAGE_LIMIT=1
+#PLUGIN_MESSAGE_LIMIT=1
+#PLUGIN_MESSAGE_BURST=5
+#ALLOW_PING=true
+#OPUS_THRESHOLD=0
+#CHANNEL_NESTING_LIMIT=10
+#CHANNEL_COUNT_LIMIT=1000
+#CHANNEL_NAME=[ \\-=\\w#\\[\\]\\{\\}\\(\\)\\@\\|]+
+#USERNAME=[-=\\w\\[\\]\\{\\}\\(\\)\\@\\|\\.]+
+#DEFAULT_CHANNEL=0
+#REMEMBER_CHANNEL=true
+#REMEMBER_CHANNEL_DURATION=0
+#TEXT_MESSAGE_LENGTH=5000
+#IMAGE_MESSAGE_LENGTH=1048576
+#ALLOW_HTML=true
+#BONJOUR=true
+#OBFUSCATE=false
+#CERT_REQUIRED=false
+#SEND_VERSION=true
+#SUGGEST_VERSION=
+#SUGGEST_POSITIONAL=
+#SUGGEST_PUSH_TO_TALK=
+#KDF_ITERATIONS=-1
+#AUTO_BAN_ATTEMPTS=10
+#AUTO_BAN_TIMEFRAME=120
+#AUTO_BAN_TIME=300
+#AUTO_BAN_SUCCESSFUL_CONNECTIONS=true
+#ALLOW_RECORDING=true
+#ROLLING_STATS_WINDOW=300
+#LISTENERS_PER_CHANNEL=5
+#LISTENERS_PER_USER=2

.gitea/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,16 @@
+---
+name: "Mumble pull request template"
+about: "Mumble pull request template"
+---
+
+<!--
+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.
+-->
+
+* [ ] 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)
+* [ ] 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)

MAINTENANCE.md

@@ -0,0 +1,31 @@
+# Traefik Recipe Maintenance
+
+All contributions should be made via a pull request. This is to ensure a
+certain quality and consistency, that others can rely on.
+
+## Maintainer Responsibilities
+
+A recipe maintainer has the following responsibilities:
+
+- Respond to pull requests / issues within a week
+- Make image security updates within a day
+- Make image patch / minor updates within a week
+- Make image major updates within a month
+
+In order to fullfill 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. 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.
+
+Pull requests opened by a maintainer need to be approved by another maintainer. If there is only one maintainer, reviews from operators are recommended but not required.
+
+## Become a maintainer
+
+Everyone can apply to be a recipe maintainer:
+1. Watch the repository to always get updates
+2. 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 [mumble maintainers team](https://git.coopcloud.tech/org/coop-cloud/teams/mumble-maintainers).

README.md

@@ -21,14 +21,53 @@ Low latency, high quality voice chat application.
 ## Basic usage
 
 1. Set up Docker Swarm and [`abra`]
-2. Deploy [`coop-cloud/traefik`]
-3. `abra app new ${REPO_NAME} --secrets` (optionally with `--pass` if you'd like
-   to save secrets in `pass`)
-4. `abra app config YOURAPPDOMAIN` - be sure to change `$DOMAIN` to something that resolves to
-   your Docker swarm box
-5. `abra app deploy YOURAPPDOMAIN`
-6. Open the configured domain in your browser to finish set-up
+2. Configure [`coop-cloud/traefik`] to accept mumble's ports:
+    ```bash
+    $ abra app config <YOURTRAEFIKDOMAIN>
+    ```
+  - uncomment lines related to mumble:
+    ```
+    COMPOSE_FILE="$COMPOSE_FILE:compose.mumble.yml"
+    MUMBLE_ENABLED=1
+    ```
+  - save the config and deploy traefik:
+    ```bash
+    $ abra app deploy <YOURTRAEFIKCOMAIN> --force
+    ```
+3. `abra app new mumble`
+4. `abra app secret generate <YOURAPPDOMAIN> --all`
+5. `abra app config <YOURAPPDOMAIN>`
+6. `abra app deploy <YOURAPPDOMAIN>`
+7. Connect with a [Mumble client] to port 64738 on your domain
+
+## Web Client
+
+An optional browser-based client is available via the `compose.mumbleweb.yml`
+overlay. To enable it:
+1. `abra app config mumble.example.com` — uncomment the line:
+   ```
+   COMPOSE_FILE="$COMPOSE_FILE:compose.mumbleweb.yml"
+   ```
+2. `abra app deploy <YOURAPPDOMAIN> --force`
+3. Open `https://<YOURAPPDOMAIN>` in a browser
+
+## Server Password
+By default, the server is not password-restricted. To enable a server password,
+1. uncomment the relevant lines in the config:
+```
+COMPOSE_FILE="$COMPOSE_FILE:compose.serverpassword.yml"
+SECRET_SERVER_PASSWORD_VERSION=v1
+```
+2. set the password as a secret:
+```bash
+$ abra app secret insert <YOURAPPDOMAIN> server-pw v1
+? specify secret value:
+```
+3. Redeploy your app:
+```bash
+$ abra app deploy <YOURAPPDOMAIN> --force
+```
 
 [`abra`]: https://git.coopcloud.tech/coop-cloud/abra
 [`coop-cloud/traefik`]: https://git.coopcloud.tech/coop-cloud/traefik
-coop-cloud/traefik
+[Mumble client]:(https://www.mumble.info/downloads/)

compose.serverpassword.yml

@@ -0,0 +1,12 @@
+version: "3.8"
+
+services:
+  app:
+    secrets:
+      - source: server-pw
+        target: MUMBLE_CONFIG_SERVER_PASSWORD
+
+secrets:
+  server-pw:
+    external: true
+    name: ${STACK_NAME}_server-pw_${SECRET_SERVER_PASSWORD_VERSION}

compose.yml

@@ -8,6 +8,49 @@ services:
       - proxy
     volumes:
       - "mumble_data:/data"
+    secrets:
+      - source: superuser-pw
+        target: MUMBLE_SUPERUSER_PASSWORD
+    environment:
+      MUMBLE_CONFIG_WELCOMETEXT: ${WELCOME_TEXT:-"<br />Welcome to this server running <b>Mumble</b>.<br />Enjoy your stay!<br />"}
+      MUMBLE_CONFIG_BANDWIDTH: ${BANDWIDTH:-558000}
+      MUMBLE_CONFIG_TIMEOUT: ${TIMEOUT:-30}
+      MUMBLE_CONFIG_USERS: ${USERS:-100}
+      MUMBLE_CONFIG_USERSPERCHANNEL: ${USERS_PER_CHANNEL:-0}
+      MUMBLE_CONFIG_MESSAGEBURST: ${MESSAGE_BURST:-5}
+      MUMBLE_CONFIG_MESSAGELIMIT: ${MESSAGE_LIMIT:-1}
+      MUMBLE_CONFIG_PLUGINMESSAGELIMIT: ${PLUGIN_MESSAGE_LIMIT:-1}
+      MUMBLE_CONFIG_PLUGINMESSAGEBURST: ${PLUGIN_MESSAGE_BURST:-5}
+      MUMBLE_CONFIG_ALLOWPING: ${ALLOW_PING:-true}
+      MUMBLE_CONFIG_OPUSTHRESHOLD: ${OPUS_THRESHOLD:-0}
+      MUMBLE_CONFIG_CHANNELNESTINGLIMIT: ${CHANNEL_NESTING_LIMIT:-10}
+      MUMBLE_CONFIG_CHANNELCOUNTLIMIT: ${CHANNEL_COUNT_LIMIT:-1000}
+        # 2026-04-28 @amras - the missing } in the following lines is intentional
+        # otherwise compose will pass that character to the env.
+      MUMBLE_CONFIG_CHANNELNAME: ${CHANNEL_NAME:-[ \\-=\\w\\#\\[\\]\\{\\}\\(\\)\\@\\|]+
+      MUMBLE_CONFIG_USERNAME: ${USER_NAME:-[-=\\w\\[\\]\\{\\}\\(\\)\\@\\|\\.]+
+      MUMBLE_CONFIG_DEFAULTCHANNEL: ${DEFAULT_CHANNEL}
+      MUMBLE_CONFIG_REMEMBERCHANNEL: ${REMEMBER_CHANNEL:-true}
+      MUMBLE_CONFIG_REMEMBERCHANNELDURATION: ${REMEMBER_CHANNEL_DURATION:-0}
+      MUMBLE_CONFIG_TEXTMESSAGELENGTH: ${TEXT_MESSAGE_LENGTH:-5000}
+      MUMBLE_CONFIG_IMAGEMESSAGELENGTH: ${IMAGE_MESSAGE_LENGTH:-1048576}
+      MUMBLE_CONFIG_ALLOWHTML: ${ALLOW_HTML:-true}
+      MUMBLE_CONFIG_BONJOUR: ${BONJOUR:-true}
+      MUMBLE_CONFIG_OBFUSCATE: ${OBFUSCATE:-false}
+      MUMBLE_CONFIG_CERTREQUIRED: ${CERT_REQUIRED:-false}
+      MUMBLE_CONFIG_SENDVERSION: ${SEND_VERSION:-true}
+      MUMBLE_CONFIG_SUGGESTVERSION: ${SUGGEST_VERSION}
+      MUMBLE_CONFIG_SUGGESTPOSITIONAL: ${SUGGEST_POSITIONAL}
+      MUMBLE_CONFIG_SUGGESTPUSHTOTALK: ${SUGGEST_PUSH_TO_TALK}
+      MUMBLE_CONFIG_KDFITERATIONS: ${KDF_ITERATIONS:--1}
+      MUMBLE_CONFIG_AUTOBANATTEMPTS: ${AUTOBAN_ATTEMPTS:-10}
+      MUMBLE_CONFIG_AUTOBANTIMEFRAME: ${AUTOBAN_TIMEFRAME:-120}
+      MUMBLE_CONFIG_AUTOBANTIME: ${AUTOBAN_TIME:-300}
+      MUMBLE_CONFIG_AUTOBANSUCCESSFULCONNECTIONS: ${AUTOBAN_SUCCESSFUL_CONNECTIONS:-true}
+      MUMBLE_CONFIG_ALLOWRECORDING: ${ALLOW_RECORDING:-true}
+      MUMBLE_CONFIG_ROLLINGSTATSWINDOW: ${ROLLING_STATS_WINDOW:-300}
+      MUMBLE_CONFIG_LISTENERSPERCHANNEL: ${LISTENERS_PER_CHANNEL:--1}
+      MUMBLE_CONFIG_LISTENERSPERUSER: ${LISTENERS_PER_USER:--1}
     deploy:
       restart_policy:
         condition: on-failure
@@ -21,7 +64,12 @@ services:
         - "traefik.udp.routers.${STACK_NAME}.entrypoints=mumble-udp"
         - "traefik.udp.routers.${STACK_NAME}.service=${STACK_NAME}-udp-service"
         - "traefik.udp.services.${STACK_NAME}-udp-service.loadbalancer.server.port=64738"
-        - "coop-cloud.${STACK_NAME}.version=0.1.0+v1.6.870-0"
+        - "coop-cloud.${STACK_NAME}.version=0.2.0+v1.6.870-0"
+
+secrets:
+  superuser-pw:
+    external: true
+    name: ${STACK_NAME}_superuser-pw_${SECRET_SUPERUSER_PASSWORD_VERSION}
 
 networks:
   proxy:

release/0.2.0+v1.6.870-0

@@ -0,0 +1,3 @@
+- Added support for optional server passwords
+- Added support for misc options from mumble-server.ini
+- Important: superuser-pw must now be set as a secret