docs(user-guide): add Remote Access page#16
Merged
Conversation
mairas
force-pushed
the
docs/remote-access-vpn
branch
from
ad7d167 to
527e91b
Compare
mairas
changed the title
mairas
force-pushed
the
docs/remote-access-vpn
branch
12 times, most recently
from
98231b7 to
a921e65
Compare
HaLOS works on a LAN out of the box; the shipped default
`${hostname}.local` as canonical is the right answer for LAN-only,
marine/RV/offshore, and offline-capable deployments. This page is for
the cases that also need to reach the device from outside the LAN.
The page:
- Leads with TL;DR: don't change canonical unless you need remote
access.
- States what remote access requires: canonical must resolve from the
remote network.
- Gives two patterns that preserve on-LAN devices: per-device DNS
override on remote devices (canonical stays .local; LAN unchanged),
or split-horizon DNS at the site (canonical changes; LAN clients
including locked-down ones keep working via boat DNS).
- Hostname-choice guidance, DoH and mDNS-doesn't-tunnel gotchas,
verifying, reverting.
Cross-links updated in user-guide/networking.md and
architecture/sso.md.
Closes #15
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
mairas
force-pushed
the
docs/remote-access-vpn
branch
from
a921e65 to
6d196f1
Compare
8 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds
docs/user-guide/remote-access-vpn.mdcovering how to reach HaLOS from outside the LAN. Closes #15.Shape of the page
TL;DR up front: the shipped default is right for LAN-only, marine, offline-capable, and single-use-device-on-LAN scenarios. Don't change unless you need remote access.
States what remote access requires: canonical hostname must resolve from the remote network.
Two patterns that preserve on-LAN devices:
.local. LAN unchanged. Owner's laptop gets an/etc/hostsline; mobile uses VPN-pushed DNS or a DNS-filter app. Works for one or two remote clients.Hostname-choice guidance:
.example/.home.arpapreferred,.local/.lan/ real-TLDs avoided.Gotchas: DoH bypassing the resolver, mDNS-doesn't-tunnel.
Verify and revert sections at the end.
Cross-links updated
user-guide/networking.md— pointer to the Remote Access page.architecture/sso.md— names the single-canonical constraint and links to the user-guide page.Test plan
uv run mkdocs build --strict— clean build, no broken links or warnings.Closes #15