# 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

```sh
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`:

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

Generate a JWT secret:

```sh
openssl rand -hex 32
```

## Development

Backend:

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

Frontend:

```sh
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:

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

Restore:

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

## Updates

```sh
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:

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

Container image scan:

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

Secret scan:

```sh
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.