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.

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.

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: ...   # once auth (#5) lands
    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.