GroceryWise

GroceryWise is a self-hosted app that helps a single household find the best grocery prices across the retailers they actually shop at — Walmart, Costco, and BJ's Warehouse at launch. It works by letting each user log into their own retailer accounts so the app can drive a browser to pull their real purchase history and reflect accurate, location-specific pricing. The core value is correct per-unit price comparison: it normalizes for unit differences, filters out third-party marketplace listings, and surfaces delivery costs so apparent savings aren't quietly negated. It serves a household (an admin, a co-owner such as a spouse, and regular users such as children) that wants to plan shopping intelligently, build offline-capable shopping lists, and get a data-driven suggested weekly list from their order history.

It runs as a single container behind your own reverse proxy. New here? Start with the Quick start below to evaluate it locally, then follow the deployment runbook for a production install.

Install

The recommended way to run GroceryWise is to pull the prebuilt, multi-arch (linux/amd64 + linux/arm64) image published to GitHub Container Registry — no Node/SvelteKit build environment required:

docker pull ghcr.io/benw5483/grocery-wise:latest

Each release is also published under its exact version (e.g. ghcr.io/benw5483/grocery-wise:1.0.0) and a <major>.<minor> short tag (e.g. ghcr.io/benw5483/grocery-wise:1.0). For the full operator setup — reverse-proxy configuration, environment variables, volumes, and first-run admin setup — follow the deployment runbook:

➡️ docs/DEPLOY.md

Prefer to build from source instead? The Quick start below uses Docker Compose to build the image locally, which remains a supported development fallback.

Tech stack

GroceryWise is built on a modern, self-host-friendly stack:

• Runtime: Node.js 22+ (ESM only)
• Language: TypeScript 5.x (strict mode)
• Frontend: SvelteKit — an installable Progressive Web App (PWA) shell with offline support and light/dark mode
• Database: SQLite, stored as a file under the mounted data directory — no separate database service to run
• Container runtime: Docker (with first-class Unraid + SWAG support)
• Package manager / tests: pnpm and Vitest

Quick start

The fastest way to evaluate GroceryWise on your workstation is with Docker Compose. This is for evaluation; for a production-style install behind a reverse proxy, see docs/DEPLOY.md.

# 1. Copy the environment template and review it.
#    Leave SESSION_SECRET and ENCRYPTION_KEY blank to have strong values
#    auto-generated and persisted under DATA_DIR on first run.
cp .env.example .env

# 2. Launch the stack (SQLite + app live in mounted volumes).
docker compose up -d

# 3. Open the app and complete the first-run admin setup.
#    By default the app listens on http://localhost:8080

On first run, GroceryWise presents a one-time setup flow that creates your admin account; until that account exists, every other route is locked. From there you can invite the rest of your household and assign roles. See auth-and-onboarding for the full first-run and invite flow.

Configuration is entirely environment-driven. The supported variables are:

Variable	Required	Purpose
PORT	optional (default 8080)	App listen port inside the container.
DATA_DIR	optional (default /data)	Root of persistent data (db, sessions, assets).
SESSION_SECRET	optional*	Signs/encrypts session material.
ENCRYPTION_KEY	optional*	Encrypts stored retailer credentials.
TRUST_PROXY	optional (default false)	Set true behind a reverse proxy (e.g. SWAG).

* Auto-generated and persisted under DATA_DIR on first run if not supplied. The authoritative reference is .env.example.

Features

Each highlight links to the feature's specification, where the deeper detail lives.

• Self-hosted deployment — Containerized deploy with Docker Compose and an Unraid user-template, designed to run behind SWAG with Authelia bypassed.
• PWA shell — Installable Progressive Web App with light/dark mode and an in-app changelog.
• Auth & onboarding — First-run admin setup, secure sessions, and passwordless household invites.
• User management — Invite, assign three-tier roles (admin, co-owner, regular), and revoke household members.
• Retailer management — Choose comparison retailers and manage per-retailer store/login config.
• Purchase-history import — Browser-driven import of each user's real purchase history, with marketplace listings filtered out.
• Price comparison — Correct per-unit price comparison with clear delivery-cost visibility.
• Shopping list — Offline-first shopping lists with categories and aisle fields that sync when back online.
• Suggested list — A history-based suggested weekly list you can review and turn into a real list.
• Favorites — Tag and filter frequently bought items.
• Push notifications — Push and in-app notifications when household members add to the shared list.

Tracked but deferred to a later phase:

• Comparables review — Manual review when per-unit deviations are too dissimilar to compare safely.
• Barcode scanning — Scan item barcodes to add and compare prices.

Production install

For a production-style deployment on Unraid behind SWAG — prerequisites, the Unraid template, the full environment-variable reference, volume layout, the reverse-proxy configuration with the Authelia bypass, first-run admin setup, and a common-boot-time-problems guide — follow the deployment runbook:

➡️ docs/DEPLOY.md

Operations

For keeping a running instance healthy — backups and cadence, the upgrade procedure, power-loss recovery, where to find logs, push-notification reset, and a common-runtime-issues matrix — see the operations note:

➡️ docs/OPERATIONS.md

Project status

• Phase: MVP. The launch retailers are Walmart, Costco, and BJ's Warehouse.
• Version: 1.0.0.
• Scope: Single household per instance (one admin, co-owners, and regular users). Multi-tenancy, additional retailers, and in-app checkout are out of scope for this phase. Comparables review and barcode scanning are tracked but deferred.
• Release notes: Tracked in the in-app changelog (see the PWA shell feature); there is no separate CHANGELOG file for MVP.

Architecture, decisions, and per-feature detail live under .nexus/specs/. The project blueprint is .nexus/blueprint.md.

License

ISC. See package.json for the declared license.