fix(docker): ship the compose file for image installs so HTTPS works there too

The optional HTTPS proxy is defined in the repo's docker-compose.yml behind the "https" Compose profile, which only git-checkout installs have. Docker Hub / GHCR installs write their own compose file from a README heredoc that had no npm service, so COMPOSE_PROFILES=https matched nothing and started the app alone - exit 0, no warning. The same gap swallowed MC_TRUST_PROXY, MC_BIND_ADDRESS and MC_DEMO*, which the compose file passes to the app. Add docker-compose.image.yml - the image-based counterpart of docker-compose.yml, maintained here and downloaded instead of hand-copied, so the npm service and every variable stay in sync. The image tag becomes MC_IMAGE in .env so the file itself needs no editing and can be re-downloaded when something is added to it. Docs: README Option A downloads the file (and .env.example) instead of pasting one, and switches tags via MC_IMAGE; https-setup.md Step 1 splits into the two install paths, tells image installs to refresh the file, notes that MC_TRUST_PROXY / MC_BIND_ADDRESS need it too, adds the curl for npm-default-site.conf (no docker/ folder there) and a troubleshooting row for "only mc-webui starts, no error". Verified with `docker compose config` in a scratch project directory: the old hand-written file plus COMPOSE_PROFILES=https in .env resolves to mc-webui only, the new file to mc-webui + npm with MC_TRUST_PROXY passed and port 5000 bound to 127.0.0.1; `config --images` lists both images, so update-image.sh pulls and recreates them. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-10-30 23:51:57 +01:00 · 2026-09-12 18:18:36 +02:00
1 parent db209e4270
commit f82ee981b2
@@ -72,6 +72,16 @@ FLASK_PORT=5000
 # Debug mode (true/false) - use false in production
 FLASK_DEBUG=false

+# ============================================
+# Docker image (Docker Hub / GHCR installations only)
+# ============================================
+# Which published image the container runs. Only used by the compose file from
+# docker-compose.image.yml - an installation built from source ignores it.
+# Stable (default when unset): mawoj/mc-webui:latest
+# Development builds:          mawoj/mc-webui:dev
+# GHCR mirror:                 ghcr.io/marekwo/mc-webui:latest
+# MC_IMAGE=mawoj/mc-webui:latest
+
 # ============================================
 # HTTPS (optional) - see docs/https-setup.md
 # ============================================
@@ -99,52 +99,22 @@ Images are also mirrored to GitHub Container Registry: `ghcr.io/marekwo/mc-webui
    mkdir ~/mc-webui && cd ~/mc-webui
    ```

-2. **Create `docker-compose.yml`**
+2. **Download `docker-compose.yml`**
    ```bash
-    cat > docker-compose.yml << 'EOF'
-    services:
-      mc-webui:
-        image: mawoj/mc-webui:latest
-        container_name: mc-webui
-        restart: unless-stopped
-        ports:
-          - "${FLASK_PORT:-5000}:${FLASK_PORT:-5000}"
-        device_cgroup_rules:
-          - 'c 188:* rmw'
-          - 'c 166:* rmw'
-        cap_add:
-          - NET_ADMIN
-          - NET_RAW
-        volumes:
-          - "${MC_CONFIG_DIR:-./data}:/data:rw"
-          - "/dev:/dev"
-          - "/var/run/dbus:/var/run/dbus"
-        environment:
-          - MC_SERIAL_PORT=${MC_SERIAL_PORT:-auto}
-          - MC_DEVICE_NAME=${MC_DEVICE_NAME:-MeshCore}
-          - MC_CONFIG_DIR=/data
-          - MC_TCP_HOST=${MC_TCP_HOST:-}
-          - MC_TCP_PORT=${MC_TCP_PORT:-5555}
-          - MC_BLE_ADDRESS=${MC_BLE_ADDRESS:-}
-          - MC_BACKUP_ENABLED=${MC_BACKUP_ENABLED:-true}
-          - MC_BACKUP_HOUR=${MC_BACKUP_HOUR:-2}
-          - MC_BACKUP_RETENTION_DAYS=${MC_BACKUP_RETENTION_DAYS:-7}
-          - FLASK_HOST=${FLASK_HOST:-0.0.0.0}
-          - FLASK_PORT=${FLASK_PORT:-5000}
-          - FLASK_DEBUG=${FLASK_DEBUG:-false}
-          - TZ=${TZ:-UTC}
-        env_file:
-          - path: .env
-            required: false
-        healthcheck:
-          test: ["CMD", "curl", "-f", "http://localhost:5000/health"]
-          interval: 30s
-          timeout: 10s
-          retries: 3
-          start_period: 15s
-    EOF
+    curl -fsSL https://raw.githubusercontent.com/MarekWo/mc-webui/main/docker-compose.image.yml -o docker-compose.yml
    ```

+    This is [`docker-compose.image.yml`](docker-compose.image.yml) from this repository — the
+    image-based counterpart of the compose file used by Option B. Downloading it instead of
+    writing your own keeps the optional extras working: the HTTPS proxy
+    ([docs/https-setup.md](docs/https-setup.md)) is defined in it behind a Compose *profile*,
+    and options such as `MC_BIND_ADDRESS`, `MC_TRUST_PROXY` or demo mode are read from it too.
+    A hand-written file that lacks those lines simply ignores the matching `.env` settings.
+
+    **Leave the file unedited.** Everything configurable is a variable read from `.env`
+    (including the image tag — `MC_IMAGE`), so you can download the file again at any time to
+    pick up services added in later versions, without touching your own settings.
+
 3. **Create `.env` file (optional)**

    **In most cases, no `.env` file is needed!** The defaults work automatically:
@@ -156,6 +126,12 @@ Images are also mirrored to GitHub Container Registry: `ghcr.io/marekwo/mc-webui
    echo "TZ=Europe/Warsaw" > .env
    ```

+    Every available option is documented in [`.env.example`](.env.example). You can keep a copy
+    next to your `.env` for reference — no clone needed:
+    ```bash
+    curl -fsSL https://raw.githubusercontent.com/MarekWo/mc-webui/main/.env.example -o .env.example
+    ```
+
    <details>
    <summary><b>Troubleshooting: Multiple USB devices or detection fails</b></summary>

