adam/mc-webui
1
0 Fork 0
mirror of https://github.com/MarekWo/mc-webui.git synced 2026-10-30 23:51:57 +01:00
Code Issues 3 Packages Projects Releases Wiki Activity

feat(https): optional HTTPS front end via Nginx Proxy Manager

Browse Source 
Adds an opt-in HTTPS layer without touching anything for existing installs.

The proxy is a service in docker-compose.yml behind the "https" Compose
profile, activated with COMPOSE_PROFILES=https in .env. That keeps the whole
setup inside files git owns while the switch lives in a file it ignores --
important because scripts/update.sh runs `git pull`, so any user edit to a
tracked compose file would break the next update with a merge conflict.
mcupdate needs no change: compose reads COMPOSE_PROFILES from .env itself.

Both services share the project's default network, so the proxy forwards to
http://mc-webui:5000 internally; MC_BIND_ADDRESS lets the plain-HTTP port be
restricted to loopback once HTTPS works, and MC_TRUST_PROXY turns on ProxyFix
so the app sees the real client address and scheme.

Also fixes copying over plain HTTP. navigator.clipboard only exists in a
secure context, and 9 call sites across 5 entry points used it with no
fallback, so copy buttons silently did nothing on a LAN address. They now
share clipboard-utils.js, loaded via _head_i18n.html (the one include every
entry point already has), which falls back to execCommand.

Verified locally against the real stack: self-signed cert uploaded to NPM,
proxy host created, app served over HTTPS with socket.io upgrading to a real
wss:// WebSocket (transport "websocket"), and the clipboard fallback checked
end-to-end by pasting back what it copied over http://.

Two findings from that run are documented in docs/https-setup.md:
NPM 2.15 dropped the default admin@example.com account for a setup wizard,
and its default 443 server now refuses connections without SNI -- which is
every connection made to a bare IP address. docker/npm-default-site.conf is
the opt-in way around that, mounted writable (a :ro mount aborts s6 init and
leaves nginx not listening at all).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
MarekWoandClaude Opus 5 committed 2026-08-02 17:58:03 +02:00
1 parent a3fde55704
commit 05ec5fa13e
15 files changed
+502 -51
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/https-setup.md
+312
View File
@@ -0,0 +1,312 @@
# HTTPS Setup
By default mc-webui speaks plain HTTP. This guide turns on an optional HTTPS front end
using [Nginx Proxy Manager](https://nginxproxymanager.com/) (NPM) — a small web UI where
you point-and-click your way to a certificate, instead of editing nginx config files.
Everything here is opt-in. If you skip this document, nothing about your installation
changes.
## Why bother
- **Encrypted traffic.** Nobody on your network reads your messages or your device
configuration in transit.
- **Copy buttons, and more, start working.** Browsers restrict a set of features to a
*secure context* — HTTPS, or `http://localhost`. Open mc-webui over plain HTTP at
`http://192.168.1.50:5000` and the modern clipboard API simply does not exist, so copy
buttons fall back to an older, less reliable method. The same applies to installing
mc-webui as an app on a phone, and to browser notifications.
- **A real hostname.** `https://mesh.example.com` instead of an IP and a port number.
- **Optional password protection.** NPM's *Access Lists* can put HTTP authentication in
front of mc-webui, which has no login of its own.
## How it fits together
```
browser ──HTTPS(443)──► nginx-proxy-manager ──HTTP──► mc-webui ──► MeshCore device
(container: mc-webui-proxy) (container: mc-webui)
```
Both containers belong to the same Compose project, so they share a private Docker
network. The proxy reaches the app as `http://mc-webui:5000` over that network — the app
does not need to publish a port at all, and the traffic between them never leaves the
host.
---
## Step 1 — Turn it on
Edit `.env` in your mc-webui directory (create it from `.env.example` if you have none)
and add:
```ini
COMPOSE_PROFILES=https
```
Then start it the usual way:
```bash
docker compose up -d --build
```
That is the whole installation. The proxy is defined in the project's `docker-compose.yml`
behind a Compose *profile*, so it stays completely inert until that line exists — and
`mcupdate` picks it up automatically from then on. **Do not edit `docker-compose.yml`
yourself**: it is tracked in git, and a local edit will make the next update fail with a
merge conflict.
Check that both containers are up:
```bash
docker compose ps
```
You should see `mc-webui` and `mc-webui-proxy`.
> **Port 80 or 443 already in use?** If something else on the host owns those ports,
> `docker compose up` fails with `address already in use`. Either stop the other service,
> or move the proxy's ports with `NPM_HTTP_PORT` / `NPM_HTTPS_PORT` in `.env`. Note that
> Let's Encrypt's HTTP validation requires the public port 80, so moving it rules that
> method out — use the DNS method (Option B) instead.
## Step 2 — Log in to the proxy admin UI
Open `http://<your-server>:81`. On first run you get a short setup form where you create
your own administrator account — name, email and password. There is no default login to
change afterwards.
Keep this panel on the local network and **do not forward port 81 through your router**:
it can route traffic anywhere inside your network, and it is served over plain HTTP.
> Older Nginx Proxy Manager releases (before 2.15) instead shipped a built-in
> `admin@example.com` / `changeme` account that you were expected to change on first
> login. If you pinned an older image with `NPM_IMAGE`, that is what you will see.
## Step 3 — Create the proxy host
Go to **Hosts → Proxy Hosts → Add Proxy Host** and fill in the **Details** tab:
| Field | Value |
|---|---|
| Domain Names | `mesh.example.com` — your hostname, or the server's IP address |
| Scheme | `http` |
| Forward Hostname / IP | `mc-webui` |
| Forward Port | `5000` |
| Cache Assets | off |
| Block Common Exploits | on |
| **Websockets Support** | **on — this one is not optional** |
> ### Websockets Support must be on
>
> mc-webui pushes new messages to open pages over a WebSocket. Without this switch, nginx
> does not forward the connection upgrade, the page silently drops back to long-polling,
> and a browser only allows six long-polling connections per address **across all tabs**.
> Two or three open tabs then exhaust that budget and the interface crawls — clicks take
> ten or twenty seconds while the server sits idle. It looks exactly like an overloaded
> server and it is not one. If you have seen that symptom before, this is the same bug
> coming back through the proxy.
Save. `http://mesh.example.com` should now show mc-webui. Certificates come next.
## Step 4 — Choose a certificate
Three routes, depending on whether you have a domain name and whether your server is
reachable from the internet.
### Option A — Let's Encrypt with a public domain (the easy case)
**Requires:** a domain name pointing at your public IP, and port 80 forwarded from your
router to this host.
Edit the proxy host → **SSL** tab → SSL Certificate: *Request a new SSL Certificate* →
enable **Force SSL** and **HTTP/2 Support** → agree to the terms → Save.
That is it. The certificate is trusted by every browser and phone with no warnings, and
NPM renews it automatically.
### Option B — Let's Encrypt with a DNS challenge (best for LAN-only servers)
**This is the option most home installations want.** It gives you a fully trusted
certificate on a server that is *not* exposed to the internet at all — no port
forwarding, nothing reachable from outside.
The trick: Let's Encrypt proves you own the *domain* by having you write a token into its
DNS, and never connects to your server. Nothing stops that domain's A record from
pointing at a private address such as `192.168.1.50`.
**Requires:** a domain you own, hosted at a DNS provider NPM supports (Cloudflare,
deSEC, DuckDNS, Hetzner, OVH, and around a hundred others), and an API token from it.
1. In your DNS, point `mesh.example.com` at the server's LAN address, e.g. `192.168.1.50`.
2. Edit the proxy host → **SSL** tab → *Request a new SSL Certificate*.
3. Enable **Use a DNS Challenge**, pick your provider and paste its API credentials.
4. Enable **Force SSL**, save, and give it a minute or two for DNS to propagate.
Certificate renewal is automatic and equally invisible. Everyone on the LAN reaches
`https://mesh.example.com` with a green padlock, including phones and the Android app.
### Option C — Self-signed, or a private CA (no domain at all)
**Use when you only ever reach the server by IP address**, e.g. `https://192.168.1.50`.
First, the part that is worth being clear about: **no public certificate authority will
ever issue a certificate for a private address** like `192.168.1.50` — nobody can prove
they own an address that exists identically inside every home network on earth. Let's
Encrypt has recently begun issuing certificates for *public* IP addresses, but those are
short-lived and NPM's certificate integration does not support them. So for a LAN
address, the choice is a certificate you sign yourself.
NPM cannot generate one, so create it on the host and upload it. **The `subjectAltName`
line is what matters** — browsers ignore the old Common Name entirely, and a certificate
without a matching SAN is rejected outright:
```bash
openssl req -x509 -nodes -newkey rsa:2048 -days 3650 \
-keyout mc-webui.key -out mc-webui.crt \
-subj "/CN=mc-webui" \
-addext "subjectAltName=IP:192.168.1.50,DNS:mc-webui.local" \
-addext "basicConstraints=critical,CA:FALSE" \
-addext "keyUsage=digitalSignature,keyEncipherment" \
-addext "extendedKeyUsage=serverAuth"
```
Replace the IP with your server's. List every name and address you will actually type
into the browser — each one needs to be in that SAN list.
Then in NPM: **SSL Certificates → Add SSL Certificate → Custom**, upload `mc-webui.key`
as the key and `mc-webui.crt` as the certificate (leave the intermediate field empty),
and select it on the proxy host's SSL tab.
**What you get:** real encryption, and the secure-context browser features work. **What
you do not get:** a green padlock. Every browser shows an interstitial warning the first
time, which you click through once per browser.
If the warnings bother you, use **[mkcert](https://github.com/FiloSottile/mkcert)**
instead. It creates a small certificate authority of your own, and installs it into the
trust store of the machines you choose — then those machines see no warning at all:
```bash
mkcert -install # once, per machine that should trust it
mkcert 192.168.1.50 mc-webui.local # produces a .pem cert and key to upload
```
### Browsing by IP address needs one extra step
Put the IP straight into the proxy host's *Domain Names* field — NPM accepts it. That is
not quite enough on its own, though, and the reason is worth understanding.
When you type a hostname, the browser tells the server which name it is asking for, as
part of setting up the encrypted connection (SNI). When you type an IP address it sends
nothing — the standard forbids it. Nginx then falls back to a *default* server for
port 443, and since version 2.15 Nginx Proxy Manager ships one whose entire job is to
refuse such connections. The browser shows a connection error before it ever gets as far
as a certificate warning.
Two ways out.
**The clean one: give the server a name.** Add a DNS entry on your router (or Pi-hole,
or whatever serves DNS on your network) pointing e.g. `mesh.lan` at the server, and use
that. One entry covers every device, including phones — where you cannot edit a hosts
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`:
```yaml
services:
npm:
volumes:
- "./docker/npm-default-site.conf:/etc/nginx/conf.d/default.conf"
```
Then `docker compose up -d`. That filename is deliberately ignored by git, so it survives
updates untouched.
> **Do not add `:ro` to that line.** The proxy container adjusts ownership of its config
> files at startup; on a read-only mount that fails, and it aborts the whole startup —
> the container comes up but nginx never starts listening, so *everything* refuses
> connections. It is a confusing failure to debug. Mount it writable, as above.
## Step 5 — Tighten it up (optional)
Once HTTPS works, three optional steps make it the only way in.
**Force HTTPS.** On the proxy host's SSL tab, enable **Force SSL** so plain HTTP requests
redirect. Leave HSTS off until you are sure everything works — HSTS is remembered by
browsers for months and is awkward to undo.
**Let the app see the real client.** In `.env`:
```ini
MC_TRUST_PROXY=true
```
Without it, mc-webui sees every request as coming from the proxy container and believes
the connection is plain HTTP. With it, the log shows real client addresses. Enable it
**only** when the app is reached through the proxy — anyone able to talk to port 5000
directly can forge those headers.
**Close the plain HTTP port.** Also in `.env`:
```ini
MC_BIND_ADDRESS=127.0.0.1
```
Port 5000 then answers only on the machine itself, so the network sees nothing but HTTPS.
The proxy is unaffected — it reaches the app over the internal Docker network. Set this
**after** HTTPS works, not before, or you will lock yourself out. To undo it, delete the
line and run `docker compose up -d`.
Apply either change with `docker compose up -d`.
## The Android app
The [Android wrapper](android-app.md) accepts both `http://` and `https://` addresses, but
it **rejects certificates it does not trust** and shows an SSL error instead of the page.
In practice:
- Options A and B work perfectly — enter `https://mesh.example.com` and you are done.
- Option C (self-signed) does **not** work in the app. Android's WebView does not trust
certificates you added to the phone manually, and there is no way around that from
inside the app. Use the app over `http://` on the LAN, or move to Option B.
## 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.
**Removing HTTPS:** delete or comment out `COMPOSE_PROFILES=https` in `.env`, then:
```bash
docker compose --profile https down
docker compose up -d
```
Also remove `MC_BIND_ADDRESS` and `MC_TRUST_PROXY` if you set them, or the app stays
unreachable from the network. The proxy's data directories are left in place; delete
`./data/npm` and `./data/letsencrypt` by hand if you want them gone.
## Troubleshooting
| 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). |
| `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). |
| Browser warns about the certificate even after installing a private CA | The address you typed is not in the certificate's `subjectAltName`. Reissue with every name and IP you use. |
| The Android app shows an SSL error | A self-signed certificate — the app cannot trust it. See the Android section above. |
| HTTPS works by hostname but not by IP address | The proxy refuses connections that carry no hostname. See "Browsing by IP address" above. |
| After mounting `npm-default-site.conf`, *nothing* answers — not even port 81 | The mount has `:ro`. Remove it and run `docker compose up -d`. |
| Locked out after setting `MC_BIND_ADDRESS` | On the server itself: remove the line from `.env` and run `docker compose up -d`. |
| Proxy container keeps restarting | Check `docker compose logs npm`. A common cause is `./data/npm` sitting on a synced folder (Synology Drive, Dropbox) — the sync client corrupts its SQLite database. Move it with `NPM_DATA_DIR`. |
## See also
- [Nginx Proxy Manager documentation](https://nginxproxymanager.com/guide/)
- [architecture.md](architecture.md) — how mc-webui itself is put together
- [android-app.md](android-app.md) — the Android wrapper
docs/whatsnew.md
+2
View File
@@ -12,12 +12,14 @@ For deep technical notes, see [architecture.md](architecture.md). For the full g
### Features
- **You can now reach mc-webui over HTTPS.** Until now the interface was served over plain HTTP only, which meant the address bar warned it was not secure, and — less obviously — that browsers quietly withheld a set of features they reserve for encrypted connections. There is now an optional HTTPS front end you switch on with a single line in `.env`; it starts [Nginx Proxy Manager](https://nginxproxymanager.com/) next to the app, and you pick your certificate in its web interface rather than editing configuration files. Three routes are covered: a free Let's Encrypt certificate for a public domain, a Let's Encrypt certificate via a DNS challenge — the one worth knowing about, because it gives a fully trusted certificate on a server that is not exposed to the internet at all, with no port forwarding — and a self-signed certificate for reaching the server by its IP address. Existing installations are untouched: nothing starts and nothing changes unless you ask for it, and updates keep working exactly as before. The guide is [https-setup.md](https-setup.md), including which switch to be careful about (Websockets Support — leave it off and several open tabs will crawl) and why a self-signed certificate cannot work with the Android app.
- **The interface can be translated, and Polish has started.** mc-webui was written English-only, with every label and message baked into the code. There is now a translation system behind it, and a **Language** setting at the top of Settings → Appearance. It covers the whole interface: the main window — menu, chat, message bubbles, its dialogs and **Settings** — every panel that opens in its own window (**System Log**, **Console**, **My Repeaters**, **Path Analyzer**, **Contacts**, **Direct Messages**), and the running commentary too: the small toasts after every action, the confirmation dialogs, the search results, the update flow and the notifications your phone shows when the app is in the background. Error text that comes back from the server itself is still English — that is the one part left, and it is a separate job. Your choice applies to the browser you set it in and also becomes the default for anyone else opening the server without a preference of their own.
- **You can add a language yourself, without waiting for a release.** A language is a single file. Copy `en.json` from `app/translations/`, translate the values, and drop it into a `translations` folder inside your config directory — the same place the database lives. Refresh the page and it appears in the Language list, named however you named it, with no rebuild and no restart. Anything you leave untranslated falls back to English, so a half-finished translation is perfectly usable. A file you drop in also overrides one that ships with the app, so you can correct the built-in Polish on your own server. English and Polish ship in the box; everything else is open to whoever wants to write it. See [translations.md](translations.md), which explains the format and — importantly — which words to leave alone: mesh terms like flood, hop, advert, RSSI and the repeater roles stay English in every language, because that is what the firmware, the CLI and the forums all use. The Console and the log lines themselves stay English for the same reason.
- **Times and dates behave the same in every language.** Only the words are translated — "Yesterday" becomes "Wczoraj", "5 min ago" becomes "5 min temu". The clock and the number formatting keep following your browser's own settings, so switching the menus to English will not suddenly turn your 24-hour clock into "9:53 AM". One display of large numbers on the repeater statistics page had been hard-coded to American thousands separators; it now follows your locale like everything else.
### Fixes
- **Copy buttons work over plain HTTP again.** Copying a public key, a channel key or a routing path did nothing on some pages when mc-webui was open over `http://` on a network address — no error, no text on the clipboard, just a button that appeared to do nothing. Browsers only offer the modern clipboard function to pages served over HTTPS (or opened on the machine itself), and several of those buttons had no fallback for anything else. They all share one now, so copying works over HTTP everywhere in the interface. Serving the interface over [HTTPS](https-setup.md) removes the restriction at the source.
- **The Android app no longer renders text larger than the browser does.** The app is a wrapper around the same page you open in Chrome, but Android's WebView quietly scales text by your phone's system font-size setting while Chrome ignores it and uses its own. If you had enlarged the system font even one step, everything in the app came out around 20% bigger than on the website — the title truncated to "mc-web…", longer messages wrapped earlier, and the connection status and refresh time at the bottom broke across two lines each. The app now pins text at the same size the browser uses. This is **app version 1.2** — install the new `.apk` over the one you have to pick it up; it is signed with the same key, so it goes in as an update and keeps your server address. See [android-app.md](android-app.md).
- **The bar at the bottom copes with text that does not fit.** The connection status, the region badge and the "Updated:" time sat in a row that could not wrap, so when they ran out of room each one broke apart internally instead — a green dot with "Connected" stranded underneath it, a time split from its own label. They now drop onto a second line as whole items. This mostly showed up in translated interfaces, where the labels are longer than the English ones they were laid out for ("Aktualizacja:" against "Updated:"), and on narrow phones.