Backend Setup

Deploy the Grovs backend with Docker Compose — includes the API server, database, Redis, and background workers.

The Grovs backend is a Ruby on Rails application that handles API requests, link redirects, SDK communication, and background processing. This guide walks you through deploying it with Docker Compose.

Prerequisites

Docker and Docker Compose installed
A domain name with DNS access (for configuring subdomains)

Clone the repository

Bash

git clone https://github.com/grovs-io/backend.git
cd backend

Create the environment file

Copy the example environment file:

Bash

cp .env.example .env

Generate encryption keys

Rails requires encryption keys for securing sensitive data. Generate them with:

Bash

docker compose run --rm web bin/rails db:encryption:init

This outputs three keys. Add them to your .env file:

Bash

ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY=generated_key_here
ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY=generated_key_here
ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT=generated_key_here

Configure your domain

Set the host variables in your .env file to match your domain:

Bash

# Backend
SERVER_HOST_PROTOCOL=https://
SERVER_HOST=yourdomain.com
 
# Dashboard (where the frontend will be hosted)
REACT_HOST_PROTOCOL=https://
REACT_HOST=app.yourdomain.com

The backend uses subdomain routing. Make sure you configure DNS records for api., sdk., go., and preview. subdomains — all pointing to the same server running the backend.

Start the services

Build and start all containers:

Bash

docker compose up --build

This starts:

PostgreSQL 16 — database
Redis 6 — cache and job queues
Rails web server — on port 8765
5 Sidekiq workers — background job processing

Set up the database

In a new terminal, create and seed the database:

Bash

docker compose exec web bundle exec rails db:create db:migrate db:seed

The seed process creates:

A default OAuth application (used by the dashboard to authenticate)
A default domain and project configuration

Retrieve the OAuth credentials

The dashboard needs OAuth credentials to connect to the backend. Open a Rails console to retrieve them:

Bash

docker compose exec web bundle exec rails console

Then run:

Ruby

app = Doorkeeper::Application.first
puts "Client ID: #{app.uid}"
puts "Client Secret: #{app.secret}"

Save these values — you'll need them when setting up the dashboard.

Verify the deployment

Once the services are running, check that the backend is healthy:

Bash

curl http://localhost:8765/up

You should receive a 200 OK response.

Environment variables reference

Required

Variable	Description	Example
`ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY`	Primary encryption key	Generated in step 3
`ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY`	Deterministic encryption key	Generated in step 3
`ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT`	Key derivation salt	Generated in step 3
`SERVER_HOST_PROTOCOL`	Backend protocol	`https://`
`SERVER_HOST`	Backend domain	`yourdomain.com`
`REACT_HOST_PROTOCOL`	Dashboard protocol	`https://`
`REACT_HOST`	Dashboard domain	`app.yourdomain.com`
`REDIS_URL`	Redis connection URL	`redis://redis:6379/0`

Optional integrations

Variable	Description
`AWS_S3_KEY_ID`, `AWS_S3_ACCESS_KEY`, `AWS_S3_REGION`, `AWS_S3_BUCKET`	File storage via AWS S3
`SENDGRID_API_KEY`	Transactional emails via SendGrid
`STRIPE_API_KEY`, `STRIPE_STANDARD_PRICE_ID`, `STRIPE_WEBHOOK_SECRET`	Billing via Stripe
`GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`	Google SSO login
`MICROSOFT_CLIENT_ID`, `MICROSOFT_CLIENT_SECRET`	Microsoft SSO login
`OTEL_EXPORTER`, `OTEL_SERVICE_NAME`, `OTEL_EXPORTER_OTLP_ENDPOINT`	OpenTelemetry observability

Background workers

The backend runs five specialized Sidekiq processes:

Worker	Concurrency	Purpose
`scheduler`	1	Scheduled/cron jobs
`worker`	20	SDK event ingestion
`batch`	3	Batch event processing
`device_updates`	3	Device metadata updates
`maintenance`	5	Backfills and housekeeping

All workers are started automatically by Docker Compose.

DNS configuration

Point the following subdomains to the server running the backend:

Subdomain	Purpose
`api.yourdomain.com`	Dashboard API
`sdk.yourdomain.com`	Mobile SDK endpoints
`go.yourdomain.com`	Short link redirects
`preview.yourdomain.com`	Link preview pages

If you use a reverse proxy (nginx, Caddy, Traefik), make sure it forwards all four subdomains to port 8765 on the backend container.

Production deployment with Kamal

For production deployments, Grovs supports Kamal — a zero-downtime deployment tool from the Rails team:

Bash

cp config/deploy.yml.example config/deploy.yml
# Edit config/deploy.yml with your server details
bundle exec kamal setup
bundle exec kamal deploy

Next step

Set up the dashboard →