Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 27 additions & 7 deletions .env.example
Original file line number Diff line number Diff line change
Expand Up @@ -62,15 +62,35 @@ WEB_GUI_TLS_PORT=443
# Interface the HTTPS port binds to (0.0.0.0 = whole LAN).
WEB_GUI_TLS_BIND=0.0.0.0
# CADDY_IMAGE=caddy:2-alpine
# TRUST_PROXY: set true ONLY when requests arrive through the shipped caddy
# gateway (web profile). Caddy overwrites X-Forwarded-For with the real
# client IP (see caddy/Caddyfile), so with TRUST_PROXY=true the app can
# safely use it for per-IP rate limiting AND derive the browser-visible
# https:// Origin - without it, every form POST behind caddy would 403 on
# the cross-site check. Direct/LAN exposure (WEB_GUI_TLS=false, no caddy)
# must keep TRUST_PROXY unset: X-Forwarded-* is attacker-controllable then.
# TRUST_PROXY: set true ONLY when requests arrive through a shipped proxy -
# the caddy gateway (web profile) or the Tailscale sidecar (tailscale
# profile). Both overwrite X-Forwarded-For with the real client IP, so with
# TRUST_PROXY=true the app can safely use it for per-IP rate limiting AND
# derive the browser-visible https:// Origin - without it, form POSTs
# behind them would 403 on the cross-site check. Direct/LAN exposure
# (WEB_GUI_TLS=false, no caddy/tailscale) must keep TRUST_PROXY unset:
# X-Forwarded-* is attacker-controllable then.
TRUST_PROXY=

# ── Remote access via Tailscale (optional, profile: tailscale) ─────
# The tailscale sidecar joins your tailnet and serves the web GUI over it at
# https://<TAILSCALE_HOSTNAME>.<tailnet>.ts.net - valid HTTPS (certificate
# provisioned by Tailscale), no host ports published to LAN/internet.
# Start with: docker compose --profile tailscale up -d
# Prerequisites (one-time, Tailscale admin console): MagicDNS + HTTPS
# certificates enabled. Needs /dev/net/tun on the Docker host (Docker
# Desktop VMs provide it; unprivileged LXC / rootless Docker may not).
TAILSCALE_HOSTNAME=nexus
# tskey-auth-... joins headlessly (init.sh stores it here; this file must be
# chmod 600 and gitignored). Empty = interactive login URL printed in the
# sidecar logs on first start: docker compose logs -f tailscale
TS_AUTHKEY=
# Optional 'tailscale up' extras, e.g. --advertise-tags=tag:nexus
# (recommended so a tailnet ACL can scope this device, dst tag:nexus:443).
# NOTE: compose expands $VAR/${VAR} in .env values - escape a literal '$' as '$$'.
TS_EXTRA_ARGS=
# TAILSCALE_IMAGE=tailscale/tailscale:latest

# ── Passkeys (WebAuthn) ───────────────────────────────
# Set by init.sh from WEB_GUI_HOST. Override only if behind a reverse proxy
# that rewrites the hostname (e.g. your Node process sees a different URL
Expand Down
29 changes: 17 additions & 12 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,15 +1,20 @@

# documentation
wiki/
TODO.md

# Environment
/wiki/
/TODO.md

# Environment / credentials - init.sh writes .env, env_set() rewrites via
# temp files (.env.tmp.<pid>, credentials mid-rewrite) and pre-rewrite
# backups (.env.bak.*). Enumerated (not .env*) so unrelated files like
# direnv's .envrc stay trackable. .env.example is the only tracked env file
# - placeholders only, never real credentials. Note: .gitignore comments
# must start the line; no inline '#'s.
.env
.env.dev
.env.*
!.env*.example

# Node
node_modules/
app/node_modules/

# Astro build output
app/dist/
Expand All @@ -19,17 +24,17 @@ app/.astro/
app/coverage/

# Mintlayer data directory (node + wallet files)
mintlayer-data/
/mintlayer-data/

# Docker volumes
postgres-data/
/postgres-data/

# OS
.DS_Store
Thumbs.db

# Tauri
/windows/src-tauri
# Windows/Tauri experiment (reverted in 4903559); re-ignore if it returns
/windows/src-tauri/

# Editor
.vscode/
Expand All @@ -40,7 +45,7 @@ Thumbs.db
*.swo

