NexaPantry

NexaPantry is an AGPL-3.0 self-hosted Docker/PWA web app for managing food inventory in families, shared flats and households. It supports multi-user homes, barcode scanning, expiry warnings, shopping lists, recipe suggestions, admin operations and secure instance setup.

Features

• Initial setup wizard for the first Instance Admin
• Secure HttpOnly cookie auth, Argon2id password hashes, CSRF protection and rate limiting
• Multi-home model with owner/member/read-only roles and expiring join codes
• Inventory with barcode lookup via an abstract OpenFoodFacts provider
• Category and location views with expiry status colors
• Shopping list with stock refill flow
• In-app and e-mail notification pipeline with a background worker
• Rule-based recipe suggestions that prefer available and expiring products
• Full admin panel for users, homes, mail settings, security settings, logs and backup guidance
• German and English UI texts through i18n dictionaries
• Light, dark and system theme
• Installable PWA with app shell caching and offline-friendly runtime caching
• Docker Compose with PostgreSQL, Redis, FastAPI backend, worker, frontend and Caddy reverse proxy

Screenshots

Screenshots are intentionally not committed yet. Suggested files:

• docs/screenshots/setup.png
• docs/screenshots/inventory.png
• docs/screenshots/admin.png

Quick Start

cp .env.example .env
# edit passwords and keys in .env
docker compose up -d

Open http://localhost. On first launch NexaPantry shows the initial setup wizard because no Instance Admin exists.

Generate a Fernet key for SETTINGS_SECRET_KEY:

python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

Generate a JWT secret:

openssl rand -hex 32

Development

Backend:

cd backend
python -m venv .venv
. .venv/bin/activate
pip install -e ".[dev]"
uvicorn app.main:app --reload

Frontend:

cd frontend
npm install
npm run dev

Mail Settings

Configure SMTP in Admin -> Mail:

• SMTP host and port
• SMTP user
• encrypted SMTP password
• TLS or STARTTLS
• sender address and sender name

Mail is used for invitations, password reset, password setup and expiry summaries.

Backup and Restore

Backup:

docker compose exec postgres pg_dump -U "$POSTGRES_USER" "$POSTGRES_DB" > backup.sql

Restore:

docker compose exec -T postgres psql -U "$POSTGRES_USER" "$POSTGRES_DB" < backup.sql

Updates

git pull
docker compose build
docker compose up -d

Read release notes before updating and keep database backups.

Security

• Change every value in .env before exposing the service.
• Put NexaPantry behind HTTPS. Caddy can terminate TLS when configured with your public domain.
• Keep COOKIE_SECURE=true in production HTTPS deployments.
• Restrict CORS_ORIGINS to your real instance origin.
• Invitation and reset tokens are stored hashed only.
• SMTP passwords are encrypted at rest with SETTINGS_SECRET_KEY.
• Product, shopping and recipe APIs verify home membership to reduce IDOR risk.
• Admin actions are written to an audit log without secret values.

Run checks:

chmod +x scripts/security-checks.sh
./scripts/security-checks.sh

Container image scan:

docker compose build
trivy image nexapantry-backend
trivy image nexapantry-frontend

Secret scan:

gitleaks detect --source .

Contribution

1. Open an issue for larger changes.
2. Keep PRs focused.
3. Add or update tests for behavior changes.
4. Run lint, tests, typecheck and audits before submitting.

License

NexaPantry is licensed under AGPL-3.0-or-later.