Skip to content

getting-started.md

Latest commit

 

History

History
120 lines (93 loc) · 3.51 KB

getting-started.md

File metadata and controls

120 lines (93 loc) · 3.51 KB

Getting started

This guide walks you from zero to a running docsiq server with one project indexed and the MCP endpoint answering queries.

Prerequisites

  • Go 1.22 or newer — required to build from source. 
    go version
# go version go1.22.x ...
  • A C toolchain — docsiq links the mattn/go-sqlite3 driver with CGO enabled, so you need a working C compiler.
    • Linux (Debian / Ubuntu): sudo apt install build-essential
    • Linux (Fedora / RHEL): sudo dnf install @development-tools
    • macOS: xcode-select --install
    • Windows: MinGW-w64 / MSYS2 with gcc on PATH, or WSL2
  • Git — docsiq init reads the current repo's origin remote.
  • An LLM backend — either a local Ollama daemon or an Azure OpenAI / OpenAI API key. The defaults point at Ollama on http://localhost:11434.

Install

GOFLAGS='-tags=sqlite_fts5' go install github.com/RandomCodeSpace/docsiq@latest

The sqlite_fts5 build tag is required — docsiq uses SQLite's FTS5 full-text-search extension. Without it the binary fails at runtime with no such module: fts5 when opening a project store. go install does not pick up Makefile tags, so the flag has to come from GOFLAGS (or -tags) on the install command itself.

This drops a docsiq binary into $(go env GOPATH)/bin. Make sure that path is on your PATH.

Alternatively, build from a checkout:

git clone https://github.com/RandomCodeSpace/docsiq.git
cd docsiq
CGO_ENABLED=1 go build -tags sqlite_fts5 -o docsiq .

First project

  1. Create a default config (optional — every field has a sensible default, so you can skip this step and re-run with --config later).

    mkdir -p ~/.docsiq
cp config.example.yaml ~/.docsiq/config.yaml
$EDITOR ~/.docsiq/config.yaml

  2. From inside any git checkout, register a project:

    cd ~/src/my-repo
docsiq init
# ✅ project registered
#   slug:   my-repo
#   name:   my-repo
#   remote: git@github.com:you/my-repo.git
#   db:     ~/.docsiq/data/projects/my-repo/docsiq.db

  3. Index a directory of documents (PDF / DOCX / MD / TXT) into that project:

    docsiq index ./docs --project my-repo
docsiq index ./docs --project my-repo --finalize   # runs community detection

    Or crawl a documentation site:

    docsiq index --url https://example.com/docs/ --project my-repo

Start the server

docsiq serve
# ⚙️ resolved LLM config provider=ollama
# 🌐 listening http://127.0.0.1:8080

Flags --host / --port override server.host / server.port in the config. The MCP Streamable HTTP transport is served at /mcp; the embedded Web UI is served at /.

Smoke test

# Liveness probe — always public, never gated by auth.
curl -s http://127.0.0.1:8080/health
# {"status":"ok"}

# Project-scoped stats (bearer auth only when server.api_key is set).
curl -s -H "Authorization: Bearer $DOCSIQ_API_KEY" \
  "http://127.0.0.1:8080/api/stats?project=my-repo"

If /health returns {"status":"ok"} you have a working install. Point your AI client's MCP config at http://127.0.0.1:8080/mcp and optionally run docsiq hooks install --client claude to register the SessionStart hook.

Next steps

  • Configuration — swap providers, set an API key, tune chunk size
  • MCP tools — what tools show up in your AI client and what they return
  • Hooks — how SessionStart hooks preload project context