docs: correct Docker installer local URI endpoint#417
Open
DivyamTalwar wants to merge 1 commit into
Open
Conversation
The bash Docker installer tells self-hosted users who set LOCAL_URI_PASSWORD to use /generate_local_uri, but the local URI route is POST /local/generate_uri. Update the Docker installer guidance so users are not sent to a nonexistent endpoint after installation, point both installer paths at the required password_token form field, and clarify that generated local connection URIs are bearer credentials. Constraint: Keep this PR installer-guidance only; do not change authentication behavior, URI generation behavior, or endpoint implementation. Rejected: Add a compatibility alias for /generate_local_uri | the installer copy is the only stale reference found, and adding an API alias would expand a docs correction into runtime behavior. Confidence: high Scope-risk: narrow Directive: Keep installer endpoint guidance verified against core/api.py routes. Tested: bash -n install_docker.sh; PowerShell availability-gated parse command; rg -n "generate_local_uri|/local/generate_uri|LOCAL_URI_PASSWORD|password_token|bearer credentials|protect local connection URI generation|authorized local connection URI" install_docker.sh install_docker.ps1 core/api.py core/auth_utils.py; installer stale/external endpoint negative greps; git diff --check origin/main...HEAD Not-tested: running the interactive Docker installers; PowerShell parse check because pwsh/powershell was unavailable; calling /local/generate_uri against a live server
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
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
install_docker.shtells users who configureLOCAL_URI_PASSWORDto use/generate_local_uri, but the local URI API route isPOST /local/generate_uri. This updates the Docker installer guidance so users are pointed at the endpoint that actually exists, including the requiredpassword_tokenform field.Changes
/generate_local_uriwithPOST /local/generate_uri.password_tokenin the form body.LOCAL_URI_PASSWORDprotects local connection URI generation, not the entire deployment.Why this matters
The Docker installers are first-run paths for self-hosted deployments. If users set
LOCAL_URI_PASSWORD, the current bash guidance sends them to a nonexistent endpoint when they need an authorized local connection URI. The updated wording also avoids overstating what the password protects and reminds operators that generated local URIs are credentials.Tests
Commands run:
bash -n install_docker.sh- passed.if command -v pwsh >/dev/null 2>&1; then pwsh -NoProfile -Command '$null = [scriptblock]::Create((Get-Content -Raw install_docker.ps1)); Write-Output "PowerShell parse passed"'; elif command -v powershell >/dev/null 2>&1; then powershell -NoProfile -Command '$null = [scriptblock]::Create((Get-Content -Raw install_docker.ps1)); Write-Output "PowerShell parse passed"'; else echo "PowerShell unavailable; parse check not run"; fi- PowerShell was unavailable, so parse check was not run.rg -n "generate_local_uri|/local/generate_uri|LOCAL_URI_PASSWORD|password_token|bearer credentials|protect local connection URI generation|authorized local connection URI" install_docker.sh install_docker.ps1 core/api.py core/auth_utils.py- passed; installers now point atPOST /local/generate_uri, andcore/api.pyexposes that route with thepassword_tokenform field.if rg -n "For external access|outside this server|server_mode|public-IP detection|public IP|localhost fallback|fall back to localhost" install_docker.sh install_docker.ps1 -S; then echo "unexpected external/server-mode installer guidance remains"; exit 1; else echo "no external/server-mode installer guidance remains"; fi- passed.if rg -n "/generate_local_uri|generate_local_uri" install_docker.sh install_docker.ps1 -S; then echo "stale installer endpoint reference remains"; exit 1; else echo "no stale installer endpoint reference remains"; fi- passed.git diff --check origin/main...HEAD- passed.Not run:
/local/generate_uriwas not run because it requires a running configured server andLOCAL_URI_PASSWORD.Risk
Risk level: low code risk; medium remaining DX limitation for external URI generation
This is a small installer guidance correction with no runtime behavior change. Rollback is a direct revert of the installer message updates. External-host URI generation remains intentionally out of scope because the current
server_mode=truebehavior depends on public-IP autodetection and fallback behavior that deserves a separate reliability/docs change.Issue
No existing issue. This was discovered during repository analysis.
Notes for maintainers
I intentionally did not add a
/generate_local_uriAPI alias; the stale installer copy is the narrow problem fixed here. I also leftserver_mode=trueguidance out of the installer copy because external-host URI generation depends on public-IP autodetection and fallback behavior that deserves a separate focused docs or reliability change.