Portainer Templates logo

Portainer Templates

Grocy (stack) Grocy (stack)

Tools

Grocy is an ERP system for your kitchen! Cut down on food waste, and manage your chores with this brilliant utility.
Source: https://github.com/grocy/grocy

Source details

Repo: grocy/grocy
Stars: 10k
Forks: 809
Language: Blade
License: MIT
Latest: v4.7.1 · 25 days ago
Updated: 13 days ago
Website: grocy.info/

Configuration

Type
Compose
Platform
linux
Image
lscr.io/linuxserver/grocy:latest
Ports
9283:80
Volumes
/config : /portainer/Files/AppData/Config/Grocy
Env vars
PUID=1000PGID=1000TZ=Europe/Athens
Restart
unless-stopped
Source
Repo

Template by xneo1·Source

Standalone Install

Select an install method, to see config/commands for deploying Grocy (stack)

Installation method

Install on Portainer

Import all app templates into your Portainer instance, for easy 1-click deploys

  1. Ensure both Docker and Portainer are installed, and up-to-date
  2. Log into your Portainer web UI
  3. Under Settings → App Templates, paste the below URL
  4. Head to Home → App Templates, and the list of apps will show up
  5. Select Grocy (stack), fill in any config options, and hit Deploy

Template Import URL

https://raw.githubusercontent.com/Lissy93/portainer-templates/main/templates.json
Show Me demo
Original stackfile

The compose file this template deploys, straight from its repo:

services:
  grocy:
    image: lscr.io/linuxserver/grocy:latest
    container_name: grocy
    environment:
      PUID: 1000
      PGID: 1000
      TZ: 'Europe/Athens'
    volumes:
      - /portainer/Files/AppData/Config/Grocy:/config
    ports:
      - 9283:80
    restart: unless-stopped

Or deploy it directly from the source:

git clone https://github.com/xneo1/portainer_templates
cd portainer_templates
docker compose -f Template/Stack/grocy.yml up -d

More install options in our documentation, or see grocy/grocy for app-specific guidance.

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

Features

See the website. →

Questions / Help / Bug Reports / Feature Requests


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

How to install

Checkout 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 (also available via the Microsoft Store) - 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
  • 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

Platform support

  • PHP 8.5 (with SQLite 3.40+)
- Required PHP extensions: fileinfo, pdo_sqlite, gd, ctype, intl, zlib, mbstring
  • Recent Firefox, Chrome or Edge

How to run using Docker

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

How to update

  • Overwrite everything with the latest release 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)

If you run Grocy on Linux, there is also update.sh (remember to make the script executable via 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 if your language is incomplete or not available yet.
The default language can be set in data/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.
The pre-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 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.
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) 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 input field (powered by ZXing, 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 and there 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.

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" (the workflow dialog is displayed when entering something unknown in any product input field) Quick video demo:
A plugin for Open Food Facts is included and used by default (see the data/config.php option STOCK_BARCODE_LOOKUP_PLUGIN).
See that plugin or plugins/DemoBarcodeLookupPlugin.php for a commented example implementation if you want to build a plugin.

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 2026-05-17
  • YYYYMMDD gets expanded to the proper ISO-8601 notation
- Example: 20260417 will be converted to 2026-04-17
  • YYYYMMe or YYYYMM+ gets expanded to the end of the given month in the given year in proper notation
- Example: 202607e will be converted to 2026-07-31
  • [+/-]n[d/m/y] gets expanded to a date relative to today, while adding (+) or subtracting (-) the number of days/months/years, 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.

Installable web app (PWA)

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:
  • Quick video demo on Android/Chrome:

Database migrations

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 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 </body> (end of body) on every page
  • When the file data/custom_css.html exists, the contents of the file will be added just before </head> (end of head) on every page

Demo mode

When the MODE setting is set to dev, demo or prerelease, 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 parameter nodemodata, e.g. https://grocy.example.com/?nodemodata to skip that).

Embedded mode

When the file embedded.txt exists, it must contain a valid and writable path which will be used as the data directory instead of data and authentication will be disabled (used in Grocy Desktop).
In embedded mode, settings can be overridden by text files in data/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).

Contributing / Say Thanks

See if you just want to say thanks or Contributing for anything else.

Roadmap

There is none. The progress of a specific bug/enhancement is always tracked in the corresponding request, 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).

Screenshots

Stock overview

Stock overview

Shopping List

Shopping List

Meal Plan

Meal Plan

Chores overview

Chores overview

License

The MIT License (MIT)

Serve Grocy (stack) on your own domain behind Caddy, Nginx or Traefik. Fill in your domain and copy the result. It's a starting point, some apps need their own base URL or extra headers set too.

Proxying grocy-stack.example.com to http://grocy:80

Add this to your Caddyfile

grocy-stack.example.com {
	reverse_proxy http://grocy:80
}

Check the logs first

Nine times out of ten the logs tell you exactly what went wrong.

  • In Portainer, go to Containers, click the container, then Logs. Or run docker logs <container>
  • Exit codes help too: 137 means killed, usually out of memory. 126 or 127 means the command inside the image is broken.

Port already in use

If deployment fails with "Bind for 0.0.0.0:9283 failed: port is already allocated", something else on your server is using that port.

  • Find what's using it: sudo ss -tlnp | grep :9283
  • Stop the other service, or pick a different host port. In 9283:80 only the left number is yours to change, the right one belongs to the app.

Running but the page won't load

The container is up but nothing appears in your browser.

  • Use your server's real IP: http://your-server-ip:9283. The 0.0.0.0 link Portainer shows isn't a real address.
  • Give it a minute after first deploy, grocy can take a while to initialise.
  • Make sure your firewall allows the port, e.g. sudo ufw allow 9283

Permission denied on volumes

If the logs show "permission denied", the app can't write to its data folder on the host.

  • Fix the ownership: sudo chown -R 1000:1000 /portainer/Files/AppData/Config/Grocy
  • Or set the PUID and PGID variables (defaults 1000:1000) to match your own user, found with id $USER

Image won't pull

Test the pull directly on the host: docker pull lscr.io/linuxserver/grocy:latest

  • "manifest unknown" means the tag no longer exists. This template uses latest, so try pinning a specific version instead.
  • "toomanyrequests" is the Docker Hub rate limit. Log in with docker login to raise it.
  • "no space left on device" means a full disk. Reclaim space with docker system prune

"exec format error"

This means the image was built for a different CPU architecture than your server.

  • Check yours with uname -m: x86_64 is amd64, aarch64 is arm64. Raspberry Pi and other ARM boards are the usual culprits.

Container keeps restarting

The unless-stopped restart policy relaunches the app after every crash, so the real error can scroll past.

  • Check the logs right after a restart, the last few lines before it died are the useful ones.
  • Get the exit code with docker inspect <container> --format '{{.State.ExitCode}}'
  • Still stuck? Redeploy once with the restart policy set to no so the failure stays visible.

Stack won't deploy

Compose stacks fail fast on small mistakes, and Portainer shows the reason just above the editor.

  • YAML only accepts spaces for indentation, a single tab breaks the whole file.

Raise an issue

Found something which isn't working as it should? Here's how to report it.

A Compose stack

Grocy (stack) is a Compose stack, a set of containers defined in one file and brought up together by Portainer, then started and stopped as a single app.

The app image

An image is the app packed up ready to go, everything Grocy (stack) needs bundled into one download. This template pulls lscr.io/linuxserver/grocy:latest, which Docker fetches once and then starts your own copy from.

Where the image comes from

Docker pulls its images from registries, public libraries of ready-built apps. Grocy (stack)'s comes from LinuxServer's registry, published by linuxserver.

Version tags

The bit after the colon in the image name is the version tag. Here it's latest, which always points at the newest build, so a redeploy can bump you to a newer release without you asking. Pin a specific tag if you would rather stay on one version.

Ports

A port is the door the app answers on. A mapping like 9283:80 means it's reachable on port 9283 of your server, where the left number is yours to change and the right one belongs to the app. Once it's running, open http://your-server-ip:9283 in a browser. It opens:

  • 9283:80, likely the web interface

Volumes

A volume is where Grocy (stack) keeps its files so they survive an update or a restart. Without one, anything it saves would sit inside the container and vanish the moment it's recreated. This template mounts:

  • /config from /portainer/Files/AppData/Config/Grocy on the host

Environment variables

Environment variables are the settings you hand over when you deploy, things like a password or a timezone. Grocy (stack) takes 3 of them, all with defaults you can leave alone or tweak:

  • PUID, defaults to 1000
  • PGID, defaults to 1000
  • TZ, defaults to Europe/Athens

Restart policy

The restart policy here is unless-stopped, so Docker restarts Grocy (stack) after a crash or reboot, but leaves it off when you stop it on purpose. You can change this on the deploy screen. The choices are no (never restart), on-failure (only after a crash), unless-stopped (restart unless you stop it), and always (bring it back no matter what).

Users and permissions

The PUID and PGID settings tell it which user and group to act as on your host. Point them at your own account (find yours with id $USER) so the files it writes into your mounted folders come out owned by you rather than root.

Networking

Nothing custom is set, so Grocy (stack) sits on Docker's default bridge network: its own private space that reaches the outside world only through the ports it publishes.

Container name

Once it's deployed, Portainer names the container grocy. That's what you'll spot in the containers list and use in commands like docker logs grocy.

Platform

The platform is linux, the kind of system the container is built to run on. Docker and Portainer handle this on a normal Linux server.

Open source license

Grocy (stack) is open source, released under the MIT license. In plain terms the code is out in the open, so you're free to run it and change it to fit what you need.

Portainer app templates

Zooming out, this whole page comes from a Portainer app template: a short recipe telling Portainer how to set Grocy (stack) up. Add the template list to Portainer once, then deploying Grocy (stack) is a click rather than a wall of config.