What is groceries?

Specifically Clementines (formerly Groceries) is a self-hosted grocery list application built for families who need reliable synchronization across multiple devices and users. It supports multiple shopping lists that can be grouped into list groups, real-time sync with visible status and automatic conflict resolution, offline functionality with sync-on-reconnect, store-specific aisle/category sorting to avoid backtracking, and recipe support including import from Tandoor. The backend runs on Node.js with CouchDB for data storage and replication, while the frontend is an Ionic/Capacitor app deployable as a web app, Android APK, or iOS app. Installation is documented via Docker Compose with pre-built images on ghcr.io, and a demo instance is available at specificallyclementines.com.

Should you self-host groceries?

groceries scores 47/100 on selfhost.directory (how scoring works) and ranks #10 of 18 in Recipe Management. It has 293 GitHub stars.

There was no stable release in the past 12 months, so check the repository's recent activity before you rely on it.

Setup is advanced: plan for several services and some ongoing maintenance. An official Docker image is available. It is MIT-licensed and written mostly in Typescript.

Its closest alternative on selfhost.directory is Mealie (75/100, 13 709 stars). It scores higher overall, so compare the two before you pick. See groceries vs Mealie side by side.

Features

Conflict resolution
Friend system
List groups with store fallback
List sharing
Multiple shopping lists
Offline Support
Password reset via email
Real-time sync
Recipe support
Store aisle sorting
Tandoor recipe import
Work offline mode

How to configure groceries

ACCESS_TOKEN_EXPIRES12hAccess token expiration (e.g. 12h, 1d)
Access token expiration (e.g. 12h, 1d)
COUCHDB_ADMIN_PASSWORDAdmin password for CouchDB instance
Admin password for CouchDB instance
COUCHDB_ADMIN_USERadminAdmin user for CouchDB instance
Admin user for CouchDB instance
COUCHDB_DATABASECouchDB database name (e.g. groceries)
CouchDB database name (e.g. groceries)
COUCHDB_HMAC_KEYPlaintext HMAC key for JWT authentication; base64 encoded version goes in CouchDB jwt.ini
Plaintext HMAC key for JWT authentication; base64 encoded version goes in CouchDB jwt.ini
COUCHDB_INTERNAL_URLInternal URL for accessing CouchDB without going through ingress layer
Internal URL for accessing CouchDB without going through ingress layer
COUCHDB_URLFull CouchDB URL + port (no database reference), externally resolvable by clients
Full CouchDB URL + port (no database reference), externally resolvable by clients
DEFAULT_API_URLFrontend environment variable pointing to backend API URL
Frontend environment variable pointing to backend API URL
DISABLE_ACCOUNT_CREATION0Set to true to disable new user account creation
Set to true to disable new user account creation
values: 0, 1
ENABLE_SCHEDULING1Enable automated conflict resolution and token expiration
Enable automated conflict resolution and token expiration
values: 0, 1
EXPIRE_JWT_FREQUENCY_MINUTES60How often to expire old JWT tokens
How often to expire old JWT tokens
GROCERY_API_PORT3333Port for the server to listen on (e.g. 3333 for dev, 80 or 8000 for production)
Port for the server to listen on (e.g. 3333 for dev, 80 or 8000 for production)
GROCERY_API_URLBackend API URL for emails (e.g. https://groceries.mydomain.com/api)
Backend API URL for emails (e.g. https://groceries.mydomain.com/api)
GROCERY_URLFrontend URL for emails (e.g. https://groceries.mydomain.com)
Frontend URL for emails (e.g. https://groceries.mydomain.com)
LOG_LEVELINFOLogging level (INFO, DEBUG, SILENT, etc.)
Logging level (INFO, DEBUG, SILENT, etc.)
values: INFO, DEBUG, SILENT
REFRESH_TOKEN_EXPIRES30dRefresh token expiration (e.g. 30d, 24h)
Refresh token expiration (e.g. 30d, 24h)
RESOLVE_CONFLICTS_FREQUENCY_MINUTES3How often to resolve CouchDB conflicts
How often to resolve CouchDB conflicts
SMTP_FROMEmail address mail appears to originate from
Email address mail appears to originate from
SMTP_HOSTSMTP host for sending emails (password resets, friend requests)
SMTP host for sending emails (password resets, friend requests)
SMTP_PASSWORDPassword for SMTP server
Password for SMTP server
SMTP_PORTSMTP port
SMTP port
SMTP_USERUsername to login to SMTP server
Username to login to SMTP server