Skip to content

QUICKSTART.md

Latest commit

 

History

History
109 lines (84 loc) · 4.36 KB

QUICKSTART.md

File metadata and controls

109 lines (84 loc) · 4.36 KB
Raw

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 stable source with git clone --branch main https://github.com/turnstonelabs/turnstone, then run 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

  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:

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