This README is the one indexed from the repository at its latest ref, not from the tag for this version.

Quest

A small, private, gamified home app for one family — built with Crystal, Lucky and PostgreSQL. It ships as a ~21 MB container built FROM scratch and running as an unprivileged user.

There is no public sign-up: accounts are created from the command line.

Run it

cat > .env <<ENV
SECRET_KEY_BASE=$(openssl rand -base64 32)
POSTGRES_PASSWORD=$(openssl rand -hex 24)
APP_DOMAIN=http://localhost:3000
ENV

docker compose up -d
docker compose run --rm -it --entrypoint /app/quest-tasks migrate users.create you@example.com

Then open http://localhost:3000 and sign in.

Develop

Requirements: Crystal 1.21 and Bun (see .tool-versions), PostgreSQL, and a Chromium-based browser for the LuckyFlow specs.

shards install
bun install && bun run build   # the asset manifest is read at compile time
lucky db.setup
crystal spec
lucky dev                      # http://127.0.0.1:3000

Database settings come from DB_HOST, DB_PORT, DB_USERNAME and DB_PASSWORD (or DATABASE_URL), read from the environment or a .env file.

LuckyFlow downloads a chromedriver by default. To use your own (for instance behind a proxy, or with Brave instead of Chrome), set CHROMEDRIVER_PATH to a driver matching your browser's major version and CHROME_BIN to the browser executable.

Architecture

The domain lives in src/domain/ as plain Crystal with no Lucky or Avram dependency, and is mutation-tested with crytic. Lucky actions and pages, and Avram models and operations, are adapters around it.

License

MIT