Logchef Dev

LogChef Dev Environment

Set up and run the LogChef development environment. LogChef is a Go (Fiber) backend + Vue 3 (TypeScript/Pinia) frontend for log analytics backed by ClickHouse.

Prerequisites

• Docker (for ClickHouse, Dex OIDC, Mailpit, webhook receiver)
• just task runner
• Go 1.24+, bun, sqlite3, and build tools on PATH
• vector on PATH for log ingestion

Quick Start (Full Setup)

Run these in order. Use tmux to keep services running.

1. Start infrastructure

cd /home/karan/Code/Personal/logchef
just dev-docker-detach

This starts: ClickHouse (:8123/:9000), Dex OIDC (:5556), Mailpit (:8025/:1025), webhook receiver (:8888).

Wait for ClickHouse to be healthy:

docker exec dev-clickhouse-local-1 clickhouse-client --query "SELECT 1"

2. Create ClickHouse tables

just dev-init-tables

3. Build the app

just build

4. Start backend (creates SQLite DB on first run)

Use tmux for persistent sessions:

tmux new-session -d -s logchef-dev -n backend
tmux send-keys -t logchef-dev:backend "cd /home/karan/Code/Personal/logchef && just run-backend" Enter

Wait for the backend to be ready:

curl -s http://localhost:8125/api/v1/health

5. Start frontend

tmux new-window -t logchef-dev -n frontend
tmux send-keys -t logchef-dev:frontend "cd /home/karan/Code/Personal/logchef/frontend && bun run dev" Enter

Frontend available at http://localhost:5173

6. Seed data (if needed)

The dev config uses provisioning (dev/provisioning.toml) to automatically create teams, sources, and link OIDC users on backend startup. If you need to seed the SQLite database with the dev@localhost API user:

cd /home/karan/Code/Personal/logchef
LOGCHEF_DB_PATH=./local.db ./dev/seed.sh

7. Ingest sample logs

cd /home/karan/Code/Personal/logchef/dev
vector -c http.toml & vector -c syslog.toml & sleep 60; kill %1 %2 2>/dev/null; wait

Or for continuous ingestion in background:

cd /home/karan/Code/Personal/logchef/dev
vector -c victorialogs.toml &
vector -c http.toml &
vector -c syslog.toml &

Alternatively, insert sample data directly:

docker exec dev-clickhouse-local-1 clickhouse-client --query "
INSERT INTO default.http SELECT
  now() - toIntervalSecond(number * 2 + rand() % 3),
  arrayElement(['api.logchef.dev','web.logchef.dev','cdn.logchef.dev'], (rand()%3)+1),
  arrayElement(['GET','POST','PUT','DELETE','GET','GET'], (rand()%6)+1),
  'HTTP/1.1', '-',
  arrayElement(['/api/v1/health','/api/v1/logs/query','/api/v1/teams','/api/v1/sources'], (rand()%4)+1),
  arrayElement([200,200,201,400,404,500], (rand()%6)+1),
  arrayElement(['admin','demo','-'], (rand()%3)+1),
  toUInt32(rand()%50000)
FROM numbers(5000)"

Login Credentials

Authentication uses Dex OIDC. Static passwords configured in dev/dex/config.yaml:

Key Config Files

Dev Config Notes

• config.toml has secure_cookie = false under [server] for HTTP dev
• Provisioning auto-links admin@logchef.internal and demo@logchef.internal to "Dev Team"
• ClickHouse tables: default.http (HTTP access logs) and default.syslogs (syslog format)
• SQLite database: local.db in project root

Services & Ports

Common Operations

Reset everything

just dev-reset    # Truncates ClickHouse, wipes VictoriaLogs data, deletes local.db
just dev-clean    # Stops docker, removes volumes, deletes local.db
just dev-setup    # Fresh start (docker + tables + seed)

Rebuild after code changes

# Backend only
just run-backend

# Frontend only (hot-reload, usually automatic)
cd frontend && bun run dev

# Full rebuild
just build

Check ClickHouse data

docker exec dev-clickhouse-local-1 clickhouse-client --query "SELECT count() FROM default.http"
docker exec dev-clickhouse-local-1 clickhouse-client --query "SELECT count() FROM default.syslogs"

Run checks before committing

just check

Frontend type check / build

cd frontend && bun run typecheck
cd frontend && bun run build

Troubleshooting

"address already in use" on port 8125

ss -tlnp | grep 8125 | grep -oP 'pid=\K[0-9]+' | xargs -r kill -9

Can't login / auth_error redirect

• Check Dex is running: curl http://localhost:5556/dex/.well-known/openid-configuration
• Verify config.toml has secure_cookie = false under [server]
• Verify OIDC URLs in config.toml match Dex config

"You don't have access to any teams"

• Check dev/provisioning.toml has the user's email in a team's members list
• Restart backend to trigger provisioning reconciliation

sqlite3 not found (during seed.sh)

• Install sqlite via your package manager (e.g. yay -S sqlite)
• Or set DB path: LOGCHEF_DB_PATH=./local.db ./dev/seed.sh

No logs in explorer

• Check ClickHouse has data: docker exec dev-clickhouse-local-1 clickhouse-client --query "SELECT count() FROM default.http"
• Ingest logs with vector or direct INSERT (see step 7 above)
• For VictoriaLogs specifically, run nix-shell -p vector --run "vector -c victorialogs.toml" from dev/
• Check the time range in the UI covers when data was inserted