#23578: docs(docker): clarify dashboard HTTP access and allowInsecureAuth
docs
docker
size: XS
Cluster:
Docker and Deployment Improvements
## Problem
Users running `docker-setup.sh` cannot access the dashboard due to browser secure-context requirements. HTTP contexts restrict `SubtleCrypto` (needed for device identity), causing 'device identity required' errors even with valid tokens.
## Solution
- Updated `docker-setup.sh` to print clear dashboard access instructions including the token-embedded URL
- Added new section in `docs/install/docker.md` explaining HTTP access requirements
- Documented `gateway.controlUi.allowInsecureAuth` config option for Docker/local development
- Added security notes about localhost-only bypass behavior
## Changes
1. **docker-setup.sh**: Added dashboard access instructions with HTTP requirements notice
2. **docs/install/docker.md**:
- Updated quick start section to mention HTTP access issues
- Added new "HTTP Access and allowInsecureAuth" section with:
- Explanation of secure-context restrictions
- Configuration steps for `allowInsecureAuth`
- Security notes about localhost-only bypass
## Security
The `allowInsecureAuth` option is safe for Docker/local development because it only bypasses device identity checks for **localhost** connections. Remote connections are still rejected, maintaining the MitM protection from the original security fix.
## Testing
- ✅ All quality gates passed (build, tsgo, lint, tests)
- ✅ Documentation-only changes, no code logic modifications
- ✅ Verified against Docker setup workflow
Fixes #23554
---
**AI-assisted**: Implementation and documentation by Claude (Anthropic).
**Human oversight**: Code review and testing verification.
<!-- greptile_comment -->
<h3>Greptile Summary</h3>
Adds clear dashboard access instructions and HTTP context documentation for Docker users. The changes address browser secure-context restrictions by documenting the `gateway.controlUi.allowInsecureAuth` configuration option.
**Changes:**
- `docker-setup.sh`: prints dashboard URL with token and HTTP access notice after setup
- `docs/install/docker.md`: adds new section explaining HTTP/HTTPS access requirements, `allowInsecureAuth` configuration, and localhost-only bypass behavior
**Key points:**
- Documentation correctly explains that `allowInsecureAuth` only bypasses device identity for localhost connections
- Security model verified in codebase (`src/gateway/server/ws-connection/connect-policy.ts:62-69`): remote connections are still rejected
- All links and anchors are properly formatted for Mintlify
<h3>Confidence Score: 5/5</h3>
- This PR is safe to merge - documentation-only changes with no code modifications
- Documentation accurately reflects the existing security implementation, all quality gates passed, and the changes directly address a real usability issue (issue #23554) for Docker users accessing the dashboard over HTTP
- No files require special attention
<sub>Last reviewed commit: f6b0768</sub>
<!-- greptile_other_comments_section -->
<!-- /greptile_comment -->
Most Similar PRs
#23798: docs: add Docker pairing cross-reference to Control UI page
by dglewis · 2026-02-22
81.9%
#9999: Docker: fix token mismatch and add dev setup workflow
by benclarkeio · 2026-02-06
81.2%
#8478: Security: remove --allow-unconfigured from default Dockerfile CMD
by uttej-badwane · 2026-02-04
79.9%
#21784: fix(security): restrict gateway ports to loopback by default
by smilekyra · 2026-02-20
76.6%
#11915: Docs: Docker + reverse proxy deployment notes and pairing pitfalls
by walshd1 · 2026-02-08
76.6%
#8050: fix: docker hardening
by christopherbarnett96 · 2026-02-03
75.8%
#3744: Gateway: fix device pairing when local connection retries with exis...
by photon3710 · 2026-01-29
75.7%
#13953: feat(docker): add .env template and improve Dockerfile
by n24q02m · 2026-02-11
75.6%
#9190: feat(docker): Add autonomous container self-restart and runtime pac...
by alexdredmon · 2026-02-05
75.1%
#21741: fix(gateway): allow plaintext ws:// for Docker/private network addr...
by Joe3112 · 2026-02-20
74.9%