Free shopping assistant
A fast and simple app for managing your shopping list together
Pronounced KOF-fan (rhymes with "coffin" but with an "a" at the end). The name comes from the Polish word "kochanie" (meaning "darling" or "sweetheart"), which evolved into a playful nickname. It's a long story, but let's just say the name stuck! :D
Koffan is a lightweight web application for managing shopping lists, designed for couples and families. It allows real-time synchronization between multiple devices, so everyone knows what to buy and what's already in the cart.
The app works in any browser on both mobile and desktop. Just one password to log in - no complicated registration required.
I needed an app that would let me and my wife create a shopping list together and do grocery shopping quickly and efficiently. I tested various solutions, but none of them were simple and fast enough.
I built the first version in Next.js, but it turned out to be very resource-heavy. I have a lot of other things running on my server, so I decided to optimize. I rewrote the app in Go and now it uses only ~2.5 MB RAM instead of hundreds of megabytes!
- Ultra-lightweight - ~16 MB on disk, ~2.5 MB RAM
- Multiple lists - Create separate lists for different stores or purposes, with custom icons
- PWA - Install on your phone like a native app
- Offline mode - Create, edit and delete lists, sections and products without internet, with automatic synchronization when the connection returns
- Auto-completion - Fuzzy search suggestions from your history, remembers sections
- Organize products into sections (e.g., Dairy, Vegetables, Cleaning)
- Mark products as purchased
- Mark products as "uncertain" (can't find it in the store)
- Real-time synchronization (WebSocket)
- Responsive interface (mobile-first)
- Dark mode - Automatic theme based on system preferences
- Support for 18 languages, including all offline and synchronization messages
- Simple login system
- Rate limiting protection against brute-force attacks
- REST API - Programmatic access for integrations and migrations (docs)
- Outbound webhooks - Signed item events for automation tools such as n8n, Node-RED, and Zapier (docs)
Open Koffan online and sign in once so the app and shopping data can be saved on your device. For offline page loads and the installed PWA, serve Koffan over HTTPS; localhost also works for development. A plain HTTP address on your home network does not provide the same offline support.
| What you can manage offline | Supported actions |
|---|---|
| Lists | Create, rename, change icons, reorder and delete |
| Sections | Create, rename, reorder, change sorting and delete |
| Products | Add, edit names and notes, change quantities, check/uncheck, mark as uncertain, move, reorder and delete |
| Bulk actions | Check/uncheck an entire section, delete purchased products and delete selected sections |
You can create a new list with new sections and products entirely offline. Changes are saved on the device before the view updates and remain available after a page reload or reopening the app. When the connection returns, Koffan automatically sends pending changes and refreshes the list. Retrying a request after a lost response does not duplicate the same operation.
Other shoppers see your offline changes after they reach the server. Changes to different products are combined. For overlapping edits, the last value accepted by the server for each updated field wins. Saving product details sends its name, note and quantity together.
If a change cannot be applied, for example because another shopper deleted the edited product, it stays pending and the app offers retry and discard controls. Discarding a failed change can also remove local changes that depend on it.
Initial setup and login, imports, and history management require a connection. Clearing site data removes unsynchronized changes, and browser or operating-system storage cleanup can also remove offline data.
- Backend: Go 1.25+ (Go 1.26.6 toolchain) + Fiber
- Frontend: HTMX + Alpine.js + Tailwind CSS
- Database: SQLite
You can run Koffan directly on your machine using Go. This works on any system (macOS, Linux, Windows).
macOS (Homebrew):
brew install goLinux (Debian/Ubuntu):
sudo apt install golang-goWindows: Download from go.dev/dl
git clone https://github.com/PanSalut/Koffan.git
cd Koffan
go run .App available at http://localhost:3000
Default password: shopping123
To set a custom password:
APP_PASSWORD=yourpassword go run .Arch Linux users can install Koffan from the AUR using an AUR helper:
yay -S koffanThe AUR package is community-maintained by @SergeantBiggs, not by the Koffan project.
Upgrading from 2.9.x or earlier? The default container port changed from
80to8080in 2.10.0 so the image can run as a non-root user. If you are upgrading, update your port mappings and any reverse proxy upstreams accordingly:
docker run -p 80:80→docker run -p 80:8080docker run -p 3000:80→docker run -p 3000:8080- Reverse proxies (nginx / Caddy / Traefik): point the upstream to the container's port
8080- If you previously overrode
PORTvia env to work around the privileged port, you can drop that overrideCoolify and other auto-discovery setups that read the image's
EXPOSEwill pick up the new port on redeploy without any manual change.
docker run -d -p 3000:8080 -e APP_PASSWORD=yourpassword -v koffan-data:/data ghcr.io/pansalut/koffan:latestApp available at http://localhost:3000
docker-compose up -d
# App available at http://localhost:8080| Variable | Default | Description |
|---|---|---|
APP_ENV |
development |
Set to production for secure cookies |
APP_PASSWORD |
shopping123 |
Login password |
DISABLE_AUTH |
false |
Set to true to disable authentication (for reverse proxy setups) |
PORT |
8080 (Docker) / 3000 (local) |
Server port |
HTTP_READ_BUFFER_SIZE |
16384 |
Max size in bytes for request headers (raise if you see HTTP 431 behind an SSO proxy) |
DB_PATH |
./shopping.db |
Database file path |
DEFAULT_LANG |
en |
Default UI language (supported codes) |
LOGIN_MAX_ATTEMPTS |
5 |
Max failed login attempts before lockout; set to 0 to disable login rate limiting |
LOGIN_WINDOW_MINUTES |
15 |
Time window for counting attempts |
LOGIN_LOCKOUT_MINUTES |
30 |
Lockout duration after exceeding limit |
API_TOKEN |
(disabled) | Enable REST API with this token (docs) |
WEBHOOK_URL |
(disabled) | HTTP or HTTPS endpoint for outbound item events |
WEBHOOK_SECRET |
(none) | Secret used to sign webhook payloads with HMAC-SHA256 |
WEBHOOK_EVENTS |
(all item events) | Comma-separated filter: item.created, item.updated, item.completed, item.deleted |
If your reverse proxy already handles rate limiting (for example, Traefik with CrowdSec), set LOGIN_MAX_ATTEMPTS=0 in the container environment and restart Koffan. This disables the built-in login limiter while keeping password authentication enabled. LOGIN_WINDOW_MINUTES and LOGIN_LOCKOUT_MINUTES have no effect when the limiter is disabled.
Set WEBHOOK_URL to receive signed, asynchronous item events. Koffan supports event filtering, HMAC-SHA256 signatures, and durable SQLite-backed retries that survive restarts.
WEBHOOK_URL=https://automation.example.com/webhook/koffan \
WEBHOOK_SECRET=replace-with-a-random-secret \
WEBHOOK_EVENTS=item.created,item.completed,item.deleted \
go run .See the Webhook documentation for events, payloads, signature verification, retry behavior, and integration guidance.
git clone https://github.com/PanSalut/Koffan.git
cd Koffan
docker build -t koffan .
docker run -d -p 80:8080 -e APP_PASSWORD=your-password -v koffan-data:/data koffan- Add new resource → Docker Compose → Select your Git repository or use
https://github.com/PanSalut/Koffan - Set domain in Domains section
- Enable Connect to Predefined Network in Advanced settings
- Add environment variable
APP_PASSWORDwith your password - Deploy
Data is stored in /data/shopping.db. The volume ensures your data persists across deployments.
- Offline behavior - Capabilities, synchronization and limitations
- Translation guide - Supported languages and updating translations
For more information, check the Wiki:
- REST API - Programmatic access, migrations, integrations
- Webhooks - Outbound item events for automation and notifications
- Multiple Instances - Running separate instances for different households
Have an idea? Check open feature requests and vote with 👍 on the ones you want most.
Want to suggest something new? Create an issue.
I love and admire the open source philosophy. That's why I created Koffan - to give back to the community that has given me so much over the years.
If you find this project useful and want to support my work (completely optional!), you can become a sponsor:
I'm incredibly grateful to these amazing people for supporting Koffan:
MIT License with Commons Clause.
You are free to use, modify, and share this software for any purpose, including commercial use within your organization. However, you may not sell the software or offer it as a paid service.