Deploying Grocy

Introduction

Grocy is a comprehensive self-hosted grocery and household management solution. It helps you track what is in your pantry, manage shopping lists, plan meals, and keep on top of household chores. Think of it as an ERP system for your household.

Built with PHP, Grocy provides a web-based interface accessible from any device. It goes far beyond simple grocery lists by tracking quantities, expiration dates, prices, and nutritional information. The application also includes task management, equipment tracking, and recipe planning.

Key highlights of Grocy:

Stock Management: Track products with quantities, expiration dates, and locations
Shopping Lists: Create and manage shopping lists with automatic stock integration
Recipe Planning: Store recipes and plan meals
Meal Planning: Calendar-based meal scheduling
Chores Tracking: Manage household tasks and schedules
Battery Tracking: Track rechargeable battery cycles
Equipment Management: Record equipment and maintenance schedules
Barcode Support: Scan products for quick entry
Multi-User: Support for multiple household members
API Access: Full REST API for integrations
Mobile Apps: Third-party mobile applications available
Open Source: Licensed under MIT

This guide walks through deploying Grocy on Klutch.sh using Docker.

Why Deploy Grocy on Klutch.sh

Deploying Grocy on Klutch.sh provides several advantages:

Family Access: All household members can access from any device.

Always Available: Check your pantry or shopping list from anywhere.

Persistent Data: Your inventory and history survive updates.

HTTPS Security: Secure access to your household data.

No Infrastructure: No need to maintain home servers.

Prerequisites

Before deploying Grocy on Klutch.sh, ensure you have:

A Klutch.sh account
A GitHub account with a repository for your configuration
Basic familiarity with Docker
(Optional) A custom domain for your Grocy instance

Understanding Grocy Architecture

Grocy consists of:

PHP Application: Core application logic and web interface.

SQLite Database: Stores all product, stock, and household data.

File Storage: Product images and attachments.

Web Server: Serves the PHP application.

Preparing Your Repository

Create a GitHub repository with your Grocy configuration.

Repository Structure

grocy-deploy/
├── Dockerfile
└── .dockerignore

Creating the Dockerfile

FROM linuxserver/grocy:latest

# Set environment variables
ENV PUID=1000
ENV PGID=1000
ENV TZ=America/New_York

# Expose web interface
EXPOSE 80

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD curl -f http://localhost:80 || exit 1

Environment Variables Reference

Variable	Required	Description
`PUID`	No	User ID for file ownership
`PGID`	No	Group ID for file ownership
`TZ`	No	Timezone (e.g., America/New_York)
`GROCY_CULTURE`	No	Language/locale setting
`GROCY_CURRENCY`	No	Default currency

Deploying Grocy on Klutch.sh

Push Your Repository to GitHub

Commit your Dockerfile to GitHub.

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project named “grocy” or “household”.

Create a New App

Create a new app and connect your GitHub repository.

Configure HTTP Traffic

Set up HTTP traffic:

Select HTTP as the traffic type
Set the internal port to 80

Set Environment Variables

Variable	Value
`TZ`	Your timezone
`GROCY_CULTURE`	en (or your language)
`GROCY_CURRENCY`	USD (or your currency)

Attach Persistent Volumes

Mount Path	Size	Purpose
`/config`	5 GB	Database and configuration

Deploy Your Application

Click Deploy to build and launch Grocy.

Complete Initial Login

Access Grocy at your app URL. Default credentials:

Username: admin
Password: admin

Change the default password immediately.

Initial Setup

System Configuration

Go to Settings
Configure:
- Language
- Currency
- Date and time format
- First day of week

Location Setup

Create storage locations:

Go to Master Data > Locations
Add locations like:
- Pantry
- Refrigerator
- Freezer
- Basement
- Garage

Product Groups

Organize products by category:

Go to Master Data > Product Groups
Create groups like:
- Dairy
- Meat
- Vegetables
- Canned Goods
- Snacks

Quantity Units

Configure measurement units:

Go to Master Data > Quantity Units
Add units like:
- Pieces
- Pounds
- Ounces
- Liters
- Packages

Stock Management

Adding Products

Go to Master Data > Products
Click “Add”
Fill in:
- Name
- Product group
- Default location
- Minimum stock amount
- Default expiration days
Save the product

Stock Entries

Record what you have:

Go to Stock > Purchase
Select product
Enter:
- Amount
- Best before date
- Price (optional)
- Location
Add to stock

Consuming Stock

Record usage:

Go to Stock > Consume
Select product
Enter amount consumed
Specify if opened

Stock Overview

View current inventory:

Products at location
Items expiring soon
Below minimum stock
Total stock value

Shopping Lists

Creating Lists

Go to Shopping List
Add items:
- From products below minimum
- Manually
- From recipes
Print or use on mobile

Automatic Additions

Configure automatic shopping list additions:

Products below minimum stock
Recipe ingredients
Scheduled additions

Recipe Management

Adding Recipes

Go to Recipes
Click “Add”
Enter:
- Name
- Description
- Servings
- Instructions
Add ingredients from products
Save recipe

Recipe Features

Scale servings
Calculate costs
Check stock for ingredients
Add missing items to shopping list

Meal Planning

Calendar

Go to Meal Plan
Click on a day
Select:
- Recipe
- Section (Breakfast, Lunch, Dinner)
Plan meals for the week

Shopping Integration

Generate shopping lists from meal plans with missing ingredients.

Chores Tracking

Setting Up Chores

Go to Chores
Add chores like:
- Clean kitchen
- Vacuum living room
- Take out trash
Set:
- Frequency
- Assigned user
- Track date

Tracking Completion

Mark chores as done and track history.

User Management

Adding Users

Go to User Management
Create users for household members
Set permissions:
- Admin
- Normal user

User Features

Personal shopping lists
Assigned chores
Activity tracking

Barcode Scanning

Product Lookup

Grocy can look up products by barcode:

Enable product lookup service
Scan barcodes to find products
Add to your database

Mobile Scanning

Use mobile apps:

Grocy Mobile (iOS)
Pantry Party (Android)
Grocy Barcode Scanner

API Integration

REST API

Grocy provides a full REST API:

# Get all products
curl -H "GROCY-API-KEY: your-api-key" \
  https://your-app.klutch.sh/api/objects/products

# Add stock
curl -X POST \
  -H "GROCY-API-KEY: your-api-key" \
  -d '{"amount": 5}' \
  https://your-app.klutch.sh/api/stock/products/1/add

API Key

Generate API keys in Settings > API Keys.

Backup Strategy

Database Backup

Back up the SQLite database regularly:

/config/data/grocy.db

Export Features

Grocy can export:

Products (CSV)
Stock entries (CSV)
Recipes

Mobile Access

Responsive Design

The web interface works on mobile browsers.

Third-Party Apps

Dedicated mobile apps provide:

Barcode scanning
Quick consumption
Shopping list access

Troubleshooting

Verify credentials
Clear browser cache
Check session settings

Stock Discrepancies

Perform inventory
Check consumption logs
Review stock corrections

Performance Issues

Optimize database
Review product count
Check server resources

Additional Resources

Conclusion

Deploying Grocy on Klutch.sh provides a comprehensive household management solution accessible from anywhere. From pantry tracking to meal planning and chore management, Grocy helps bring organization to daily household tasks.

The combination of Grocy’s extensive features and Klutch.sh’s reliable hosting creates an ideal platform for household management.