Installation¶

Kiwi runs as a Docker Compose stack: a FastAPI backend and a Vue 3 frontend served by nginx. No external services are required for the core feature set.

Prerequisites¶

Docker and Docker Compose
500 MB disk for images + space for your pantry database

Quick setup¶

git clone https://git.opensourcesolarpunk.com/Circuit-Forge/kiwi
cd kiwi
cp .env.example .env
./manage.sh build
./manage.sh start

The web UI opens at http://localhost:8511. The FastAPI backend is at http://localhost:8512.

manage.sh commands¶

Command	Description
`./manage.sh start`	Start all services
`./manage.sh stop`	Stop all services
`./manage.sh restart`	Restart all services
`./manage.sh status`	Show running containers
`./manage.sh logs`	Tail logs (all services)
`./manage.sh build`	Rebuild images
`./manage.sh open`	Open browser to the web UI

Environment variables¶

Copy .env.example to .env and configure:

# Required — generate a random secret
SECRET_KEY=your-random-secret-here

# Optional — LLM backend for AI features (receipt OCR, recipe suggestions)
# See LLM Setup guide for details
LLM_BACKEND=ollama          # ollama | openai-compatible | vllm
LLM_BASE_URL=http://localhost:11434
LLM_MODEL=llama3.1

Data location¶

By default, Kiwi stores its SQLite database in ./data/kiwi.db inside the repo directory. The data/ folder is bind-mounted into the container so your pantry survives image rebuilds.

Updating¶

git pull
./manage.sh build
./manage.sh restart

Database migrations run automatically on startup.

Uninstalling¶

./manage.sh stop
docker compose down -v    # removes containers and volumes
rm -rf data/              # removes local database