mirror of
https://github.com/turnstonelabs/turnstone.git
synced 2026-08-12 23:12:23 -06:00
Patrick Buckley
c0be383f99
* 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).
108 lines
4.3 KiB
Markdown
108 lines
4.3 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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](docs/docker.md).
|
|
- **Python package:** `pip install turnstone` (add `--pre` for the experimental
|
|
track), then run `turnstone-server` / `turnstone-console` directly. See the
|
|
[README](README.md#quickstart).
|
|
|
|
## 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.)
|
|
|
|
```bash
|
|
# 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
|
|
|
|
1. **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.
|
|
2. **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.
|
|
3. **Version check** — reports the installed version, version drift across your
|
|
cluster's nodes, and the latest upstream stable/experimental releases.
|
|
4. **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:
|
|
|
|
```bash
|
|
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.
|
|
|
|
## See Also
|
|
|
|
- [Docker Deployment](docs/docker.md) — compose stacks, ports, and bare-metal nodes
|
|
- [Security](docs/security.md) — auth architecture and token types
|
|
- [Governance](docs/governance.md) — roles, policies, and templates
|