Skip to content

Add /health endpoint distinguishing setup_required from ready #47

Closed

Description

@savioruz

Summary

Currently there is no way to distinguish "server process is up and port is listening" from "server is actually usable" (past first-run setup, provider configured). A process supervisor (systemd, Docker healthcheck, a load balancer if ever relevant) needs a clear signal for this — right now the only observable behavior is that API calls return 401/errors until setup is manually completed, which is not a real readiness signal.

Fix

Add GET /api/health (unauthenticated — this must be reachable without an API key or session, since its whole purpose is pre-setup diagnostics):

// Before first-run setup completed
{ "status": "setup_required" }

// After setup, provider configured, ready to serve requests
{ "status": "ready" }

Consider a third state if useful: "status": "degraded" for cases where the server is up and setup is complete, but something non-fatal is wrong (e.g. provider unreachable at last check) — optional, don't over-engineer this if it adds complexity disproportionate to the value; setup_required vs ready covers the reported pain point on its own.

Acceptance criteria

  • GET /api/health reachable with zero auth, works even on a completely fresh unconfigured instance.
  • Returns setup_required before the admin account / provider config exists.
  • Returns ready once both are in place.
  • Document this endpoint in the README as the recommended healthcheck target for Docker/systemd, with an example Docker HEALTHCHECK or systemd ExecStartPost snippet.

Activity

  1. added this to the v0.1.0 milestone on Aug 15, 2026
  2. added
    priority-highHighest priority — must be done before next milestone
    featureNew feature or capability
    self-hostedRelates to self-hosted / local-first usage
    on Aug 15, 2026
  3. savioruz commented on Aug 24, 2026

    @savioruz
    OwnerAuthor

    Implemented & merged in PR #57. Note: PR #58 was the Candle-only slice and has since been merged into main — PR #58 (draft) is now its superset, adding #54 (setup wizard) + #45 (headless fallback) on top of this base.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    featureNew feature or capabilitypriority-highHighest priority — must be done before next milestoneself-hostedRelates to self-hosted / local-first usage

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions