AWS

Create a single EC2 server for Grovs with the CloudFormation template.

When to use

You want Grovs on one EC2 instance in your AWS account. The CloudFormation template creates a dedicated VPC, public subnet, security group, static IPv4 address and one Ubuntu 24.04 EC2 instance. Grovs runs there with Docker Compose. PostgreSQL, Redis, ClickHouse and uploads use persistent Docker volumes on its encrypted EBS disk. This is a single-server deployment, not an HA cluster.

Prerequisites

Requirement	Notes
AWS permissions	Create the template's resources, create and pass IAM roles, and read the public Ubuntu AMI parameter from SSM
Budget	You pay for the instance, EBS storage and public IPv4. The default is a `t3.xlarge` with 100 GiB of gp3 storage. Check regional pricing first.
A domain you control	For the DNS records

1. Prepare DNS and firewall

The template creates the security group. No SSH port is open publicly: you connect through Session Manager. Point the DNS records at the static IP from the stack Outputs after step 2.

2. Create the server

Upload the template

Download deploy/aws/cloudformation.yaml from the repository. In your region, open CloudFormation → Create stack → With new resources, select Upload a template file and upload it.

Fill in the parameters

Set AppDomain, AdminEmail and GrovsVersion. For GrovsVersion, use the version on the latest completed release, replacing any older template default. It selects matching backend and dashboard images from GHCR.

Choose the stack files

Keep StackRef=main or pin a reviewed commit that contains the deployment files. StackRef selects deployment files independently of the image version, because application release tags can predate the cloud scripts.

Create the stack

Review the resources and acknowledge IAM creation. The instance role grants Session Manager connectivity. Create the stack, then copy IpAddress and InstanceId from Outputs.

3. Install Grovs

CloudFormation completion means the VM exists. Application setup continues inside it: package installation, image pulls and migrations take a while before the dashboard is up. Point the DNS records at IpAddress.

4. Deploy and verify

In EC2 → Instances → Connect → Session Manager, open the instance and run:

Bash

sudo systemctl status grovs --no-pager
sudo tail -100 /var/log/cloud-init-output.log
sudo cat /opt/grovs/.env

Sign in at https://dashboard.<AppDomain> with BOOTSTRAP_ADMIN_EMAIL and BOOTSTRAP_ADMIN_PASSWORD. Setup writes secrets to root-readable files; they are not in CloudFormation parameters or Outputs. Finish with the checks in Verify.

Upgrades

The checkout and .env live in /opt/grovs, and grovs.service starts the stack on boot. Run sudo -i, then cd /opt/grovs for the usual Compose commands. Back up PostgreSQL, ClickHouse, uploads and .env, then follow Upgrades. Updating the CloudFormation parameters is not a supported in-place application upgrade.

Gotchas

If Session Manager is unavailable, check the instance profile, outbound network access and SSM agent status. The operator also needs permission to start an SSM session. See AWS Session Manager prerequisites.
Deleting the stack terminates the VM and releases its public IP. The root EBS volume is retained (DeleteOnTermination: false), so its data survives but keeps incurring storage charges. Identify and snapshot it before deletion; deleting retained volumes is a separate, irreversible operation. A retained disk is not a database backup.

Last updated 2026-10-26

Was this page helpful?