@@ -334,9 +310,23 @@ docker compose pull
 docker compose up -d
 ```

-To switch between stable and dev, change the image tag in `docker-compose.yml`:
- Stable: `image: mawoj/mc-webui:latest`
- Development: `image: mawoj/mc-webui:dev`
+To switch between stable and dev, set the image in `.env` (not in `docker-compose.yml`):
+- Stable: `MC_IMAGE=mawoj/mc-webui:latest` — the default when unset
+- Development: `MC_IMAGE=mawoj/mc-webui:dev`
+
+Then `docker compose pull && docker compose up -d`.
+
+New optional services occasionally land in the compose file — the HTTPS proxy is one. Pulling a
+new image does not bring them, since the file is yours; download the current one over it when you
+need one of them:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/MarekWo/mc-webui/main/docker-compose.image.yml -o docker-compose.yml
+docker compose up -d
+```
+
+That file holds no settings of yours — those all live in `.env` — so overwriting it is safe.
+One exception: if you had edited the image tag inside the old file to follow `dev`, the downloaded file resets it to the stable one. Put `MC_IMAGE=mawoj/mc-webui:dev` in `.env` to stay on development builds.

 You can also update from the web interface instead of the terminal — see
 [Remote updates from web GUI](#remote-updates-from-web-gui-optional) below.
@@ -0,0 +1,88 @@
+# mc-webui — Docker Hub / GHCR installation (README "Option A")
+#
+# The counterpart of docker-compose.yml for installations that never cloned the
+# repository: the same services, but the app comes from the published image
+# instead of a local build. Download it as your docker-compose.yml:
+#
+#   curl -fsSL https://raw.githubusercontent.com/MarekWo/mc-webui/main/docker-compose.image.yml \
+#        -o docker-compose.yml
+#
+# Keep it unedited. Everything configurable is a variable read from .env, so the
+# file can be downloaded again at any time — to pick up services added later,
+# such as the optional HTTPS proxy at the bottom — without losing your setup.
+services:
+  mc-webui:
+    # Stable release: mawoj/mc-webui:latest — development: mawoj/mc-webui:dev
+    # GHCR mirror: ghcr.io/marekwo/mc-webui. Switch with MC_IMAGE in .env.
+    image: ${MC_IMAGE:-mawoj/mc-webui:latest}
+    container_name: mc-webui
+    restart: unless-stopped
+    # MC_BIND_ADDRESS=127.0.0.1 keeps the plain-HTTP port off the network once
+    # HTTPS is up (docs/https-setup.md). Default 0.0.0.0 = reachable as before.
+    ports:
+      - "${MC_BIND_ADDRESS:-0.0.0.0}:${FLASK_PORT:-5000}:${FLASK_PORT:-5000}"
+    # Grant access to serial devices for auto-detection
+    # Major 188 = ttyUSB (CP2102, CH340), Major 166 = ttyACM (ESP32-S3)
+    device_cgroup_rules:
+      - 'c 188:* rmw'
+      - 'c 166:* rmw'
+    # NET_ADMIN + NET_RAW for BLE scanning (no overhead when BLE unused)
+    cap_add:
+      - NET_ADMIN
+      - NET_RAW
+    volumes:
+      - "${MC_CONFIG_DIR:-./data}:/data:rw"
+      - "/dev:/dev"
+      - "/var/run/dbus:/var/run/dbus"  # BlueZ D-Bus (for BLE)
+    environment:
+      - MC_SERIAL_PORT=${MC_SERIAL_PORT:-auto}
+      - MC_DEVICE_NAME=${MC_DEVICE_NAME:-MeshCore}
+      - MC_CONFIG_DIR=/data
+      - MC_TCP_HOST=${MC_TCP_HOST:-}
+      - MC_TCP_PORT=${MC_TCP_PORT:-5555}
+      - MC_BLE_ADDRESS=${MC_BLE_ADDRESS:-}
+      - MC_BACKUP_ENABLED=${MC_BACKUP_ENABLED:-true}
+      - MC_BACKUP_HOUR=${MC_BACKUP_HOUR:-2}
+      - MC_BACKUP_RETENTION_DAYS=${MC_BACKUP_RETENTION_DAYS:-7}
+      - FLASK_HOST=${FLASK_HOST:-0.0.0.0}
+      - FLASK_PORT=${FLASK_PORT:-5000}
+      - FLASK_DEBUG=${FLASK_DEBUG:-false}
+      - MC_TRUST_PROXY=${MC_TRUST_PROXY:-false}
+      - MC_DEMO=${MC_DEMO:-false}
+      - MC_DEMO_TRUSTED_NETS=${MC_DEMO_TRUSTED_NETS:-}
+      - MC_DEMO_UNLOCK_CODE=${MC_DEMO_UNLOCK_CODE:-}
+      - TZ=${TZ:-UTC}
+    env_file:
+      - path: .env
+        required: false
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:5000/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 15s
+
+  # Optional HTTPS front end — Nginx Proxy Manager.
+  # Inert unless the "https" profile is active, so existing installs are untouched.
+  # Enable it by putting COMPOSE_PROFILES=https in .env, then run the usual
+  # `docker compose up -d`. Full guide: docs/https-setup.md
+  #
+  # Both services share this project's default network, so the proxy reaches the
+  # app at http://mc-webui:5000 without the app publishing any port at all.
+  npm:
+    image: ${NPM_IMAGE:-jc21/nginx-proxy-manager:latest}
+    container_name: mc-webui-proxy
+    profiles: ["https"]
+    restart: unless-stopped
+    depends_on:
+      - mc-webui
+    ports:
+      - "${NPM_HTTP_PORT:-80}:80"     # HTTP — also the Let's Encrypt HTTP-01 challenge
+      - "${NPM_HTTPS_PORT:-443}:443"  # HTTPS
+      - "${NPM_ADMIN_PORT:-81}:81"    # Proxy Manager admin UI
+    volumes:
+      - "${NPM_DATA_DIR:-./data/npm}:/data"
+      - "${NPM_LETSENCRYPT_DIR:-./data/letsencrypt}:/etc/letsencrypt"
+    environment:
+      - TZ=${TZ:-UTC}
+      - DISABLE_IPV6=${NPM_DISABLE_IPV6:-true}
@@ -176,7 +176,8 @@ The `/path-analyzer` panel (standalone iframe page, `path-analyzer.js`) is a rea
 ```text
 mc-webui/
 ├── Dockerfile                      # Main app Docker image
-├── docker-compose.yml              # Single-container orchestration
+├── docker-compose.yml              # Single-container orchestration (builds from source)
+├── docker-compose.image.yml        # Same, for Docker Hub/GHCR installs (published image)
 ├── app/
 │   ├── __init__.py
 │   ├── main.py                     # Flask entry point + Socket.IO handlers
@@ -44,7 +44,13 @@ and add:
 COMPOSE_PROFILES=https
 ```

-Then start it the usual way:
+What comes next depends on how mc-webui was installed — the two options in the
+[README](../README.md#installation) differ in who owns `docker-compose.yml`, and the profile
+line can only start a service that is actually defined in that file.
+
+### Installed from source (README Option B — git clone)
+
+Nothing else to do:

 ```bash
 docker compose up -d --build
@@ -56,6 +62,33 @@ behind a Compose *profile*, so it stays completely inert until that line exists
 yourself**: it is tracked in git, and a local edit will make the next update fail with a
 merge conflict.

+### Installed from the Docker image (README Option A — Docker Hub / GHCR)
+
+Here `docker-compose.yml` is *your* file — no update ever rewrites it — and versions of it
+written by hand, or copied from an older README, contain the app service only. With no `npm`
+service to activate, `COMPOSE_PROFILES=https` does exactly nothing: `docker compose up -d`
+starts the app as before and says nothing about a proxy. Nothing is broken and nothing is
+misconfigured — there is simply no proxy in the file.
+
+So replace the file with the current one, which has the proxy in it, and start:
+
+```bash
+cd ~/mc-webui
+curl -fsSL https://raw.githubusercontent.com/MarekWo/mc-webui/main/docker-compose.image.yml -o docker-compose.yml
+docker compose up -d
+```
+
+Overwriting is safe: that file holds no settings of yours — every option is a variable it
+reads from `.env`, which the download does not touch. Keep it unedited from now on, so the
+next feature that arrives this way is one download away again. One thing to carry over: if you
+had changed the image tag inside the old file to follow `dev`, add `MC_IMAGE=mawoj/mc-webui:dev`
+to `.env` — the downloaded file follows the stable tag by default.
+
+> The same applies to `MC_TRUST_PROXY` and `MC_BIND_ADDRESS` in Step 5. They too are passed
+> to the app by `docker-compose.yml`, so in a hand-written file that predates them the `.env`
+> lines are read by nobody — the app keeps seeing the proxy as the client, and port 5000 stays
+> open to the network. The download above fixes those at the same time.
+
 Check that both containers are up:

 ```bash
@@ -279,8 +312,15 @@ file. Everything then works as described above, and this is worth doing anyway.
 **The direct one: let the proxy answer unnamed requests.** This project ships a
 replacement for that default server at [`docker/npm-default-site.conf`](../docker/npm-default-site.conf)
 — same file with the refusing block removed, so your proxy host answers instead and
-presents its certificate. Enable it by creating `docker-compose.override.yml` next to
-`docker-compose.yml`:
+presents its certificate. A Docker Hub installation has no `docker/` folder, so fetch the
+file first (a git checkout already has it):
+
+```bash
+mkdir -p docker
+curl -fsSL https://raw.githubusercontent.com/MarekWo/mc-webui/main/docker/npm-default-site.conf -o docker/npm-default-site.conf
+```
+
+Enable it by creating `docker-compose.override.yml` next to `docker-compose.yml`:

 ```yaml
 services:
@@ -411,8 +451,11 @@ In practice:
 ## Updating and removing

 **Updating** needs nothing special — `mcupdate` (or `docker compose up -d --build`) pulls
-both containers as usual. The proxy's configuration and certificates live in
-`./data/npm` and `./data/letsencrypt` and survive rebuilds.
+both containers as usual, and so does `docker compose pull && docker compose up -d` on a
+Docker Hub installation. The proxy's configuration and certificates live in `./data/npm` and
+`./data/letsencrypt` and survive rebuilds. On a Docker Hub installation, remember that
+`docker-compose.yml` is yours and is never updated for you: download it again (Step 1) when
+a release adds something to it.

 **Removing HTTPS:** delete or comment out `COMPOSE_PROFILES=https` in `.env`, then:

@@ -430,6 +473,7 @@ unreachable from the network. The proxy's data directories are left in place; de
 | Symptom | Cause and fix |
 |---|---|
 | The interface crawls with 2–3 tabs open; clicks take 10–20 s | **Websockets Support** is off on the proxy host. Turn it on (Step 3). |
+| `docker compose up -d` starts only `mc-webui` — no proxy, and no error either | Your `docker-compose.yml` has no `npm` service, so the `https` profile has nothing to activate. A Docker Hub installation with a hand-written compose file: download the current one (Step 1). |
 | `502 Bad Gateway` | The app container is down or still starting — `docker compose ps`, then `docker compose logs mc-webui`. Also check Forward Hostname is `mc-webui` (the container name), not `localhost`: inside the proxy container, `localhost` is the proxy itself. |
 | `address already in use` on startup | Something else on the host holds port 80 or 443. Stop it, or set `NPM_HTTP_PORT` / `NPM_HTTPS_PORT`. |
 | Let's Encrypt fails with a connection or timeout error | HTTP-01 validation could not reach port 80 from the internet. Check the router forward, or switch to a DNS challenge (Option B). |
@@ -10,6 +10,20 @@ For deep technical notes, see [architecture.md](architecture.md). For the full g

 ## Unreleased

+### Fixes
+
+- **Optional HTTPS now works on installations made from the Docker image, not only on those built from source.** mc-webui can be installed two ways, and they differ in one detail that turned out to matter: an installation built from the repository uses the `docker-compose.yml` that comes with it, while an installation from the published Docker image uses a `docker-compose.yml` that the README told you to write yourself. The optional HTTPS proxy ([HTTPS Setup](https-setup.md)) is defined in the project's file behind a Compose *profile*, so adding `COMPOSE_PROFILES=https` to `.env` starts it — but a hand-written file never had that definition, so the same line did nothing at all: the app started as before and no proxy was mentioned, with no error to explain why. Pasting the proxy into the file by hand worked, and then had to be redone by hand every time anything else was added to it. The same gap silently swallowed `MC_TRUST_PROXY` and `MC_BIND_ADDRESS` — the two settings that let the app see the real client address and close the plain-HTTP port — because those are passed to the app by the compose file too.
+
+    The compose file for image installations is now maintained in the repository as `docker-compose.image.yml` and downloaded rather than typed, so it contains the proxy, both proxy-related settings, and demo mode, exactly like the one used when building from source:
+
+    ```bash
+    cd ~/mc-webui   # the folder with your docker-compose.yml
+    curl -fsSL https://raw.githubusercontent.com/MarekWo/mc-webui/main/docker-compose.image.yml -o docker-compose.yml
+    docker compose up -d
+    ```
+
+    If you installed from the image, that command is also the upgrade path: it replaces your compose file with the current one, which is safe because none of your settings live there — they are all in `.env`, which the download does not touch. Keep the file unedited from now on and the next addition to it is one download away again. The image tag moved into `.env` for the same reason: `MC_IMAGE=mawoj/mc-webui:dev` selects development builds, where previously you edited the tag inside the compose file — so if you had edited it to follow `dev`, add that line to `.env` when you replace the file, or the next pull brings the stable image back. Installations built from source are unaffected.
+
 ---

 ## 2.18.1 — 2026-09-11