# Bitcoin (optional, profile: bitcoin)
bitcoin-data/
bitcoin-wallet-data*/
/bitcoin-data/
/bitcoin-wallet-data*/
bdk-wallet/target/
.ecc/
64 changes: 63 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -135,7 +135,68 @@ After creating your wallet at <http://localhost:4321/setup>, the dashboard at <h
> plain-HTTP LAN hostname (e.g. `http://192.168.1.50:4321`) will silently fail.
> By default the GUI also binds to `127.0.0.1` only - set `WEB_GUI_BIND=0.0.0.0`
> in `.env` to expose it, and put a TLS reverse proxy in front for real remote
> access.
> access - or skip port publishing entirely with the
> [Tailscale profile](#remote-access-via-tailscale).

### Remote access via Tailscale

Run `./init.sh` and pick **Tailnet (Tailscale)** as the access mode: it joins
the stack to your tailnet, captures the assigned `https://<name>.<tailnet>.ts.net`
name, and derives the passkey (WebAuthn) settings from it. Manual setup:

```bash
# .env - keep comments on their own line (inline '#' handling varies by
# compose version and would corrupt the values)
TAILSCALE_HOSTNAME=nexus
# empty: first start prints a login URL in the logs
TS_AUTHKEY=
# REQUIRED for manual setup: login POSTs 403 behind the sidecar without it
TRUST_PROXY=true
# TS_EXTRA_ARGS=--advertise-tags=tag:nexus

docker compose --profile tailscale up -d
docker compose logs -f tailscale # login URL on first start (no key set)
```

After approving the login URL, wire the assigned name into `.env` (this is
what init.sh automates):

```bash
docker compose exec tailscale tailscale status --json # Self.DNSName = your ts.net name
```

```bash
# .env - WEB_GUI_HOST and PASSKEY_RP_ID take the BARE name (no https://);
# only PASSKEY_ORIGIN carries the scheme. Then restart web-gui:
WEB_GUI_HOST=nexus.<tailnet>.ts.net
PASSKEY_RP_ID=nexus.<tailnet>.ts.net
PASSKEY_ORIGIN=https://nexus.<tailnet>.ts.net
```

```bash
docker compose up -d web-gui
```

What you get:

| | |
|---|---|
| URL | `https://nexus.<tailnet>.ts.net` - valid Let's Encrypt certificate, no CA import like the Caddy mode |
| Exposure | none on the host - only tailnet devices reach the sidecar; the LAN and the internet see nothing |
| Auth | the app's password + TOTP login still applies (matters on shared tailnets) |
| Scope | web UI only - node RPC (3030), wallet RPC (3034), Postgres and the indexer stay on the internal compose network |

Prerequisites (one-time, Tailscale admin console): **MagicDNS** and **HTTPS
certificates** enabled. The Docker host needs `/dev/net/tun` (kernel-mode
networking; Docker Desktop VMs provide it, unprivileged LXC and rootless
Docker may not). Local access on the host keeps working at
`http://localhost:4321`.

Optional hardening: tag the node (`TS_EXTRA_ARGS=--advertise-tags=tag:nexus`)
and add a tailnet ACL rule scoping reachability to it (`dst: tag:nexus:443`).

> Tailscale **Funnel** (a public internet URL) is deliberately not wired up -
> a wallet GUI must not get a public link.

> **Sync time:** balance and transaction history only appear once the node has fully synced. On first run this takes several hours for mainnet. The dashboard shows the current block height so you can track progress.

Expand Down Expand Up @@ -385,3 +446,4 @@ docker compose restart web-gui
- Wallet RPC credentials are never sent to the browser - all calls are proxied server-side by the Astro app.
- Only a fixed allowlist of RPC methods is callable through the `/api/rpc` endpoint.
- The wallet RPC (3034) and node RPC (3030) ports are not exposed to the host by default.
- The optional Tailscale sidecar (profile: `tailscale`) serves only the web UI over your tailnet - RPC ports stay on the internal compose network, and Funnel (public URLs) is not shipped.
87 changes: 83 additions & 4 deletions docker-compose.yml
Original file line number Diff line number Diff line change
Expand Up @@ -131,10 +131,15 @@ services:
HOST: "0.0.0.0"
# Settings -> HTTPS section renders only when the gateway is enabled
WEB_GUI_TLS: "${WEB_GUI_TLS:-false}"
# Gate for proxy-derived headers (client IP + Origin): set true ONLY when
# traffic arrives through the shipped caddy gateway, which overwrites
# X-Forwarded-For with the real client IP. Direct/LAN exposure must keep
# it unset - X-Forwarded-* is attacker-controllable then.
# Gate for proxy-derived headers (client IP + Origin): set true ONLY
# when traffic arrives through a shipped proxy that overwrites
# X-Forwarded-For with the real client IP: the caddy gateway
# (header_up XFF {client_ip}, see caddy/Caddyfile) or the tailscale
# sidecar (tailscale serve Set()s XFF from the WireGuard peer address -
# addProxyForwardedHeaders in tailscale's ipn/ipnlocal/serve.go, which
# also clears client-supplied Tailscale-* identity headers). Direct/LAN
# exposure must keep it unset - X-Forwarded-* is attacker-controllable
# then.
TRUST_PROXY: "${TRUST_PROXY:-}"
# WebAuthn: init.sh writes these into .env; without the passthrough
# compose never injects them and passkeys silently fail on TLS setups.
Expand Down Expand Up @@ -435,9 +440,83 @@ services:
- web
restart: unless-stopped

# ─────────────────────────────────────────
# Remote access via Tailscale (profile: tailscale)
#
# Joins the node to your Tailscale network and serves the web GUI over it:
# https://<TAILSCALE_HOSTNAME>.<tailnet>.ts.net
# valid HTTPS (certificate provisioned by Tailscale, no CA import), with no
# ports published to the host LAN or the internet. Requires MagicDNS + HTTPS
# certificates to be enabled for the tailnet (admin console, one-time).
#
# Threat model: only the web GUI is reachable through the sidecar. Node RPC
# (3030), wallet RPC (3034), Postgres and the indexer stay on the internal
# compose network, and the app's password + TOTP login still applies (it
# matters on shared tailnets). Funnel (public internet exposure) is
# deliberately not wired up - a wallet GUI must not get a public URL.
#
# Kernel-mode networking (/dev/net/tun + NET_ADMIN). Hosts without a TUN
# device (unprivileged LXC, rootless Docker, some NAS) cannot run this
# service; Tailscale's own userspace networking mode is the upstream escape
# hatch (tailscale.com/kb - userspace networking) but is not shipped here.
#
# First start without TS_AUTHKEY prints a login URL in this container's
# logs: docker compose logs -f tailscale
# ─────────────────────────────────────────
tailscale:
image: "${TAILSCALE_IMAGE:-tailscale/tailscale:stable}"
hostname: "${TAILSCALE_HOSTNAME:-nexus}"
# Deliberately NOT watchtower-managed (watchtower runs --label-enable):
# this sidecar sits on the trust path - TRUST_PROXY=true depends on its
# XFF-overwriting behavior - so upgrade it deliberately
# (docker compose pull tailscale). Default tag :stable tracks the
# Tailscale stable channel (not :latest); override via TAILSCALE_IMAGE.
depends_on:
- web-gui
environment:
# State must persist, or the node re-authenticates (new tailnet
# identity) on every restart.
TS_STATE_DIR: "/state"
TS_HOSTNAME: "${TAILSCALE_HOSTNAME:-nexus}"
# Empty = interactive login URL in the logs. A tskey-auth-... here
# joins headlessly (init.sh stores it in .env, 0600 + gitignored).
TS_AUTHKEY: "${TS_AUTHKEY:-}"
# Keep existing state across restarts even when TS_AUTHKEY is rotated.
TS_AUTH_ONCE: "true"
# Never adopt tailnet DNS settings: compose service names (web-gui,
# wallet-rpc-daemon, ...) must keep resolving via Docker's DNS.
TS_ACCEPT_DNS: "false"
TS_USERSPACE: "false"
# Serves the GUI on the tailnet at ${TS_CERT_DOMAIN}:443 - see
# ./tailscale/serve-config.json.
TS_SERVE_CONFIG: "/config/serve-config.json"
# Optional 'tailscale up' extras, e.g. --advertise-tags=tag:nexus
# (recommended so a tailnet ACL can scope this device).
TS_EXTRA_ARGS: "${TS_EXTRA_ARGS:-}"
volumes:
- "tailscale-state:/state"
- "./tailscale:/config:ro"
devices:
- "/dev/net/tun:/dev/net/tun"
cap_add:
- NET_ADMIN
healthcheck:
# --json exits 0 whenever tailscaled answers, including NeedsLogin;
# plain status exits 1 ("Logged out.") and would mark the sidecar
# unhealthy for the whole login-approval window.
test: ["CMD", "tailscale", "status", "--peers=false", "--json"]
interval: "30s"
timeout: "10s"
retries: "5"
start_period: "30s"
profiles:
- tailscale
restart: unless-stopped

volumes:
postgres-data:
caddy-data:
caddy-config:
ca-public:
feature-requests:
tailscale-state:
Loading
Loading