Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/grocy/grocy

ERP beyond your fridge - Grocy is a web-based self-hosted groceries & household management solution for your home
https://github.com/grocy/grocy

erp food groceries grocy home meal-planner ownyourdata php self-hosted

Last synced: 4 days ago
JSON representation

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

Awesome Lists containing this project

README 

        
-----





Logo

ERP beyond your fridge


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


This is a hobby project by Bernd Bestel






-----



## Give it a try



- Public demo of the latest stable version (`release` branch) → [https://demo.grocy.info](https://demo.grocy.info)

- Public demo of the current development version (`master` branch) → [https://demo-prerelease.grocy.info](https://demo-prerelease.grocy.info)



## Features



See the website. → 



## Questions / Help / Bug Reports / Feature Requests



- General help and usage questions →  [r/grocy subreddit](https://www.reddit.com/r/grocy)

- Bug Reports and Feature Requests → [Issue Tracker](https://github.com/grocy/grocy/issues/new/choose)



_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._



## Community contributions



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



## How to install



> Checkout [Grocy Desktop](https://github.com/grocy/grocy-desktop), if you want to run Grocy without having to manage a webserver just like a normal (Windows) desktop application.

>

> Directly download the [latest release](https://releases.grocy.info/latest-desktop) - 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 the [latest release](https://releases.grocy.info/latest)

- Copy `config-dist.php` to `data/config.php` + edit to your needs

- Ensure that the `data` directory is writable

- The webserver root should point to the `public` directory

- Include `try_files $uri /index.php$is_args$query_string;` in your location block if you use nginx

  - Or disable URL rewriting (see the option `DISABLE_URL_REWRITING` in `data/config.php`)

- → Default login is user `admin` with password `admin`, please change the password immediately (user menu at the top right corner)



Alternatively clone this repository (the `release` 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](https://grocy.info/links)



### Platform support



- 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



## How to run using Docker



See [grocy/grocy-docker](https://github.com/grocy/grocy-docker) or [linuxserver/docker-grocy](https://github.com/linuxserver/docker-grocy) for instructions.



## How to update



- Overwrite everything with the [latest release](https://releases.grocy.info/latest) while keeping the `data` directory

- Check `config-dist.php` for new configuration options and add them to your `data/config.php` where appropriate (the default values from `config-dist.php` will be used for not in `data/config.php` defined settings)

- Empty the `data/viewcache` directory

- Visit the main route once to apply database migrations ([see below](https://github.com/grocy/grocy#database-migrations))



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



## Localization



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 on [Transifex](https://www.transifex.com/grocy/grocy/dashboard/) if your language is incomplete or not available yet.



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



The [pre-release demo](https://demo-prerelease.grocy.info) 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](https://www.transifex.com/grocy/grocy/strings/)) will be included in releases.



_RTL languages are unfortunately not yet supported._



## Motivation



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!



## Things worth to know



### REST API



See the integrated Swagger UI instance on [/api](https://demo.grocy.info/api).



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



### Barcode readers & camera scanning



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 a `TAB` 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 field (powered by [Quagga2](https://github.com/ericblade/quagga2), 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://`)). Quick video demo: 



_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._



### Input shorthands for date fields



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 to `2024-05-17`

- `YYYYMMDD` gets expanded to the proper ISO-8601 notation

  - Example: `20240417` will be converted to `2024-04-17`

- `YYYYMMe` or `YYYYMM+` gets expanded to the end of the given month in the given year in proper notation

  - Example: `202407e` will be converted to `2024-07-31`

- `[+/-]n[d/m/y]` gets expanded to a date relative to today, while adding (**+**) or subtracting (**-**) the **n**umber of **d**ays/**m**onths/**y**ears, in proper notation

  - Example: `+1m` will be converted to the same day next month

- `x` gets expanded to `2999-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



### Keyboard shorthands for buttons



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 the `P` key on your keyboard.



### Barcode lookup via external services



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 (via plugin)" (the workflow dialog is displayed when entering something unknown in any product input field).



There is no plugin included for any service, see the reference implementation in `data/plugins/DemoBarcodeLookupPlugin.php`.



### Database migrations



Database schema migration is automatically done when visiting the root (`/`) route (click on the logo in the left upper edge).



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



### Disable certain features



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 (see `config-dist.php`).



### Adding your own CSS or JS without to have to modify the application itself



- When the file `data/custom_js.html` exists, the contents of the file will be added just before `