nessi
3792ca55e7
Add complete NexaPantry application structure including: - Docker Compose configuration with PostgreSQL, Redis, FastAPI backend, worker, frontend and Caddy - Environment configuration template with database, auth, and service settings - GitHub Actions CI workflow for backend/frontend linting, testing, auditing and Docker builds - AGPL-3.0 license and comprehensive README with setup, development, and security documentation - Backend
150 lines
3.6 KiB
Markdown
150 lines
3.6 KiB
Markdown
# 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.
|
|
|