Quick Start

Chukfi CMS — Quickstart (v0.3.0)

Get a headless CMS running in 5 minutes.

Prerequisites

Rust 1.91+ (rustup)
AWS account with CLI configured — see AWS Setup for step-by-step instructions
Your developer IAM user needs rds:CreateDBInstance, rds:DeleteDBInstance, and rds:DescribeDBInstances permissions

Option A: Run from source (recommended)

git clone https://github.com/smattera/chukfi-core
cd chukfi-core

1. Create your database

Each developer gets their own RDS PostgreSQL instance. Run this once — it takes ~10 minutes the first time.

chukfi db create --name my-chukfi-dev --region us-east-1

When it finishes, you’ll see a DATABASE_URL like:

postgres://chukfi:<password>@my-chukfi-dev.abcdef.us-east-1.rds.amazonaws.com:5432/chukfi

2. Set up config and secrets

# Copy the standard config template
cp chukfi-bin/templates/standard.config.json chukfi.config.json

# Create .env with the DATABASE_URL from step 1 + a random JWT secret
cat > .env << EOF
DATABASE_URL=postgres://chukfi:<password>@your-instance.region.rds.amazonaws.com:5432/chukfi
CHUKFI_JWT_SECRET=$(openssl rand -hex 32)
CHUKFI_DEV_MODE=true
EOF

3. Build and start

cargo build --release -p chukfi-bin
./target/release/chukfi serve

Server is live at http://localhost:8080.

4. Seed demo data (optional)

./target/release/chukfi seed

Seeds demo pages and media assets for every content type defined in your config. Navigation groups ship with the schema migrations and are created automatically on first run. Admin users are created lazily by chukfi token <email>.

5. Get an auth token

Dev mode auto-creates users on first login. To get a JWT without the browser:

./target/release/chukfi token you@example.com

Use it in headers: Authorization: Bearer <token>

6. Hit the API

TOKEN=$(./target/release/chukfi token you@example.com)
curl -H "Authorization: Bearer $TOKEN" http://localhost:8080/api/admin/config

7. Admin UI

The embedded admin dashboard is bundled in the binary — just open http://localhost:8080 in your browser and sign in. No separate build step.

For the optional Dioxus admin UI:

cd chukfi-admin-ui
trunk serve --open    # Opens admin UI at http://localhost:8081 (API runs at http://localhost:8080)

Option B: cargo install (binary only)

cargo install chukfi-bin
chukfi serve

The binary auto-runs migrations on startup (no sqlx migrate run needed) and serves the embedded admin dashboard at http://localhost:8080. To scaffold a config, run chukfi init (writes chukfi.config.json + .env.example).

Customize

Edit chukfi.config.json to:

Add content types — blog posts, products, events
Change auth — wire up Entra ID, Cognito, or SES magic links
Configure the admin — name, color, custom components
Set S3 media storage — switch from local filesystem to AWS

Restart the server after changing config.

Commands reference

Command	What it does
`chukfi db create --name <id>`	Create a per-dev AWS RDS instance
`chukfi db list`	List your RDS instances
`chukfi db destroy --id <id> --yes`	Destroy an RDS instance
`chukfi serve`	Start the API server (default command)
`chukfi seed`	Seed demo data (pages, media, users)
`chukfi token <email>`	Generate a JWT for local dev
`chukfi content create --type pages --title "Hello"`	Create content via CLI
`chukfi content list --type pages`	List content entries
`chukfi media upload --path ./photo.jpg`	Upload a file
`chukfi media list`	List media assets
`chukfi codegen`	Generate TypeScript types from schema

Tear down your database

When you’re done working on a project:

chukfi db destroy --id my-chukfi-dev --yes

This deletes the RDS instance so you’re not paying for idle compute.

Where to go from here

Source: github.com/smattera/chukfi-core
Crate docs: https://crates.io/crates/chukfi-bin
CLI Reference: /guides/cli/
AWS Setup: /guides/aws-setup/
Issues / questions: Open a GitHub issue

Known gaps (v0.3.0)

Optional Dioxus admin UI — the embedded vanilla-JS dashboard is the default; the Dioxus UI in chukfi-admin-ui/ is an optional richer interface built separately with trunk build.