knotelResources
Browse resources

Start here

Getting started

Run knotel with Docker Compose, claim it, and send your first trace.

knotel is two containers on a machine you run: the app, which serves the UI, the ingest endpoints and the browser script, and ClickHouse, which stores every span, log and page view. Accounts, projects and keys live in a SQLite file next to the app. This guide takes you from nothing to your first trace in about ten minutes.

What you need

  • A machine with Docker and Docker Compose. A small VM (2-4 vCPU, 4-8 GB of RAM) handles millions of spans a day; see Usage and costs.
  • Nothing to clone or build: knotel runs from the public image ghcr.io/kien-ngo/knotel.

Deploy

Docker and Compose has the whole Compose file to copy, and the plain docker run alternative. In short: save that file as compose.yml, put the two required secrets in a .env next to it, and start the stack. Migrations for both stores run when the app starts, so there is no separate setup step.

mkdir knotel && cd knotel
# save compose.yml from the Docker page here, then:
printf 'BETTER_AUTH_SECRET=%s
CLICKHOUSE_PASSWORD=%s
'   "$(openssl rand -base64 32)" "$(openssl rand -hex 24)" > .env
docker compose up -d    # open http://localhost:3000/setup

BETTER_AUTH_SECRET signs sessions; CLICKHOUSE_PASSWORD is shared by the two containers. The app listens on port 3000. Put it behind your reverse proxy or tunnel to give it an address such as https://knotel.example.com, and set PUBLIC_URL to that address if the proxy doesn't send X-Forwarded-Proto and X-Forwarded-Host. See Configuration.

How long data is kept
Each project keeps spans for RETENTION_DAYS (30) unless it picks its own number in Settings, and logs for LOG_RETENTION_DAYS (7). ClickHouse deletes what is older. It is one store: a 30-day chart reads the same table as a 15-minute one.

Claim your instance

A new instance has no accounts. The first person to enter the setup code becomes its owner.

  1. Open /setup on your instance, such as https://knotel.example.com/setup.
  2. Enter the setup code. If you set SETUP_TOKEN in .env, that's the code. Otherwise a one-time code is printed in the server log on first start (docker compose logs knotel).
  3. Enter your name, email and a password of at least 8 characters.

To choose the code yourself, set it before the first start:

.env
SETUP_TOKEN=a-code-only-you-know
There is no public sign-up
After the claim, the sign-up endpoint refuses new accounts. Members add teammates from Settings.

Send your first trace

  1. Create a project. Home offers a form when there are none; later ones come from Settings.
  2. Open the project's Send data page and create an ingest key, listing the domains and IP addresses it should accept data from: your site's domain for the script tag, your server's public IP for a backend. It's shown once, so copy it.
  3. Point your senders at your instance's URL: add the script tag or an SDK from that page (the snippets fill in your key and address), or send a test span straight away:
Test span
START=$(($(date +%s) * 1000000000))
curl -X POST https://knotel.example.com/v1/traces \
  -H "content-type: application/json" \
  -H "x-knotel-key: kn_YOUR_KEY" \
  -d '{"resourceSpans":[{"resource":{"attributes":[{"key":"service.name","value":{"stringValue":"curl-test"}}]},
  "scopeSpans":[{"spans":[{"traceId":"5b8efff798038103d269b633813fc60c","spanId":"eee19b7ec3c1b174",
  "name":"GET /hello","kind":2,"startTimeUnixNano":"'$START'","endTimeUnixNano":"'$((START + 120000000))'"}]}]}]}'

A 200 with {} means the span was stored. Open the project's Traces page and it's there. A 403 means the key doesn't allow the machine you sent it from: the response names the IP it saw, so add it to the key.

Next steps