cibrandocampo/nudge-frontend repository overview

⁠Nudge

A gentle reminder for recurring things.
Set the interval once. Get nudged at the right moment. Your server, your rules.

See the project site →⁠
_{Product tour, screenshots and FAQ. This README is the technical side.}

⁠What it is

A self-hosted tracker for the things that come round again: medication, filters, fertiliser, descaling the coffee machine. You set the interval once, Nudge tells you when it is due, and it keeps the history.

What makes it more than a checklist:

• Stock that decrements itself. Attach a consumable to a routine and every completion draws it down, lot by lot, First Expired First Out — with expiry warnings before anything goes off.
• Findable at twenty items. The inventory is one compact row per product — what is left, how fast it goes, when it runs out — with a search that matches names, categories and batch numbers, filters per category, and up to four products pinned to the top. What needs attention is one summary line, not a wall of alerts.
• Scan the box. Point the camera at the DataMatrix on the packaging and the batch, its expiry and the product code fill themselves in — or type them, for the boxes where the print is scratched or there is no camera to hand. A pack carrying a serial stays one physical box, never merged with another, so "which box did I open?" has an answer.
• Offline-first, honestly. Mutations queue in IndexedDB, sync when the network returns, and a conflict opens a per-field diff instead of guessing. Reads come from the service-worker cache.
• Shared with the household. Share a routine or a stock item with a contact; either of you can complete it and both see the same history.
• Push that respects the night. A daily heads-up, an alert when something falls due, follow-up reminders — with quiet hours per user.
• Yours. No SaaS, no public registration, no telemetry. Backend and database never leave the Docker network.

⁠Up and running in 5 minutes

Two files, a few secrets, docker compose up:

curl -O https://raw.githubusercontent.com/cibrandocampo/nudge/main/docker-compose.yml
curl -O https://raw.githubusercontent.com/cibrandocampo/nudge/main/.env.example
cp .env.example .env

Fill in .env — at minimum DJANGO_SECRET_KEY, the database and Redis passwords, ADMIN_PASSWORD, your domain in DJANGO_ALLOWED_HOSTS / CORS_ALLOWED_ORIGINS / VITE_API_BASE_URL, and the VAPID key pair if you want push notifications. Then:

mkdir -p data
docker compose up -d

Log in at /login with ADMIN_EMAIL and ADMIN_PASSWORD. Only the frontend container publishes a port; put a reverse proxy in front of it for TLS.

→ Full installation guide⁠ — secrets, domain, reverse proxy, image tags, installing it on a phone.

⁠Documentation

⁠License

MIT⁠ © 2026 Cibrán Docampo Piñeiro. Use it, change it, distribute it, self-host it — personally or commercially — as long as the copyright notice survives. No warranty.