Skip to content

docs: correct Docker installer local URI endpoint#417

Open
DivyamTalwar wants to merge 1 commit into
morphik-org:mainfrom
DivyamTalwar:docs/install-docker-local-uri-endpoint
Open

docs: correct Docker installer local URI endpoint#417
DivyamTalwar wants to merge 1 commit into
morphik-org:mainfrom
DivyamTalwar:docs/install-docker-local-uri-endpoint

Conversation

@DivyamTalwar

Copy link
Copy Markdown

Summary

install_docker.sh tells users who configure LOCAL_URI_PASSWORD to use /generate_local_uri, but the local URI API route is POST /local/generate_uri. This updates the Docker installer guidance so users are pointed at the endpoint that actually exists, including the required password_token form field.

Changes

  • Replace stale bash installer references to /generate_local_uri with POST /local/generate_uri.
  • Add matching PowerShell installer guidance for the same endpoint.
  • Mention that the configured password is sent as password_token in the form body.
  • Clarify that LOCAL_URI_PASSWORD protects local connection URI generation, not the entire deployment.
  • Mention that generated local connection URIs are bearer credentials.
  • Leave installer behavior, auth configuration, and API routes unchanged.

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 at POST /local/generate_uri, and core/api.py exposes that route with the password_token form 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:

  • The interactive Docker installers were not run because this PR only changes printed guidance.
  • A live request to /local/generate_uri was not run because it requires a running configured server and LOCAL_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=true behavior 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_uri API alias; the stale installer copy is the narrow problem fixed here. I also left server_mode=true guidance 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.

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
@DivyamTalwar DivyamTalwar marked this pull request as ready for review July 3, 2026 20:57
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