mirror of https://github.com/MarekWo/mc-webui.git synced 2026-07-30 05:23:21 +02:00

Files

T

MarekWo 0cbab03ab8 feat(android): add wrapper sources and fix the address, camera and downloads

The wrapper is what users sideload, so its source belongs next to the APK -
they can read what they install, or build it themselves.

Behaviour fixes on the way in (APK rebuild pending):

- The saved server address survives. Back on the first page and connection
  errors used to delete it, so a stray tap or a moment without signal meant
  typing the address again; the form now opens pre-filled and only a save
  replaces what is stored. Back at the top level asks: exit, change server,
  or cancel
- QR scanning works: the page's camera request is mirrored to an Android
  permission request (CAMERA, on an https instance - getUserMedia needs a
  secure context, as in any browser)
- Downloads work: a DownloadListener hands database backups and other files
  to DownloadManager, which puts them in the phone's Downloads folder
- Links to other hosts and non-http schemes open in the system browser, so
  a URL in a message no longer navigates the app away from the instance
- Rotating the screen no longer reloads the page

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2026-07-28 21:05:42 +02:00

6.9 KiB

Raw Blame History

mc-webui for Android

A small companion app that opens your own mc-webui instance full screen — no address bar, no browser tabs, its own icon in the app drawer. It looks and works like a native app, because underneath it is the same web interface you already use in the browser.

The app contains no mesh logic of its own: it asks once for the address of your mc-webui server and displays it. Everything still runs on your server and your MeshCore device.

The app is not distributed through Google Play — you download the .apk file from this repository and install it yourself. That is a normal and supported way to install Android apps, but Android will warn you a few times along the way. The steps below cover those warnings.

What you need

Android 5.0 (Lollipop) or newer
A running mc-webui instance the phone can reach — either on the same local network (e.g. http://192.168.1.100:5000) or published over the internet through a reverse proxy (e.g. https://mc-webui.example.com)

Step 1: Download the app


File	`android/mc-webui-wrapper.apk`
Direct link	https://github.com/MarekWo/mc-webui/raw/main/android/mc-webui-wrapper.apk
Size	5.7 MB
App version	1.0
Package	`it.wojtaszek.mc.wrapper`
SHA-256	`12e1e388e01a68e0de73672808033a2ff8417df7075a229e3be9eccc6f7ff82c`

Download it directly on the phone, or copy it over from a computer.

Optional — verify the file. Only worth doing if you got the file from somewhere other than this repository:

# Linux / macOS
sha256sum mc-webui-wrapper.apk

# Windows (PowerShell)
Get-FileHash mc-webui-wrapper.apk -Algorithm SHA256

The result must match the SHA-256 above.

Step 2: Allow installation from unknown sources

Android only installs apps from Google Play unless you allow the app that is doing the installing — usually your browser or the Files app — to install others. You grant that permission once, and it applies to that app only.

The easy way — just start the installation (Step 3). When Android says "For your security, your phone is not allowed to install unknown apps from this source", tap Settings, turn on Allow from this source, and press back. The installation continues.

Up front, if you prefer — Settings → Apps → Special app access → Install unknown apps → pick the browser or file manager you will use → Allow from this source. The exact wording varies by manufacturer (Samsung, Xiaomi, and others each name it slightly differently).

Step 3: Install

Open the downloaded mc-webui-wrapper.apk — from the browser's download notification, or from Files → Downloads
Tap Install
Play Protect may show "Unsafe app blocked" or "App scan recommended". This is Google's standard notice for apps that did not come from the Play Store — it is not a detection of anything in the app. Choose More details → Install anyway (or Don't send / Install if it offers to upload the file for scanning)
Tap Open, or launch mc-webui from the app drawer

To remove it later: long-press the icon → Uninstall, like any other app.

Step 4: Connect to your instance

On the first run the app asks for the address of your server:

Type the full address, including the protocol and — for a local instance — the port:

Your setup	What to enter
mc-webui on the local network	`http://192.168.1.100:5000`
Behind a reverse proxy with a certificate	`https://mc-webui.example.com`
On a non-standard port behind a proxy	`https://mc-webui.example.com:8443`

Then tap SAVE & CONNECT.

Type http:// explicitly for local instances. If you leave the protocol out, the app assumes https:// and the connection to a plain local server will fail.

The address is remembered, so every later launch goes straight into mc-webui.

Changing the address later

The app returns to the address screen when you press Back on the main mc-webui page, and also when it cannot reach the server (wrong address, server down, phone off the network). Enter the address again — corrected if it was wrong, unchanged if the server was simply unreachable — and tap SAVE & CONNECT.

What works, and what doesn't

Everything you do in mc-webui itself works exactly as in the browser: channels, direct messages, contacts, the console, My Repeaters, the Path Analyzer, maps, settings, themes. A few things live outside the page and are not wired up in this version of the wrapper:

Feature	In the app	Instead
Notifications for new messages	Not available — the app has no access to the browser notification system	Install mc-webui as a PWA in Chrome for notifications (how); the two can live side by side
Scanning a QR code (Add Contact → Scan QR)	Not available — the app does not request camera access	Paste URI or Manual entry on the same screen
Downloading files (database backup, saving a QR image)	Does nothing when tapped	Do it from a browser on the phone or from a computer
HTTPS with a self-signed certificate	Refused, with an "SSL Error" message	Use a valid certificate (e.g. Let's Encrypt), or plain `http://` on the local network

Security notes

Install the .apk only from this repository (or from the project's GitHub Releases page). An .apk from anywhere else is a different app, no matter what it is called
The app stores exactly one thing on the phone: the server address you typed. No messages, keys, or contacts — those stay on your server and your MeshCore device
Plain http:// is allowed so that local instances work without a certificate. On a home network that is fine; over the internet, put mc-webui behind a reverse proxy with HTTPS and some form of access control — the app adds no authentication of its own
The app requests a single Android permission: internet access

How it is built

A minimal Android WebView wrapper: one screen for the server address, one full-screen WebView for mc-webui itself, and a saved preference between them. No analytics, no third-party services, no background activity — when the app is closed, nothing of it runs.

The complete source is in android/src/, and android/README.md describes how to build it yourself if you would rather not trust a prebuilt .apk.

6.9 KiB Raw Blame History