Sustenance

A small shared grocery list built with Rust, Axum, Maud, htmx, WebSockets, and SQLite.

Run locally

cargo run

Open http://127.0.0.1:3000. The application creates sustenance.db in the working directory on first start.

Configuration

Variable	Default	Purpose
DATABASE_PATH	sustenance.db	SQLite database path
BIND_ADDRESS	127.0.0.1:3000	Listen address
PUBLIC_BASE_URL	derived from BIND_ADDRESS	Base URL used in invitation links
COOKIE_SECURE	false	Add the Secure attribute to session cookies
REGISTRATION_MODE	invite_only	Use open for local development; otherwise registration requires a valid list invitation after the first account
SEED_CONFIG	seed.json	Optional JSON file with a default user to create when the database is first initialized
RUST_LOG	sustenance=debug,tower_http=info	Log filter

Seeding a default user

If a JSON config file exists at the path given by SEED_CONFIG (default seed.json), Sustenance creates the configured user on startup when the database has no users yet. The file is optional — if it is missing or invalid, seeding is silently skipped.

{
  "user": {
    "email": "you@example.com",
    "display_name": "You",
    "password": "a-strong-password"
  }
}

Current features

• Email/password accounts with Argon2 password hashes
• Cookie-backed sessions and CSRF tokens for list mutations
• Shared lists with one-time, seven-day invitation links
• Invite-only registration by default after the first account
• Add, edit, check, and delete grocery items
• List-scoped categories with common defaults and custom category creation
• Items grouped by category and assigned from the add/edit forms
• Server-authoritative last-write-wins updates
• Per-list WebSocket updates with server-rendered htmx fragments
• In-memory presence for members currently viewing a list
• Responsive layout for phone, tablet, and desktop

The htmx scripts are currently loaded from unpkg. They can be vendored into static/ before production deployment.

Verification

cargo fmt --all -- --check
cargo check
cargo test