Skip to content

fix(self-host): make first boot observable and retryable - #157

Open
tnunamak wants to merge 2 commits into
mainfrom
fix/self-host-first-run-readiness-0818
Open

fix(self-host): make first boot observable and retryable#157
tnunamak wants to merge 2 commits into
mainfrom
fix/self-host-first-run-readiness-0818

Conversation

@tnunamak

Copy link
Copy Markdown
Contributor

Why

A new Core container could return a generic error while its internal services were still starting. The generated owner password was also easy to miss because the Docker command returned only a container ID. The console's dark-mode choice did not reach the hosted owner login page. The Connect apps page also showed a one-command CLI setup that does not complete on a standard Core deployment.

What changed

  • Publish a readiness marker only after the internal authorization and data services accept connections.
  • Show a retrying startup page before readiness, while keeping a diagnostic JSON error for failures after startup.
  • Make the local Docker command private by default, restart the container automatically, and follow its logs so the first-boot password is visible.
  • Make the Compose command create a private .env, start the stack, and print the generated owner password after startup.
  • Mirror the console theme preference to the hosted login page.
  • Stop advertising the Core-incompatible one-command CLI flow on Connect apps; MCP remains the supported Core path.
  • Document the first-run behavior, persistent volume boundary, cold-start wait, and local-versus-public access choice.

Verification

  • Focused console, theme, Connect apps, and site-command tests: 32 passed.
  • Deployment template and Docker first-boot tests: 30 passed; the updated template suite alone: 19 passed.
  • Changed-code Biome checks and git diff --check: passed.
  • Console production build, site production build, console TypeScript check, and generated-artifact check: passed.
  • Fresh disposable Core image: owner login returned 200, the readiness message appeared once both internal services were listening, a dark-theme cookie produced data-theme="dark", Sources/Add rendered ChatGPT, the ChatGPT setup page returned 200, and unauthenticated MCP returned 401.
  • Existing local Core instance: completed the scoped device-approval flow, initialized MCP, listed its six tools, read the ChatGPT schema, and queried a real ChatGPT record successfully.

Scope

This does not add a password-change page; deployment configuration remains the password rotation path. It does not make the standard Core pdpp connect command work; the misleading dashboard row is removed instead. Hosted ChatGPT and Claude.ai still require a public HTTPS MCP endpoint; localhost is for local clients.

The public self-host page will use the new command after this PR is merged and the site deploy completes.

Assisted-by: AI

Record the terminal onboarding, bootstrap credential, recovery, and cold-start readiness requirements for standalone Core deployments.

Assisted-by: AI
Signed-off-by: Tim Nunamaker <tnunamak@gmail.com>
A new Core container could show a generic proxy error while its internal
services were still starting, and the generated owner password was easy to
miss because the Docker command did not follow the container logs. The
console's selected dark theme also did not reach the hosted owner login page.

Publish an explicit readiness marker after both reference services accept
connections, serve a retrying startup page before that marker, and preserve a
diagnostic JSON error for failures after startup. Make the local Docker
command loopback-only, restart-safe, and log-following. Make Compose generate
secrets with a private env file and print the owner password after startup.
Mirror the console theme preference to hosted login pages. Remove the
Core-incompatible one-command CLI entry from Connect apps rather than
advertising a flow that fails on a standard Core deployment.

Assisted-by: AI
Signed-off-by: Tim Nunamaker <tnunamak@gmail.com>
@vercel

vercel Bot commented Aug 18, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
pdpp Ready Ready Preview Aug 18, 2026 4:19am

Request Review

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