Repository files navigation

ERP beyond your fridge

Grocy is a web-based self-hosted groceries & household management solution for your home

This is a hobby project byBernd Bestel

• Public demo of the latest stable version (release branch) →https://demo.grocy.info
• Public demo of the current development version (master branch) →https://demo-prerelease.grocy.info

See the website. →https://grocy.info

• General help and usage questions →r/grocy subreddit
• Bug Reports and Feature Requests →Issue Tracker

Please don't send me private messages or call me regarding anything Grocy. I check the issue tracker and the subreddit pretty much daily, but don't provide any support beyond that.

See the website for a list of community contributed Add-ons / Tools. →https://grocy.info/addons

CheckoutGrocy Desktop, if you want to run Grocy without having to manage a webserver just like a normal (Windows) desktop application.

Directly download thelatest release - the installation is nothing more than just clicking 2 times "next".

Grocy is technically a pretty simple PHP application, so the basic notes to get it running are:

• Unpack thelatest release
• Copyconfig-dist.php todata/config.php + edit to your needs
• Ensure that thedata directory is writable
• The webserver root should point to thepublic directory
• Includetry_files $uri /index.php$is_args$query_string; in your location block if you use nginx
  • Or disable URL rewriting (see the optionDISABLE_URL_REWRITING indata/config.php)
• → Default login is useradmin with passwordadmin, please change the password immediately (user menu at the top right corner)

Alternatively clone this repository (therelease branch always references the latest released version) and install Composer and Yarn dependencies manually.

See the website for more installation guides and troubleshooting help. →https://grocy.info/links

• PHP 8.2 or 8.3 (with SQLite 3.34.0+)
  • Required PHP extensions:fileinfo,pdo_sqlite,gd,ctype,intl,zlib,mbstring
  • Recommendation: Benchmark tests showed that e.g. unit conversion handling is up to 5 times faster when using a more recent (3.39.4+) SQLite version.
• Recent Firefox, Chrome or Edge

→https://hub.docker.com/r/linuxserver/grocy

• Overwrite everything with thelatest release while keeping thedata directory
• Checkconfig-dist.php for new configuration options and add them to yourdata/config.php where appropriate (the default values fromconfig-dist.php will be used for not indata/config.php defined settings)

If you run Grocy on Linux, there is alsoupdate.sh (remember to make the script executable (chmod +x update.sh) and ensure that you haveunzip installed) which does exactly this and additionally creates a backup (.tgz archive) of the current installation indata/backups (backups older than 60 days will be deleted during the update).

Grocy is fully localizable - the default language is English (integrated into code), a German localization is always maintained by me.

You can easily help translating Grocy onTransifex if your language is incomplete or not available yet.

The default language can be set indata/config.php, e. g.Setting('DEFAULT_LOCALE', 'de'); and there is also a user setting (see the user settings page) to set a different language per user.

Thepre-release demo is available for any translation which is at least 70 % complete and will pull the translations from Transifex 10 minutes past every hour, so you can have a kind of instant preview of your contributed translations. Thank you!

Also any translation which once reached a completion level of 70 % (strings resource) will be included in releases.

RTL languages are unfortunately not yet supported.

A household needs to be managed. Before Grocy I did this (for almost 10 years) using my first self written software (a C# Windows forms application) and with a bunch of Excel sheets. The software was a pain to use at the end and Excel is Excel. So I searched for and tried different things for a (very) long time, nothing 100 % fitted, so this is my aim for a "complete household management"-thing. ERP your fridge!

See the integrated Swagger UI instance on/api.

The web frontend uses exactly this API for pretty much everything. So everything you can do there is also possible via the API.

Some fields (with a barcode icon above) also allow to select a value by scanning a barcode. It works best when your barcode reader prefixes every barcode with a letter which is normally not part of a item name (I use a$) and sends aTAB after a scan.

Additionally it's also possible to use your device camera to scan a barcode by using the camera button on the right side of the corresponding input field (powered byQuagga2, totally offline / client-side camera stream processing, please note due to browser security restrictions, this only works when serving Grocy via a secure connection (https://)).Here andthere are quick video demos of that.

My personal recommendation: Use a USB barcode laser scanner. They are cheap and work 1000 % better, faster, under any lighting condition and from any angle.

Products can be directly added to the database via looking them up against external services by a barcode.

This can be done in-place using the product picker workflow "External barcode lookup" (the workflow dialog is displayed when entering something unknown in any product input field) Quick video demo:https://www.youtube.com/watch?v=-moXPA-VvGc

A plugin forOpen Food Facts is included and used by default (see thedata/config.php optionSTOCK_BARCODE_LOOKUP_PLUGIN).

See that plugin orplugins/DemoBarcodeLookupPlugin.php for a commented example implementation if you want to build a plugin.

For (productivity) reasons all date (and time) input (and display) fields use the ISO-8601 format regardless of localization.The following shorthands are available:

• MMDD gets expanded to the given day on the current year, if > today, or to the given day next year, if < today, in proper notation
  • Example:0517 will be converted to2025-05-17
• YYYYMMDD gets expanded to the proper ISO-8601 notation
  • Example:20250417 will be converted to2025-04-17
• YYYYMMe orYYYYMM+ gets expanded to the end of the given month in the given year in proper notation
  • Example:202507e will be converted to2025-07-31
• [+/-]n[d/m/y] gets expanded to a date relative to today, while adding (+) or subtracting (-) thenumber ofdays/months/years, in proper notation
  • Example:+1m will be converted to the same day next month
• x gets expanded to2999-12-31 (which is an alias for "never overdue")
• Down/up arrow keys will increase/decrease the date by 1 day
• Right/left arrow keys will increase/decrease the date by 1 week
• Shift + down/up arrow keys will increase/decrease the date by 1 month
• Shift + right/left arrow keys will increase/decrease the date by 1 year

Wherever a button contains a bold highlighted letter, this is a shortcut key.Example: Button "P Add as new product" can be "pressed" by using theP key on your keyboard.

Grocy's web frontend is responsive and an "installable web app" (PWA, without providing any offline usage capabilities), that provides a pretty native mobile app-like experience without the need for additional tools.

• Quick video demo on Android/Firefox:https://www.youtube.com/watch?v=L38drVZfwHs
• Quick video demo on Android/Chrome:https://www.youtube.com/watch?v=rjLdXUFDNuk

Database schema migration is done when visiting the root (/) route (click on the logo in the left upper edge) as needed and is also triggered automatically if the version has changed (so when an update has been made).

Please note: Database migrations are supposed to work between releases, not between every commit. If you want to run the currentmaster branch (which is the development version), you need to handle that (and more) yourself.

If you don't use certain feature sets of Grocy (for example if you don't need "Chores"), there are feature flags per major feature set to hide/disable the related UI elements (seeconfig-dist.php).

• When the filedata/custom_js.html exists, the contents of the file will be added just before</body> (end of body) on every page
• When the filedata/custom_css.html exists, the contents of the file will be added just before</head> (end of head) on every page

When theMODE setting is set todev,demo orprerelease, the application will work in a demo mode which means authentication is disabled and some demo data will be generated during the database schema migration (pass the query parameternodemodata, e.g.https://grocy.example.com/?nodemodata to skip that).

When the fileembedded.txt exists, it must contain a valid and writable path which will be used as the data directory instead ofdata and authentication will be disabled (used inGrocy Desktop).

In embedded mode, settings can be overridden by text files indata/settingoverrides, the file name must be<SettingName>.txt (e. g.BASE_URL.txt) and the content must be the setting value (normally one single line).

Any help is welcome, feel free to contribute anything which comes to your mind or seehttps://grocy.info/#say-thanks if you just want to say thanks.

There is none. The progress of a specific bug/enhancement is always tracked in the corresponding issue, at least by commit comment references.

Milestones are used to indicate in which version the corresponding request was done (vNEXT means it's currently planned to do that for the next release).

The MIT License (MIT)