Grocy on AWS User Guide

Overview

Grocy is an open source, self-hosted groceries and household management solution, an ERP for your home. It tracks your food stock and best before dates, manages your shopping list, stores your recipes and meal plans, and schedules your recurring chores, batteries and equipment, all from one clean web interface and a full REST API. This image runs Grocy behind nginx, with PHP FPM 8.3 and OPcache enabled.

Grocy stores its data in SQLite, so the appliance is fully self-contained: there is no separate database server to install, secure or back up. The SQLite database, the configuration and the file storage live under /var/lib/grocy on a dedicated, independently resizable EBS volume, so you can grow your household data store without touching the operating system disk.

The database schema is already initialised in the image, so there is no first-run setup to step through, and no demo data is shipped. The Grocy administrator password is generated on the first boot of every deployed instance. Two instances launched from the same Amazon Machine Image never share credentials. The initial administrator password is written to /root/grocy-credentials.txt with mode 0600 so that only the root user can read it.

Prerequisites

Before you deploy this image you need:

• An Amazon Web Services account where you can launch EC2 instances
• IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
• An EC2 key pair in the target Region for SSH access to the instance
• A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network and inbound ports 80 and 443 from the networks your users will browse from
• The AWS CLI (version 2) installed locally if you plan to deploy from the command line

Step 1: Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for Grocy. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of m5.large or larger. Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that allows inbound port 22 from your management network and inbound ports 80 and 443 from the networks your users browse from. Leave the root and data volumes at their default sizes or larger.

Select Launch instance. First boot initialisation takes approximately one minute after the instance state becomes Running and the status checks pass.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg Grocy Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens ports 22, 80, and 443 as described above.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type m5.large \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --block-device-mappings '[{"DeviceName":"/dev/sda1","Ebs":{"VolumeSize":20,"VolumeType":"gp3"}}]' \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=grocy-01}]'

The command prints a JSON document on success. Note the instance ID, then retrieve its public address once it is running with aws ec2 describe-instances --instance-ids <instance-id> --query "Reservations[].Instances[].PublicIpAddress" --output text.

Step 3: Connect and Retrieve Initial Credentials

Connect over SSH with the key pair you selected and the public IP address from step 2. The SSH login user depends on the operating system of the AMI variant you launched:

ssh -i /path/to/your-key.pem ubuntu@<public-ip>

The Grocy administrator password is generated on first boot and written to a root only file. Retrieve it with:

sudo cat /root/grocy-credentials.txt

The file lists the administrator user (admin), the generated password and the instance URL. Store the password somewhere safe and treat it as a secret.

Step 4: Sign In to Grocy

Open a web browser and browse to http://<instance-public-ip>/. You are taken to the Grocy sign-in page.

Sign in as the admin user with the password from /root/grocy-credentials.txt. After signing in you land on the Stock overview. Open the user menu at the top right and choose your own user to change the administrator password to one of your choosing from inside the application.

Step 5: Track Your Stock

The Stock overview is the heart of Grocy. It lists every product you have in stock, the amount on hand, the total stock value, and the next due date, with rows colour coded so that overdue and soon to expire products stand out. Use Purchase to book new stock in with a best before date and price, Consume to book stock out as you use it, and Inventory to correct the on hand amount after a stock take.

Create your products under Manage master data, where you also define quantity units, locations, product groups and shopping locations. Each product can carry a minimum stock amount so that Grocy can tell you when you are running low.

Step 6: Build a Shopping List

The Shopping list view collects everything you need to buy. Add items manually, or let Grocy populate the list automatically from the products that have fallen below their minimum stock amount. Each item carries a quantity and the list shows a running total value.

When you return from the shops, use Stock actions on the shopping list to book the purchased items straight into stock.

Step 7: Schedule Chores

The Chores overview turns recurring household tasks into a tracked schedule. Define a chore with a period (manually, daily, weekly, monthly or a custom number of days), then track each execution so that Grocy estimates the next due date and highlights overdue chores.

Grocy carries the same tracking model for Batteries (charge cycles) and Equipment (manuals and maintenance), and a Tasks module for one off jobs.

Step 8: Using the REST API

Grocy exposes a full REST API that mirrors the web interface. Create an API key from the user menu at the top right, under Manage API keys. Then call the API with the key in the GROCY-API-KEY header. For example, to list the current stock:

curl -s -H "GROCY-API-KEY: <your-token>" http://<public-ip>/api/stock

The interactive API documentation is available in the application under the same menu, generated from the bundled OpenAPI specification.

Step 9: Verify the Service on the Instance

To confirm the stack is healthy from the shell, check the services and the listening port:

systemctl is-active nginx php8.3-fpm

Both units report active. Confirm nginx is serving on port 80:

sudo ss -tlnp | grep ':80 '

Confirm the installed Grocy version and that the data volume is mounted:

cat /var/www/grocy/version.json
df -h /var/lib/grocy

The version file reports Grocy 4.5.0, and /var/lib/grocy is a dedicated ext4 volume holding the SQLite database (grocy.db), the configuration and file storage.

Step 10: Enable HTTPS with Let's Encrypt

For production use you should put Grocy behind HTTPS. Point a DNS A record at the instance's public IP, ensure inbound port 443 is open in the security group, then install Certbot and obtain a certificate. Replace your-domain.example.com with your fully qualified domain name and run the following on the instance:

sudo snap install --classic certbot
sudo ln -sf /snap/bin/certbot /usr/bin/certbot

Then request and install a certificate for your domain with the nginx plugin, following the interactive prompts to enter your email address and agree to the terms. Use the command sudo certbot --nginx -d your-domain.example.com. Certbot edits the nginx site to serve TLS and installs a renewal timer. After enabling HTTPS, browse to https://your-domain.example.com/.

Backup and Maintenance

All of your Grocy data lives under /var/lib/grocy, principally the SQLite database grocy.db. To back it up, stop the web stack briefly to ensure a consistent copy, archive the directory, and start the stack again:

sudo systemctl stop nginx php8.3-fpm
sudo tar czf /tmp/grocy-backup.tar.gz -C /var/lib grocy
sudo systemctl start nginx php8.3-fpm

Copy the resulting archive to durable storage such as Amazon S3. Because the data volume is a separate EBS volume, you can also take EBS snapshots of it on a schedule for point in time recovery, and resize it independently of the operating system disk as your household data grows.

Keep the operating system patched with sudo apt-get update && sudo apt-get -y upgrade. To move to a newer Grocy release, follow the upgrade notes in the official Grocy documentation, preserving the /var/lib/grocy data directory.

Support

This image is published and supported by cloudimg. Support covers Grocy deployment, upgrades, REST API integration, performance tuning, and storage administration, 24/7 by email and chat. For questions about using Grocy itself, the official Grocy documentation and community are excellent resources.

All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.