Getting started

Run the full Karet stack on your machine in under five minutes.

Prerequisites

• Finch or Docker, or anything else that speaks docker compose.
• About 1 GB of disk for the bundled S3 emulator and clean Parquet output.

1. Clone and configure

git clone https://github.com/joeyshi12/karet
cd karet

# Generate a secret used to sign session cookies.
echo "KARET_SESSION_SECRET=$(openssl rand -base64 48)" > .env

The compose file refuses to start without KARET_SESSION_SECRET. That's deliberate. Running with a default value would let anyone forge a session.

2. Start the stack

finch compose up -d
# or: docker compose up -d

Three services come up:

Service	Port	Purpose
web	:3000	Karet's Next.js UI
worker	:8080	The Rust/Axum pipeline worker
rustfs	:9000 (:9001 console)	S3-compatible object store

3. Set the admin password

Open http://localhost:3000. The first visit shows a "Set admin password" form. Pick a password (≥ 8 characters) and click Set password.

You're now signed in. Subsequent visits will show a normal sign-in form.

4. Create your first pipeline

From the home page, click + New pipeline and pick the Spending Tracker template. This provisions:

• A source container at pipelines/<slug>/raw/transactions/ that expects date, description, amount, account CSVs.
• A keyword-lookup mapping that tags each row with a category.
• An analytic table written to pipelines/<slug>/clean/transactions/ as partitioned Parquet.
• A dashboard with KPI tiles, a category doughnut, a monthly-trend line, a top-merchants bar, and a transactions table.

5. Drop in some data

Upload one or more CSVs to the source prefix:

aws --endpoint-url=http://localhost:9000 \
  s3 cp my-jan.csv s3://karet-data/pipelines/<slug>/raw/transactions/

If you've enabled the auto-run webhook, the upload triggers a pipeline run automatically (with a 5-second debounce so a batch upload becomes one job). Otherwise click Run Pipeline on the Jobs page.

6. View the dashboard

Navigate to Dashboards → Spending Overview. KPIs, charts, and the transactions table all populate from the Parquet output.

What's next?

• Architecture: the three services and how they connect.
• Pipeline config: the JSON shape that drives ingest.
• Dashboard config: panel kinds, layout, cross-filters.
• Auto-runs: wire RustFS uploads to pipeline runs.