Skip to content

feat(tailscale): remote access via a Tailscale sidecar - #40

Merged
erubboli merged 1 commit into
mainfrom
feat/tailscale-remote-access
Nov 14, 2026
Merged

erubboli merged 1 commit into
mainfrom
feat/tailscale-remote-access

Conversation

@erubboli

Copy link
Copy Markdown
Member

Adds a fourth access mode to the installer alongside localhost/SSH, LAN-over-HTTPS and LAN plain HTTP: a Tailscale sidecar joins the stack to your tailnet and serves the web GUI at https://<name>.<tailnet>.ts.net with a real Let's Encrypt certificate - no CA import, and nothing published to the LAN or the internet.

What it does

  • docker-compose.yml - new tailscale service under profiles: [tailscale]: official image (pinned to the stable channel tag), persistent state volume, healthcheck, /dev/net/tun + NET_ADMIN, Watchtower deliberately excluded (it sits on the trust path). The static serve config proxies only the web UI; node RPC (3030), wallet RPC (3034), Postgres and the indexer stay on the internal compose network. Funnel (public internet exposure) is deliberately not wired up.
  • init.sh - fourth access-mode option with /dev/net/tun availability gating (native Linux without the device hides the option; Docker Desktop VMs always provide it). Prompts for the node name and the join method (interactive login URL by default, or a regex-validated auth key). After first start it captures the assigned ts.net FQDN and wires WEB_GUI_HOST / PASSKEY_RP_ID / PASSKEY_ORIGIN so WebAuthn works remotely, with distinct recovery hints for join-timeout, MagicDNS-disabled and a crash-looping sidecar.
  • README / .env.example - manual setup path, prerequisites (MagicDNS + HTTPS certificates on the tailnet), security notes, explicit statement that Tailscale Funnel is not shipped.

Behavior change beyond the feature

init.sh now writes TRUST_PROXY=true for both shipped TLS-terminating access modes (the existing Caddy gateway gained it too - previously it was never written, which broke cross-site Origin derivation and degraded per-IP login rate limiting behind HTTPS; see the comment in caddy/Caddyfile and app/src/lib/csrf.ts). Direct/LAN plain-HTTP exposure keeps it unset, as before.

Installer hardening (found during review cycles)

  • atomic .env rewrite (env_set: O_EXCL temp, fsync, rename, 0600) with regression tests in tools/test-env-set.sh
  • port arithmetic hardened with 10# (a leading-zero port input used to abort the installer)
  • empty BITCOIN_NETWORK now really follows the Mintlayer network - testnet installs previously provisioned a mainnet Bitcoin node (-chain=main); testnet also maps to Core's test chain name
  • PROJECT_DIR_HOST assigned as a real shell variable - the whitespace guard previously dereferenced an unset variable under set -u, aborting every install
  • password validation unified across RPC, Postgres, BTC and UI secrets (rejects $, leading quotes, inline-comment and surrounding-whitespace hazards before they hit compose dotenv)
  • qrencode/mktemp/parse fallbacks for older tooling and macOS (no seq, bash 3.2, no GNU stat -c); QR display degrades to the URI instead of aborting
  • seeding window: sticky 1777, randomized container-side DB name (rename does not follow symlinks), traps restore 0700 on EXIT/INT/TERM/HUP, and a failed seed closes the window immediately instead of leaving it open

Out of scope (follow-ups)

  • Settings-page enable/disable of the Tailscale mode via the feature-enabler sidecar
  • docs.mintlayer.org page for the new access mode
  • Tailscale Funnel support (intentionally excluded - a wallet GUI should not get a public URL)

Fourth access mode for the installer, alongside localhost/SSH, LAN HTTPS
and LAN plain HTTP. The tailscale sidecar joins the host's tailnet and
serves the web GUI at https://<name>.<tailnet>.ts.net with a real
Let's Encrypt certificate - no host ports published, no CA import.

- docker-compose.yml: tailscale service (profile: tailscale) with
  persistent state, healthcheck, /dev/net/tun + NET_ADMIN, and a static
  serve config (Web -> web-gui:4321 only). RPC ports, Postgres and the
  indexer stay on the internal network; Funnel is deliberately not
  wired up. Watchtower does not manage this container: it sits on the
  trust path (TRUST_PROXY depends on its XFF-overwriting behavior, set
  via Header.Set in tailscaled's serve), so upgrades are deliberate.
- init.sh: access-mode chooser with /dev/net/tun gating (native Linux
  only; Docker Desktop VMs always provide it), node-name and auth-key
  prompts (tskey-auth- regex validated - compose would otherwise expand
  dollar-vars in .env values), post-start join flow that captures the
  ts.net FQDN and wires WEB_GUI_HOST/PASSKEY_* for WebAuthn, with
  distinct recovery hints for join-timeout, MagicDNS-disabled and a
  crash-looping sidecar. TRUST_PROXY=true is written for the shipped
  proxy modes (caddy gains it too - previously missing, which broke
  cross-site Origin derivation and per-IP rate limiting behind TLS).
- installer hardening found during review: atomic .env rewrite
  (env_set, O_EXCL temp + fsync + rename), port arithmetic with 10#
  (leading-zero input used to crash), BITCOIN_CORE_CHAIN follows the
  Mintlayer network on empty BITCOIN_NETWORK (testnet installs used to
  get a mainnet Bitcoin node), qrencode/parse fallbacks for older
  qrencode and macOS hosts (no seq, bash 3.2), password policy shared
  between RPC and UI secrets (dollar signs, quotes, inline-comment and
  whitespace hazards rejected before they hit compose dotenv), 1777
  seeding window closed via sticky bit, randomized container-side DB
  name (rename does not follow symlinks) and trap-restore on all
  signal paths.
- tools/test-env-set.sh: regression tests for the .env rewrite helper
  and the Tailscale status parser.
- .env.example + README: Tailscale section, prerequisites, security
  notes.
@erubboli
erubboli merged commit f8a0aa5 into main Nov 14, 2026
15 checks passed
@erubboli
erubboli deleted the feat/tailscale-remote-access branch November 14, 2026 14:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant