Self-Hosting Grocy with Docker Compose

What Is Grocy?

Grocy bills itself as an “ERP beyond your fridge” — it tracks groceries, household inventory, chores, meal plans, recipes, batteries, and equipment. Scan barcodes to add products, set expiration dates to reduce food waste, plan meals from your recipe collection, and assign chores to household members. It’s for people who want spreadsheet-level control over their household without actually maintaining spreadsheets.

Official site: grocy.info | GitHub

Prerequisites

• A Linux server or Raspberry Pi (ARM supported)
• Docker and Docker Compose installed (guide)
• 500 MB of free disk space
• 256 MB of RAM minimum
• A domain name (optional)

Docker Compose Configuration

services:
  grocy:
    image: lscr.io/linuxserver/grocy:4.3.0
    container_name: grocy
    restart: unless-stopped
    ports:
      - "9283:80"
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
    volumes:
      - grocy-config:/config
    networks:
      - grocy-net

volumes:
  grocy-config:

networks:
  grocy-net:

Grocy uses SQLite internally — no external database needed.

Start the stack:

docker compose up -d

Initial Setup

Access Grocy at http://your-server-ip:9283.

Default credentials:

• Username: admin
• Password: admin

Change the default password immediately after first login: click your username → Change password.

Key Features

Module	What It Does
Stock	Track groceries and household items with quantities, expiration dates, locations
Shopping list	Auto-generate from low-stock items or meal plans
Recipes	Store recipes with ingredient links to your stock
Meal planning	Plan meals by day, auto-deduct ingredients from stock
Chores	Assign and schedule household tasks with tracking
Batteries	Track battery replacement dates for devices
Equipment	Manage household equipment with manuals and warranty dates
Barcode scanning	Scan products to add or consume stock
Custom fields	Add arbitrary fields to any entity
API	Full REST API for mobile apps and automation

Configuration

Barcode Scanning

Grocy works with USB barcode scanners and the Grocy Android app. The Android app scans barcodes and looks up products via the Open Food Facts database.

To enable external barcode lookups, go to Settings → Manage API Keys and create a key for the Android app.

Multi-User Setup

Add users in the admin panel: Manage Users → Add. Each user can have their own shopping list and chore assignments. Assign chores to specific users with recurrence schedules.

Location Tracking

Set up storage locations (Fridge, Pantry, Freezer, Garage) under Master Data → Locations. When adding stock, assign items to locations. Grocy tracks where everything is and shows what’s expiring soon per location.

Customizing with config.php

For advanced settings, edit the config file inside the container:

docker compose exec grocy vi /config/data/config.php

Key settings:

// Change calendar week start (0=Sunday, 1=Monday)
Setting('CALENDAR_FIRST_DAY_OF_WEEK', 1);

// Set currency
Setting('CURRENCY', 'USD');

// Feature flags — disable modules you don't use
Setting('FEATURE_FLAG_STOCK', true);
Setting('FEATURE_FLAG_SHOPPINGLIST', true);
Setting('FEATURE_FLAG_RECIPES', true);
Setting('FEATURE_FLAG_CHORES', true);
Setting('FEATURE_FLAG_BATTERIES', false);  // Disable batteries module
Setting('FEATURE_FLAG_EQUIPMENT', false);  // Disable equipment module

Reverse Proxy

For HTTPS access, see Reverse Proxy Setup. No special headers are required — Grocy works behind any standard reverse proxy.

Backup

Back up the grocy-config volume — it contains the SQLite database and all configuration:

docker compose cp grocy:/config ./grocy-backup-$(date +%Y%m%d)

The database file is at /config/data/grocy.db. For a full backup strategy, see Backup Strategy.

Troubleshooting

Barcode Not Found

Symptom: Scanning a barcode returns “Product not found.”

Fix: Not all products exist in Open Food Facts. Create the product manually in Grocy and assign the barcode. The next scan will find it. You can also contribute missing products to Open Food Facts.

”Permission Denied” Errors

Symptom: Cannot save settings or add products.

Fix: Ensure PUID and PGID in the Compose file match your host user’s UID/GID:

id  # Shows your UID and GID

Date Format Issues

Symptom: Expiration dates display in the wrong format.

Fix: Set your locale in Settings → User Settings. Choose your preferred date format (YYYY-MM-DD, DD.MM.YYYY, MM/DD/YYYY).

Resource Requirements

• RAM: ~50 MB (SQLite is extremely lightweight)
• CPU: Minimal
• Disk: ~100 MB for the application, grows slowly with product images

Verdict

Grocy is comprehensive to a fault — it tracks everything from groceries to batteries, which means it takes effort to set up properly. If you only want a shopping list, it’s overkill. But if you want to reduce food waste with expiration tracking, meal plan from your recipe collection, and keep your household running on a schedule, Grocy does all of it in one place. The barcode scanning with the Android app makes daily use practical. For simpler grocery/recipe management without the ERP complexity, KitchenOwl or Mealie are lighter alternatives.

Related

• Grocy: Barcode Scanner Not Working — Fix
• Home Inventory for Insurance Documentation
• Grocy vs Homebox: Home Inventory Compared
• Tandoor vs Grocy: Recipe Manager vs Kitchen Inventory
• Grocy vs Snipe-IT
• Self-Hosting Mealie with Docker Compose
• Self-Hosting KitchenOwl with Docker Compose
• Best Self-Hosted Recipe Managers
• Self-Hosting Homebox with Docker Compose
• Docker Compose Basics
• Reverse Proxy Setup
• Backup Strategy