ci: fix docker compose and docs (#634)

* ci: fix docker compose and docs

* docker: address review comments

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-linux-amd64:latest
-docker pull ghcr.io/l5yth/potato-mesh/web:v0.5.5      # pinned historical release
+docker pull ghcr.io/l5yth/potato-mesh-web-linux-arm64:latest
-docker pull ghcr.io/l5yth/potato-mesh/ingestor:latest
+docker pull ghcr.io/l5yth/potato-mesh-web-linux-armv7:latest
-docker pull ghcr.io/l5yth/potato-mesh/matrix-bridge: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.

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:

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: