mirror of https://github.com/turnstonelabs/turnstone.git synced 2026-08-12 23:12:23 -06:00

Files

T

Patrick Buckley c0be383f99 refactor(doctor): replace turnstone-bootstrap with turnstone-doctor (#718 )

* refactor(doctor): replace turnstone-bootstrap with turnstone-doctor

turnstone-bootstrap was an LLM setup wizard for Day-0; run.sh now owns install.
Repurpose its LLM/conversation plumbing into turnstone-doctor — a diagnose-only
tool for a running cluster.

- Preflight detects the install kind (docker-compose/systemd/pip/source) from
  config.toml + TURNSTONE_* env, with secret redaction.
- Self-configuring brain resolves the cluster's own model from config/env/storage
  read-only (no migrations, no create_all), falling back to interactive
  selection; the attempt itself is the LLM-backend health check.
- Deterministic version check: installed version, cluster drift via the console's
  authoritative /health, and latest upstream stable/experimental (offline-safe).
- Read-only diagnostic tools (read_file, compose/systemd/journal, http_health,
  check_llm_backend, node_health, finish) behind one secret-scrubbing chokepoint;
  no generic shell, so read-only is structural.
- node_health reaches a node the right way for the detected install kind
  (exec-into-container for compose, direct HTTP otherwise), overridable per node
  for mixed clusters.
- mTLS-aware: forwards [database] SSL params and reports node-mesh mTLS instead of
  mislabelling healthy nodes "unreachable".

init_storage gains a backward-compatible create_tables override for read-only
opens. Entry point turnstone-bootstrap -> turnstone-doctor; README/QUICKSTART/
architecture/docker docs, the bundled compose header, run.sh, and the CI smoke
updated. CHANGELOG deferred.

* fix(doctor): address Copilot + CodeQL review findings on #718

Validated all seven review findings (none false positives) and fixed:

- check_llm_backend now applies the same scheme / metadata-host guard as
  http_health (extracted to _assert_safe_http_url), so a model-supplied
  base_url can't be steered at the cloud metadata endpoint or a file:// URL.
- node_health no longer double-appends the default port when the operator
  passes host:port (regression: 10.0.0.5:8081 -> http://10.0.0.5:8081:8080).
- node_health install_type enum uses "git-source" to match the label the
  rest of the module and the prompt/report show the model (a schema-strict
  provider would otherwise reject the value the model is told to use).
- _read_api_creds takes base_url + api_key as a unit from the first config
  source that defines either field, then env-fills, instead of splicing the
  two across different config files into a pair that exists in no real config.
- _mask_secrets masks assignment-shaped content inside comment lines, so a
  commented-out real secret can't leak through read_file / the report; prose
  comments (no KEY=value shape) still pass through untouched.
- drop the mixed import styles CodeQL flagged in doctor.py and test_doctor.py.

Adds 5 tests; ruff + mypy clean; full doctor suite passes (129).

2026-06-26 04:57:20 -07:00

4.3 KiB

Raw Permalink Blame History

Quickstart

Install Turnstone, then diagnose it with turnstone-doctor if anything looks off.

Install

The one-line installer autodetects your distro (Ubuntu/Debian, Fedora/RHEL, Arch, and WSL), installs git + Docker if missing, generates secrets, picks free ports, and starts the stack:

curl -fsSL https://raw.githubusercontent.com/turnstonelabs/turnstone/main/run.sh | bash

Re-running is safe — it updates the checkout and keeps your existing .env. When it finishes it prints the dashboard URL and how to create the first admin user.

Other ways to install

Already have Docker? Clone the repo and docker compose up for the full local cluster, or docker compose -f turnstone/deploy/compose.yaml up for the released single-node stack. See docs/docker.md.
Python package: pip install turnstone (add --pre for the experimental track), then run turnstone-server / turnstone-console directly. See the README.

Diagnose: `turnstone-doctor`

turnstone-doctor is an LLM-backed assistant that inspects a running Turnstone install and helps you troubleshoot it. It is read-only — it investigates and tells you the exact commands to fix things, but never changes your system. (Installation is the installer's job, not the doctor's.)

# From a host that has the turnstone package installed:
turnstone-doctor

# For a Docker install from run.sh (no package on the host), run it with pipx:
pipx run --spec turnstone turnstone-doctor --dir ~/turnstone

What it does

Preflight — detects how Turnstone is installed here (docker-compose, systemd/bare-metal, pip, or a source checkout) by probing for config.toml files, TURNSTONE_* environment variables, compose files, and systemd units.
Self-configures its LLM — it powers its own brain from your cluster's own model configuration (env / config.toml / the database). Whether that works is the first diagnostic: success means your LLM backend is healthy; if it can't, that's surfaced as finding #1 and it falls back to asking you for a provider and key so it can still help.
Version check — reports the installed version, version drift across your cluster's nodes, and the latest upstream stable/experimental releases.
Interactive diagnosis — it reads logs, /health, docker compose ps, systemctl, config, and ports to pin down problems like a node not joining the console, an unreachable database, a down model backend, port conflicts, or a JWT-secret mismatch — then hands you the precise remediation commands.

Flags

Flag	Purpose
`--dir PATH`	Install directory to inspect (default: current directory)
`--report`	Print the deterministic preflight report and exit — no LLM key needed
`--offline`	Skip the upstream GitHub version check

--report is the fastest way to get a health snapshot (and to share one when asking for help) — it never needs an API key:

turnstone-doctor --report --dir ~/turnstone

## Install profile
- Detected kind(s): docker-compose  (primary: docker-compose)
- Docker daemon reachable: yes
- Compose files:
    /home/you/turnstone/compose.yaml
- Database: backend=postgresql, url=postgresql+psycopg://turnstone:****@postgres:5432/turnstone
- Candidate health URLs: http://localhost:8080/health, http://localhost:8090/health

## Versions
- Installed (this tool): 1.7.0a2
- Cluster nodes: 10 reporting; versions ['1.7.0a2']
- Version drift across nodes: no
- Upstream: stable 1.6.9, experimental 1.7.0a2

## LLM backend (ok)
- resolved Qwen/Qwen3-32B via openai-compatible @ http://host.docker.internal:8000/v1

Secrets (JWT secret, database password, API keys) are always redacted in the report and in anything the doctor reads.

Tips

Type quit to exit the conversation; Ctrl+C interrupts (twice to quit).
Point it at the right install with --dir when you run it from elsewhere.
(Re)installing or adding nodes? Use the installer (run.sh), not the doctor.

4.3 KiB Raw Permalink Blame History