From 724b3e14e5c67bd7eb07799075420b10e331f6cd Mon Sep 17 00:00:00 2001 From: l5y <220195275+l5yth@users.noreply.github.com> Date: Sat, 14 Feb 2026 13:25:43 +0100 Subject: [PATCH] ci: fix docker compose and docs (#634) * ci: fix docker compose and docs * docker: address review comments --- README.md | 31 ++++++++++++++++++++++++++----- docker-compose.yml | 9 ++++++++- matrix/README.md | 32 ++++++++++++++++++++++++++++++++ 3 files changed, 66 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 03dfcfa..d3399a0 100644 --- a/README.md +++ b/README.md @@ -252,15 +252,36 @@ services.potato-mesh = { ## Docker -Docker images are published on Github for each release: +Docker images are published on GitHub Container Registry for each release. +Image names and tags follow the workflow format: +`${IMAGE_PREFIX}-${service}-${architecture}:${tag}` (see `.github/workflows/docker.yml`). ```bash -docker pull ghcr.io/l5yth/potato-mesh/web:latest # newest release -docker pull ghcr.io/l5yth/potato-mesh/web:v0.5.5 # pinned historical release -docker pull ghcr.io/l5yth/potato-mesh/ingestor:latest -docker pull ghcr.io/l5yth/potato-mesh/matrix-bridge:latest +docker pull ghcr.io/l5yth/potato-mesh-web-linux-amd64:latest +docker pull ghcr.io/l5yth/potato-mesh-web-linux-arm64:latest +docker pull ghcr.io/l5yth/potato-mesh-web-linux-armv7:latest + +docker pull ghcr.io/l5yth/potato-mesh-ingestor-linux-amd64:latest +docker pull ghcr.io/l5yth/potato-mesh-ingestor-linux-arm64:latest +docker pull ghcr.io/l5yth/potato-mesh-ingestor-linux-armv7:latest + +docker pull ghcr.io/l5yth/potato-mesh-matrix-bridge-linux-amd64:latest +docker pull ghcr.io/l5yth/potato-mesh-matrix-bridge-linux-arm64:latest +docker pull ghcr.io/l5yth/potato-mesh-matrix-bridge-linux-armv7:latest + +# version-pinned examples +docker pull ghcr.io/l5yth/potato-mesh-web-linux-amd64:v0.5.5 +docker pull ghcr.io/l5yth/potato-mesh-ingestor-linux-amd64:v0.5.5 +docker pull ghcr.io/l5yth/potato-mesh-matrix-bridge-linux-amd64:v0.5.5 ``` +Note: `latest` is only published for non-prerelease versions. Pre-release tags +such as `-rc`, `-beta`, `-alpha`, or `-dev` are version-tagged only. + +When using Compose, set `POTATOMESH_IMAGE_ARCH` in `docker-compose.yml` (or via +environment) so service images resolve to the correct architecture variant and +you avoid manual tag mistakes. + Feel free to run the [configure.sh](./configure.sh) script to set up your environment. See the [Docker guide](DOCKER.md) for more details and custom deployment instructions. diff --git a/docker-compose.yml b/docker-compose.yml index 3eecf2a..4ebbf44 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -81,7 +81,12 @@ x-matrix-bridge-base: &matrix-bridge-base image: ghcr.io/l5yth/potato-mesh-matrix-bridge-${POTATOMESH_IMAGE_ARCH:-linux-amd64}:${POTATOMESH_IMAGE_TAG:-latest} volumes: - potatomesh_matrix_bridge_state:/app - - ./matrix/Config.toml:/app/Config.toml:ro + - type: bind + source: ./matrix/Config.toml + target: /app/Config.toml + read_only: true + bind: + create_host_path: false restart: unless-stopped deploy: resources: @@ -128,6 +133,8 @@ services: matrix-bridge: <<: *matrix-bridge-base network_mode: host + profiles: + - matrix depends_on: - web extra_hosts: diff --git a/matrix/README.md b/matrix/README.md index e866a57..147159c 100644 --- a/matrix/README.md +++ b/matrix/README.md @@ -146,6 +146,38 @@ Container detection checks `POTATOMESH_CONTAINER`, `CONTAINER`, and `/proc/1/cgr Set `POTATOMESH_CONTAINER=0` or `--no-container` to opt out of container defaults. +### Docker Compose First Run + +Before starting Compose, complete this preflight checklist: + +1. Ensure `matrix/Config.toml` exists as a regular file on the host (not a directory). +2. Fill required Matrix values in `matrix/Config.toml`: + - `matrix.as_token` + - `matrix.hs_token` + - `matrix.server_name` + - `matrix.room_id` + - `matrix.homeserver` + +This is required because the shared Compose anchor `x-matrix-bridge-base` mounts `./matrix/Config.toml` to `/app/Config.toml`. +Then follow the token and namespace requirements in [Matrix Appservice Setup (Synapse example)](#matrix-appservice-setup-synapse-example). + +#### Troubleshooting + +| Symptom | Likely cause | What to check | +| --- | --- | --- | +| `Is a directory (os error 21)` | Host mount source became a directory | `matrix/Config.toml` was missing at mount time and got created as a directory on host. | +| `M_UNKNOWN_TOKEN` / `401 Unauthorized` | Matrix appservice token mismatch | Verify `matrix.as_token` matches your appservice registration and setup in [Matrix Appservice Setup (Synapse example)](#matrix-appservice-setup-synapse-example). | + +#### Recovery from accidental `Config.toml` directory creation + +```bash +# from repo root +rm -rf matrix/Config.toml +touch matrix/Config.toml +# then edit matrix/Config.toml and set valid matrix.as_token, matrix.hs_token, +# matrix.server_name, matrix.room_id, and matrix.homeserver before starting compose +``` + ### PotatoMesh API The bridge assumes: