Skip to content

mobile-https.md

Latest commit

 

History

History
80 lines (50 loc) · 3.03 KB

mobile-https.md

File metadata and controls

80 lines (50 loc) · 3.03 KB

Mobile HTTPS Setup

Mobile browsers require a secure context for service workers, Cache Storage, and several file APIs. localhost is treated as secure on the same machine, but a phone or tablet opening the launcher over the LAN needs HTTPS with a certificate the device trusts.

Recommended Docker Setup

Use the startup script for your OS. It detects your LAN IP, writes the Docker certificate host list, and starts the container.

Linux:

./start-linux.sh

macOS:

./start-macos.command

Windows PowerShell:

.\start-windows.ps1

The container creates a local root certificate authority in the Docker volume, generates a server certificate for localhost, loopback addresses, and your LAN IP, then serves:

  • Setup page: http://YOUR_LAN_IP:8000/mobile-setup
  • Secure launcher: https://YOUR_LAN_IP:8443

Open the setup page on the phone or tablet, download the certificate/profile, complete the device trust step, then open the secure launcher.

Manual Python Setup

If you are not using Docker, create a local certificate with mkcert:

mkcert -install
mkcert -cert-file cert.pem -key-file key.pem localhost 127.0.0.1 ::1 YOUR_LAN_IP
python3 server.py --host 0.0.0.0 --port 8443 --https --cert cert.pem --key key.pem

Replace YOUR_LAN_IP with the IP address your phone can reach, for example 192.168.1.20.

Open the launcher from the mobile device at:

https://YOUR_LAN_IP:8443

Device Trust

The phone must trust the local root CA. Docker serves this certificate from /certs/root-ca.crt and /certs/ios-root-ca.mobileconfig on the setup page. Mobile devices require user approval for this trust step; a local Docker app cannot silently install a trusted certificate on Android or iOS.

For manual mkcert setups, typical root certificate locations are:

  • Linux: ~/.local/share/mkcert/rootCA.pem
  • macOS: ~/Library/Application Support/mkcert/rootCA.pem
  • Windows: %LOCALAPPDATA%\mkcert\rootCA.pem

Install that root certificate on the device, then mark it as trusted for websites in the device certificate settings.

On iPhone/iPad, after installing the profile, go to Settings and enable full trust for the root certificate. On Android, install the downloaded certificate as a CA certificate, then confirm it appears under user trusted credentials.

Common Symptoms

  • service worker not available: the page is not in a trusted secure context, or the browser blocked service worker registration.
  • Launch hangs during engine download: the page could not use the cache path and fell back to slower network behavior.
  • HTTPS warning page: the certificate is not trusted by the device, or the certificate does not include the LAN IP you opened.

Quick Checks

Open /health from the mobile browser:

https://YOUR_LAN_IP:8443/health

Then run the launcher system check. It should report service workers and storage as available. If desktop works but mobile does not, the remaining issue is almost always certificate trust or using a hostname/IP not included in the certificate.