pansy/README.md

pansy

Self-hostable garden planner: drag beds, bags, and containers onto a real-scale field, click into them to place freeform plops of plants, and zoom out to see what's planted where. Go backend + React frontend, one static binary.

🤖 This is a vibe-coded project

Essentially all of the code in pansy was written by an LLM (Claude), with a human directing the work, reviewing it, and deciding what ships. Every pull request also gets an automated adversarial review before it lands.

That's said up front because you deserve to know it before you trust pansy with anything: it hasn't been through the kind of scrutiny a hand-written, widely-used project has. Read the code before you self-host it. Back up your database. Bugs here are the ordinary kind of bugs, not a scandal — but so is the fact that nobody hand-wrote the thing.

See DESIGN.md for the architecture. Work is tracked in this repo's issues — start from the tracking epic.

Quickstart

Prerequisites: Go 1.26+, Node 20+.

Develop

Run the Go API and the Vite dev server together (Vite proxies /api → the API):

make dev

Then open http://localhost:5173. Or run the two halves in separate terminals for independent restarts:

make dev-api   # Go API on :8080
make dev-web   # Vite dev server on :5173

Build & run

Produce the single static binary with the web build embedded, then run it:

make build
./pansy

Open http://localhost:8080 — one process serves both the JSON API and the app.

Test

make test

Configuration

All configuration is via environment variables; every value has a default, so ./pansy runs with none set.

Variable	Default	Description
PANSY_PORT	8080	TCP port the HTTP server listens on.
PANSY_DB	./pansy.db	SQLite database file path (created if absent).
PANSY_BASE_URL	(empty)	Externally-visible base URL; used to derive the OIDC redirect URI.
PANSY_REGISTRATION	open	open or closed — gates local self-service signup.
PANSY_LOCAL_AUTH	true	Enable local password auth. Set false for pure-OIDC.
PANSY_OIDC_ISSUER	(empty)	OIDC issuer/discovery URL (Authentik). Enables SSO when set.
PANSY_OIDC_CLIENT_ID	(empty)	OIDC client ID.
PANSY_OIDC_CLIENT_SECRET	(empty)	OIDC client secret.
PANSY_OIDC_BUTTON_LABEL	Sign in with Authentik	Label for the OIDC button on the login page.
PANSY_TRUSTED_PROXIES	(none)	Comma-separated proxy CIDRs/IPs to trust for client-IP resolution.

The garden assistant reads three more. Setting none of them leaves the assistant off; the app runs exactly as it does without it.

Variable	Default	Description
OLLAMA_CLOUD_API_KEY	(empty)	Ollama Cloud API key. Without it the assistant is off, not broken. This is the one agent value that stays in the environment — it is never stored in the database or editable in Settings.
PANSY_AGENT_MODEL	ollama-cloud/glm-5.2:cloud	Default model spec, passed verbatim to majordomo.Parse — a comma-separated list is a failover chain, e.g. ollama-cloud/glm-5.2:cloud,ollama-cloud/kimi-k2.6:cloud. An admin can override this per-instance in Settings without a redeploy; a blank Settings value inherits this.
PANSY_AGENT_ENABLED	on when a key is present	Default on/off for the assistant. Also overridable in Settings (which can inherit this default).
PANSY_VISION_MODEL	(empty)	Default model for seed-packet capture (photograph a packet → it fills in the plant + purchase). A vision-capable model (the chat model may not be). Empty = the feature isn't offered. Runs against the same OLLAMA_CLOUD_API_KEY, and is overridable in Settings.

The agent model + enabled flag, and the vision model, can be changed at runtime by an admin under Settings (the gear appears in the nav for admins) — an agent change swaps the live assistant with no restart. The env vars above are the defaults an untouched instance uses, and the API key is intentionally not among the runtime-editable settings: a secret in the database would land in every backup. Precedence is Settings value, if set → env var → built-in default.

The assistant acts without asking first, which is only reasonable because every turn is one undoable change set — see the History panel in the editor.

If you set the key and the assistant still doesn't appear, check that the variable reaches the container, not just your orchestrator's stack config — Compose needs it listed under the service's environment:. pansy logs why the assistant is off at startup, and Settings shows the same status (a key present, the resolved model, and whether it's actually running).

Local email/password auth is live (POST /api/v1/auth/register, /auth/login, /auth/logout, GET /auth/me, GET /auth/providers); the session is an HttpOnly cookie (Secure when PANSY_BASE_URL is https). The first account registered becomes admin, and it may register even when PANSY_REGISTRATION=closed to bootstrap the instance.

OIDC (Authentik-first) is live too: set PANSY_OIDC_ISSUER, PANSY_OIDC_CLIENT_ID, PANSY_OIDC_CLIENT_SECRET, and PANSY_BASE_URL (needed for the redirect URI). Register PANSY_BASE_URL + /api/v1/auth/oidc/callback as the redirect URI in your IdP. GET /auth/oidc/login starts an authorization-code + PKCE flow; first login provisions a user just-in-time (a matching verified email links to an existing local account instead of duplicating it). Provider discovery is lazy, so a briefly-unreachable IdP never blocks startup or local auth. Set PANSY_LOCAL_AUTH=false for pure-Authentik deployments (local register/login are then rejected and hidden from /auth/providers).

Docker & deployment

CI (.gitea/workflows/build-image.yml) builds the single-binary image and pushes it to the Gitea registry on every branch push:

Ref	Tag
main	gitea.stevedudenhoeffer.com/steve/pansy:latest
any other branch	gitea.stevedudenhoeffer.com/steve/pansy:<branch-name>
every build	gitea.stevedudenhoeffer.com/steve/pansy:sha-<short> (immutable; use to pin)

The image runs as a non-root user, serves on :8080, and stores the SQLite database on the /data volume. Run it directly:

docker run -d --name pansy \
  -p 8080:8080 \
  -v pansy-data:/data \
  gitea.stevedudenhoeffer.com/steve/pansy:latest

Or as a Komodo/Compose stack:

services:
  pansy:
    image: gitea.stevedudenhoeffer.com/steve/pansy:${PANSY_TAG:-latest}
    ports:
      - "8080:8080"
    volumes:
      - pansy-data:/data
    environment:
      PANSY_BASE_URL: https://pansy.example.com
      # PANSY_OIDC_ISSUER: https://auth.example.com/application/o/pansy/
      # PANSY_OIDC_CLIENT_ID: ...
      # PANSY_OIDC_CLIENT_SECRET: ...
      # OLLAMA_CLOUD_API_KEY: ${OLLAMA_CLOUD_API_KEY}   # enables the garden assistant
      # PANSY_AGENT_MODEL: ollama-cloud/glm-5.2:cloud
    restart: unless-stopped
volumes:
  pansy-data:

Pin PANSY_TAG to a sha-<short> tag for reproducible deploys, or leave it at latest to track main.