Self-hosted Mqttable Web on Linux
Install the candidate Linux x86_64 Web server package, configure HTTPS, initialize the Owner, and preserve state safely.
- Author:
- Mqttable
- Updated:
On this page8 sections
Loading...
/docs/engineer/self-hosted-web
Install the candidate Linux x86_64 Web server package, configure HTTPS, initialize the Owner, and preserve state safely.
Loading...
This is the Mqttable Web server, not the Linux Desktop app. Packages are release candidates until a verified stable manifest is published. The supported candidate targets are Debian 12 and Ubuntu 24.04 (amd64 DEB), and Rocky Linux 9 (x86_64 RPM). No ARM64 or other Linux distribution is claimed.
This is a private, single-owner workbench, not a hosted multi-user service. The Owner can use desktop-equivalent Free capabilities; only existing Pro capabilities require a current Pro entitlement. A reachable mqttable.com authorization service is required for sign-in, Owner binding, and Pro activation; do not expose a production instance before its matching instance API is available.
When the download page offers a Web package, select the DEB or RPM for your system. Verify the published SHA-256 before installation. The page's copyable command downloads over HTTPS, checks SHA-256 with sha256sum -c -, then invokes the native package manager. If the Web section says unavailable or not published, do not guess a package URL or reuse a Desktop installer.
Install the verified local file with sudo apt install ./mqttable-web.deb or sudo dnf install ./mqttable-web.rpm. Package installation creates a dedicated mqttable-web user, /etc/mqttable-web/mqttable-web.env, root-only /etc/mqttable-web/secrets.env, and /var/lib/mqttable-web. It does not start or enable the service. Keep the generated secrets and data directory private. Do not put secret values in the non-secret settings file. The package contains no reusable RPC cookie; the instance creates its own under the private data directory on first start and reuses it after restarts.
Edit /etc/mqttable-web/mqttable-web.env as an administrator. Set PHX_HOST to the one public DNS hostname and choose exactly one MQTTABLE_WEB_TLS_MODE:
acme (package default): direct HTTPS on PORT=443, HTTP-01 challenge on public port 80. Set MQTTABLE_ACME_EMAIL yourself. Read the CA terms, then explicitly set MQTTABLE_ACME_ACCEPT_TERMS=true; the installer never does this for you. MQTTABLE_ACME_ENV=staging is for tests and produces a certificate not trusted by normal browsers.manual: direct HTTPS with your own valid certificate. Set absolute MQTTABLE_TLS_CERTFILE and MQTTABLE_TLS_KEYFILE paths. The certificate must cover PHX_HOST; the service account must be able to read the files. For /etc/mqttable-web files, use root:mqttable-web ownership and 0640 permissions, especially for the private key. Renewal/replacement is your responsibility.proxy: put an administrator-managed HTTPS reverse proxy on the same host in front of the loopback-only PORT=51883 HTTP listener; set PHX_PORT=443 and preserve the exact external Host, HTTPS scheme, and WebSocket upgrade. Never expose the internal HTTP, local MCP (127.0.0.1:51884 by default), or RPC (127.0.0.1:6789) listeners publicly.The Docker image is separate: its Web listener remains 51883 behind a host HTTPS reverse proxy. Do not copy the native package's direct-443 configuration into the Docker example.
After checking your settings and network policy, explicitly run sudo systemctl enable --now mqttable-web.service. Inspect systemctl status mqttable-web.service and visit https://<your-host>/instance only with a trusted certificate. The package does not open firewall ports. Do not bypass browser TLS checks to make a staging certificate appear valid.
On the server, run sudo mqttable-web setup. The short-lived code is printed only to your terminal. Enter it on the instance's /instance page, complete the mqttable.com account confirmation, then explicitly bind that account as Owner. Merely visiting the page does not claim the instance. One private instance admits one bound Owner; a different Pro account cannot enter.
The setup code expires after 15 minutes; issuing another code invalidates the previous one. Once website confirmation starts, its request has a separate 10-minute expiry. Restart that step if it expires, and return to the original instance browser to complete binding.
Use sudo systemctl status mqttable-web.service, sudo journalctl -u mqttable-web.service -n 100 --no-pager, and sudo mqttable-web tls-status. The last command reports redacted certificate health, not the private key. Check DNS, certificate name/validity, port 80 challenge reachability, port 443 reachability, service file permissions, and the exact public Host before retrying. The public /mcp path is intentionally denied; do not proxy the local MCP listener.
Losing Pro does not lock the Owner out of Web. Existing normal MQTT connections remain; scheduled messages, Replay, Bench, and proxy toxic schedules stop or pause until deliberately restarted within current limits. Damaged instance state fails closed: use the explicit operator recovery procedure in the product private-Web documentation instead of deleting state or changing secrets to select another Owner.
Before replacing a package, make a protected backup of both /var/lib/mqttable-web and /etc/mqttable-web/secrets.env, plus /etc/mqttable-web/mqttable-web.env and any manually supplied TLS certificate/key files. Stop the service for a consistent copy; restore only by explicit administrator action to the same package version, with ownership and permissions intact. The browser data export is not a complete server backup. There is no automatic downgrade or migration promise. Install a verified newer package with the same package manager, inspect status, then restart explicitly if your service was stopped. Package removal stops/disables the unit; persistent data and secrets are retained, so remove them separately only when you intentionally want to destroy the instance.
For HTTP-01, your single public DNS name must resolve to this host, and inbound public TCP 80 must reach it during issuance and renewal. Public HTTPS on 443 (or your explicitly chosen direct HTTPS port) must also be reachable by users. Do not claim ACME is ready from a local private-CA test. If the CA is unreachable or validation fails, inspect the journal and TLS status, repair DNS/network/terms/account settings, and retry deliberately rather than repeatedly requesting certificates. Staging chains are not production-trusted; use production only after authorized release acceptance. Back up the persistent ACME account and certificates with the data directory. Never expose ACME account keys or private keys in logs or support tickets.