Why Track What You Own Before You Buy More
Grocy is an open-source, self-hosted grocery and household management system built for people who want full control over what comes in and out of their home. It tracks products, expiration dates, shopping lists, recipes, chores, and equipment – all from a private server you run yourself. No subscription, no data sharing, no cloud dependency.
The appeal is practical. Most households repurchase items they already have, let food expire without noticing, and have no reliable system for knowing what needs restocking. Grocy solves all three problems with a clean web interface and a surprisingly capable API that supports barcode scanning through companion apps.
This guide walks through a full Grocy installation using Docker, covers initial configuration, and gets your first products into the system.
What You Need Before You Start
Grocy runs well on modest hardware. A Raspberry Pi 4, an old desktop repurposed as a home server, or any Linux VPS with at least 512MB of RAM will handle it without strain. The Docker installation path is the cleanest option and avoids dependency conflicts entirely. You will need Docker and Docker Compose installed on your host machine before proceeding.
You should also decide on a port. Grocy defaults to port 9283 in most Docker configurations, but if that conflicts with another service on your network, pick something free like 8080 or 9100. If you are running Grocy alongside other self-hosted services – media servers, RSS readers, or similar tools – confirm there are no port collisions before writing your compose file.
Have a text editor ready, know your server’s local IP address, and optionally set up a local domain using your router or a tool like Pi-hole so you can reach Grocy by name instead of by IP. That last step is optional but makes daily use significantly more comfortable.
Installing Grocy with Docker Compose
Create a directory for Grocy and open a new file called docker-compose.yml inside it. The official Linuxserver.io image is the most consistently maintained and the one most home server users rely on.
Paste the following into your compose file:
version: "3"
services:
grocy:
image: lscr.io/linuxserver/grocy:latest
container_name: grocy
environment:
- PUID=1000
- PGID=1000
- TZ=America/New_York
volumes:
- ./config:/config
ports:
- 9283:80
restart: unless-stopped
Adjust TZ to match your timezone. The PUID and PGID values should match the user running Docker on your host – run id in your terminal to confirm those numbers. Once the file is saved, run docker compose up -d from the same directory. Docker will pull the image and start the container. Within thirty seconds, Grocy should be accessible at http://your-server-ip:9283 in any browser on your network.
First Login and Base Configuration
The default credentials are admin for both username and password. Change the password immediately after logging in. Go to the top-right menu, select Manage Users, and update your credentials there.
Before adding any products, spend ten minutes inside the settings panel. Navigate to Settings from the main menu and work through the base configuration. Set your currency, default quantity units, and decide whether you want Grocy to track product prices. The Stock section of settings controls how expiration dates are displayed and whether due-soon alerts appear on the dashboard. Set Days to show as “due soon” to something practical – five to seven days works well for most households. You can also configure whether Grocy uses first-in-first-out consumption logic, which matters if you are tracking items with varying expiration dates.
Under Quantity Units, add any units your household regularly uses that are not already present – things like “roll”, “pack”, “bottle”, or “bag”. These will be available when you create products later. Getting this foundation right saves editing time as your inventory grows.
Adding Products and Populating Your Inventory
Products in Grocy live under the Master Data section. Each product gets a name, default quantity unit, a minimum stock amount (which triggers shopping list suggestions), and optionally a barcode. Add a few manually to get familiar with the form before committing to a large import.
Barcode scanning is where Grocy’s daily usability jumps considerably. The companion app Grocy Android (available on F-Droid and GitHub) or Grocy iOS connects to your server via the API key found under Settings > Manage API Keys. Once connected, you can scan a product barcode directly into Grocy. If the barcode is already associated with a product in your database, it logs the addition instantly. If not, it prompts you to create a new product. Over a few weeks of scanning items as they come in from grocery runs, the database fills naturally without requiring a dedicated setup session.
For initial bulk setup, Grocy supports CSV import under Master Data > Products. Prepare a spreadsheet with columns matching Grocy’s expected format – product name, quantity unit, minimum stock amount – and import it directly. This is the fastest path if you want to build out fifty or more products before scanning starts.
Making Grocy Part of a Daily Routine
Grocy’s shopping list feature auto-populates based on minimum stock thresholds. When a product’s current stock falls below its set minimum, it appears on the shopping list automatically. After a grocery trip, mark items as purchased and Grocy updates stock counts. The loop is tight enough that most households who stick with it for a month find it genuinely cuts down on redundant purchases – not because the app is clever, but because it makes the invisible visible.
Chores and equipment tracking are features that often go overlooked during initial setup. The Chores module lets you schedule recurring tasks with due dates, which works well for things like filter replacements, appliance cleaning, or pantry audits. The Equipment module tracks household items with associated manuals and next maintenance dates. Neither feature is flashy, but both answer a real question most home management tools ignore: when did you last do this, and when should you do it again.
One unresolved question worth sitting with – Grocy is only as accurate as the data you put in. The system has no way to detect when someone takes the last of something without logging it, which means household-wide adoption determines whether the inventory reflects reality. Running Grocy solo in a shared household means trusting that everyone else will scan out what they use, and that trust has a long track record of being misplaced.
