Why Grocy Belongs on Your Home Server
Most grocery apps are built around selling you something – a subscription, a delivery service, or your own shopping data. Grocy takes a different approach entirely. It is an open-source, self-hosted household management system that tracks groceries, manages recipes, monitors expiration dates, and handles chores and tasks, all running on your own hardware with no third-party account required. Once it is up and running, your household data stays exactly where it should: on your server.
Getting Grocy deployed via Docker is straightforward, even for those who have not run many self-hosted apps before. The setup requires Docker and Docker Compose, a basic comfort with terminal commands, and about fifteen minutes. This guide walks through every step from container configuration to first login, including how to expose Grocy safely if you want to access it outside your home network.
Prerequisites and What You Will Need
Before starting, confirm that Docker and Docker Compose are installed on your host machine. This can be a Raspberry Pi, an old desktop repurposed as a home server, a NAS device running Docker, or any Linux-based machine on your local network. Grocy is lightweight and runs comfortably on low-spec hardware – a Raspberry Pi 4 with 2GB of RAM handles it without any issues. You will also want a static local IP address assigned to your server, either through your router’s DHCP reservation or set manually on the host itself.
On the software side, you need a terminal with SSH access to your server if you are managing it headlessly. Create a working directory for the project before writing any configuration files. Something like /opt/grocy or ~/docker/grocy works well. All your Compose files and persistent data volumes will live here, so pick a path you will remember and that survives reboots without permission issues.
Writing the Docker Compose File
Navigate into your grocy directory and create a file named docker-compose.yml. The official Grocy Docker image is maintained at lscr.io/linuxserver/grocy, which is the LinuxServer.io build and the most actively updated option available. This image handles user permissions cleanly using the PUID and PGID environment variables, which map the container’s internal user to a user on your host system.
Paste the following into your compose file:
- image: lscr.io/linuxserver/grocy:latest
- container_name: grocy
- environment: PUID=1000, PGID=1000, TZ=America/New_York (adjust to your timezone)
- volumes: ./config:/config
- ports: 9283:80
- restart: unless-stopped
The port mapping 9283:80 exposes Grocy on port 9283 of your host. You can change 9283 to any unused port on your machine. The ./config volume mount is where Grocy stores its SQLite database and all configuration files. Because this is a bind mount pointing to your working directory, the data persists across container restarts and updates without needing any additional volume management.
To find the correct PUID and PGID for your server user, run id in the terminal while logged in as the user you want to own the files. The output shows your uid and gid values. Plug those numbers directly into the compose file. Getting these right prevents permission errors where the container cannot write to the config directory, which is a common stumbling block on first runs.
Starting Grocy and Logging In
With the compose file saved, start the container by running docker compose up -d from inside your grocy directory. Docker pulls the image, which is around 100MB, and starts the container in detached mode. Check that it came up cleanly with docker compose logs -f grocy and look for a line indicating the web server is listening. You can exit the log view with Ctrl+C once you see it running.
Open a browser on any device on your local network and navigate to http://your-server-ip:9283. The default login credentials for a fresh Grocy installation are username admin and password admin. Change the password immediately after first login under the user settings menu – Grocy does not force a password change on first run, so this step is easy to skip and easy to forget.
Configuring Grocy for Your Household
Before adding any products, spend a few minutes inside the settings panel. Under Settings, you can configure your currency, energy unit, date format, and the number of days Grocy uses for “due soon” warnings on expiring products. These settings inform how data displays throughout the entire interface, so adjusting them upfront saves tedious corrections later when you have hundreds of products entered.
Grocy organizes products into locations and product groups. Locations represent physical storage spots in your home – refrigerator, pantry shelf, freezer, bathroom cabinet. Product groups are category labels like dairy, produce, or cleaning supplies. Setting these up before you start adding inventory makes the system much easier to navigate once it is populated. Go to Masterdata in the top menu to manage both. You can add as many or as few as your household actually needs – there is no requirement to model every drawer in the kitchen.
The barcode scanning feature is one of Grocy’s most practical tools. Each product entry can store one or more barcodes, and once a barcode is saved, you can use a USB barcode scanner or a smartphone app to log purchases and consume items without typing anything manually. The official companion app Grocy for Android (available on F-Droid and the Play Store) connects directly to your Grocy instance and supports barcode scanning through your phone’s camera. To connect the app, go to Manage API Keys under your user settings and generate an API key, then enter your server’s local address and that key in the app’s configuration screen.
If you plan to access Grocy from outside your home network – from a grocery store, for example – the cleanest way to do that without exposing your server directly is to place it behind a reverse proxy with SSL. Nginx Proxy Manager is a straightforward option that handles SSL certificate provisioning through Let’s Encrypt and lets you assign a subdomain to your Grocy instance with a few clicks.
Keeping Grocy Updated and Backed Up
Updating Grocy is a two-command process. Pull the latest image with docker compose pull, then restart the container with docker compose up -d. The container rebuilds using the new image, and because all your data lives in the ./config bind mount rather than inside the container itself, nothing is lost during the update. This is one of the main advantages of the volume setup described earlier.
Backing up Grocy means backing up the config directory. The entire SQLite database is stored as a single file at ./config/data/grocy.db. A simple scheduled script that copies this file to a secondary location – a network share, an external drive, or a remote backup service – is enough to protect your data. If you ever need to migrate Grocy to a new server, copy the entire config directory, point the new container at it, and the instance comes up exactly as you left it, with all products, recipes, and history intact.
One detail worth knowing: Grocy includes a built-in backup and restore tool under About – Grocy in the top menu. It generates a zip file containing the database and any uploaded images, which you can download directly from the browser. This works as a quick manual snapshot before any major configuration change, and it does not require SSH access or server-side scripting to use.
