Self-host

When you choose to self-host, the responsibility for updates, maintenance, and merging future enhancements rests entirely with you.

We highly recommend the Cloud version, unless you have hard requirements to manage your own infrastructure.

Minimum System Requirements

Resource	Minimum	Recommended
CPU	2 vCPU	4 vCPU
RAM	2 GB	4 GB
Disk	20 GB	40 GB

Software requirements:

Docker 24+ and Docker Compose v2+
A domain with DNS A record pointing to your server
Ports 80 and 443 open (for web traffic and TLS)

Quick Start

The fastest way to get Sweetr running is with our deploy script. It will guide you through the setup, including creating a GitHub App with the correct permissions.

curl -fsSL https://raw.githubusercontent.com/sweetr-dev/sweetr.dev/main/bin/deploy | bash

The script will:

Check that Docker and Docker Compose are installed
Ask for your domain and GitHub organization handle
Generate a pre-filled URL to create a GitHub App with all required permissions
Collect your GitHub App credentials
Optionally configure Slack integration
Generate docker-compose.yml and .env files
Start the stack

To install a specific version, set the SWEETR_TAG environment variable:

curl -fsSL https://raw.githubusercontent.com/sweetr-dev/sweetr.dev/1.2.0/bin/deploy | SWEETR_TAG=1.2.0 bash

Manual Setup

If you prefer to set things up manually, follow the steps below.

Prerequisites

Create a GitHub Application

You’ll need to create a GitHub application.Use our pre-filled link to speed this up — replace YOUR_DOMAIN with your actual domain after opening it.After opening the link, you must also:

Uncheck “Expire user authorization tokens”
Generate and set a Webhook Secret
Submit the form, then generate a Client Secret
Generate a Private Key (this downloads a .pem file)

Create the app under your organization account (not your personal account) so it can be installed on the organization directly. Use https://github.com/organizations/YOUR_ORG/settings/apps/new as the base URL.

Manual setup (without pre-filled link)

General
Permissions & events

Generate a Client Secret
Callback URL: https://your-domain.com/github/callback
Uncheck “Expire user authorization tokens”
Check “Request user authorization (OAuth) during installation”
Webhook
- Check “Active”
- Webhook URL: https://your-domain.com/api/github/webhook
- Generate and set a Webhook Secret
SSL verification
- Check “Enable SSL verification”
Generate a Private Key

Create a Slack App (Optional)

Create a Slack app at https://api.slack.com/apps/new:

OAuth & Permissions
Event Subscriptions

Create a Redirect URL: https://your-domain.com/settings/integrations/slack
Add the following Bot Token Scopes:
- app_mentions:read
- channels:join
- channels:read
- chat:write
- groups:read
- im:read
- im:write
- mpim:read
- reactions:read
- users.profile:read
- users:read
- users:read.email

Set “Enable Events” to ON
Change the “Request URL” to https://your-domain.com/api/slack/webhook

Create a Caddyfile

Create a Caddyfile for the reverse proxy. Caddy automatically provisions and renews HTTPS certificates via Let’s Encrypt.

your-domain.com {
    @api path /api /api/*
    handle @api {
        uri strip_prefix /api
        reverse_proxy api:8000
    }
    handle {
        reverse_proxy web:80
    }
}

A public domain is required — GitHub cannot deliver webhooks to localhost. For local development, use a tunnel like Cloudflare Tunnel or ngrok and use the tunnel URL as your domain.

Create docker-compose.yml

Create a docker-compose.yml file:

services:
  caddy:
    image: caddy:2
    container_name: sweetr-caddy
    ports:
      - "80:80"
      - "443:443"
      - "443:443/udp"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - sweetr-caddy-data:/data
      - sweetr-caddy-config:/config
    restart: unless-stopped
    networks:
      - sweetr
    depends_on:
      - api
      - web

  api:
    image: sweetr/api:latest
    container_name: sweetr-api
    env_file: .env
    environment:
      - NODE_ENV=production
      - APP_ENV=production
      - APP_MODE=self-hosted
      - USE_SELF_SIGNED_SSL=false
    restart: unless-stopped
    networks:
      - sweetr
    depends_on:
      postgres:
        condition: service_healthy
      dragonfly:
        condition: service_healthy

  web:
    image: sweetr/web:latest
    container_name: sweetr-web
    environment:
      - API_ENDPOINT=${API_ENDPOINT}
      - AUTH_COOKIE_DOMAIN=${AUTH_COOKIE_DOMAIN}
      - GITHUB_APP=${GITHUB_APP}
      - SENTRY_DSN=${SENTRY_DSN:-}
      - APP_ENV=${APP_ENV:-production}
    restart: unless-stopped
    networks:
      - sweetr
    depends_on:
      - api

  postgres:
    image: postgres:16
    container_name: sweetr-postgres
    env_file: .env
    volumes:
      - sweetr-db:/var/lib/postgresql/data
    restart: unless-stopped
    networks:
      - sweetr
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

  dragonfly:
    image: docker.dragonflydb.io/dragonflydb/dragonfly
    container_name: sweetr-dragonfly
    command: ["--cluster_mode=emulated", "--lock_on_hashtags", "--proactor_threads=2"]
    ulimits:
      memlock: -1
    volumes:
      - sweetr-dragonfly:/data
    restart: unless-stopped
    networks:
      - sweetr
    healthcheck:
      test: ["CMD-SHELL", "redis-cli ping"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  sweetr-db:
  sweetr-dragonfly:
  sweetr-caddy-data:
  sweetr-caddy-config:

networks:
  sweetr:
    driver: bridge

Configure environment variables

Create a .env file. See the Environment Variables Reference below for all available options.

# Database
POSTGRES_USER=postgres
POSTGRES_PASSWORD=<generate-a-secure-password>
POSTGRES_DB=sweetr
DATABASE_URL=postgres://postgres:<POSTGRES_PASSWORD>@postgres:5432/sweetr

# API
PORT=8000
FRONTEND_URL=https://your-domain.com
JWT_SECRET=<generate-a-secure-random-string>
REDIS_CONNECTION_STRING=redis://dragonfly:6379

# GitHub App
GITHUB_APP_ID=<your-app-id>
GITHUB_CLIENT_ID=<your-client-id>
GITHUB_CLIENT_SECRET=<your-client-secret>
GITHUB_APP_HANDLE=<your-app-slug>
# Private key: replace newlines with \n and wrap in double quotes
GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nMIIE...\n-----END RSA PRIVATE KEY-----\n"
GITHUB_WEBHOOK_SECRET=<your-webhook-secret>

# Web
API_ENDPOINT=https://your-domain.com/api
AUTH_COOKIE_DOMAIN=your-domain.com
GITHUB_APP=<your-app-slug>

# Slack (optional)
SLACK_CLIENT_ID=
SLACK_CLIENT_SECRET=
SLACK_WEBHOOK_SECRET=

Start the stack

docker compose up -d

The API container will automatically run database migrations on startup.

Complete onboarding

After logging in, the initial data sync will begin. Follow the Onboarding Guide to review what was set up and configure your workspace.

Environment Variables Reference

API (`sweetr/api`)

Variable	Required	Default	Description
`DATABASE_URL`	Yes	—	PostgreSQL connection string
`REDIS_CONNECTION_STRING`	Yes	—	Redis/Dragonfly connection string
`JWT_SECRET`	Yes	—	Secret for signing JWT tokens
`FRONTEND_URL`	Yes	—	URL of the web application
`PORT`	No	`3000`	API server port
`GITHUB_APP_ID`	Yes	—	GitHub App ID
`GITHUB_CLIENT_ID`	Yes	—	GitHub OAuth Client ID
`GITHUB_CLIENT_SECRET`	Yes	—	GitHub OAuth Client Secret
`GITHUB_APP_HANDLE`	Yes	—	GitHub App slug (from the app URL)
`GITHUB_APP_PRIVATE_KEY`	Yes	—	GitHub App private key (PEM format)
`GITHUB_WEBHOOK_SECRET`	Yes	—	Secret for verifying GitHub webhooks
`GITHUB_OAUTH_REDIRECT_PATH`	No	`/github/callback`	OAuth redirect path
`APP_MODE`	No	`self-hosted`	`self-hosted` or `saas`
`NODE_ENV`	No	`production`	`development` or `production`
`APP_ENV`	No	`production`	`development`, `staging`, or `production`
`LOG_LEVEL`	No	`info`	`debug`, `info`, `warn`, or `error`
`USE_SELF_SIGNED_SSL`	No	`false`	Use self-signed SSL certificates
`BULLMQ_ENABLED`	No	`true`	Enable background job processing
`SLACK_CLIENT_ID`	No	`""`	Slack Client ID
`SLACK_CLIENT_SECRET`	No	`""`	Slack Client Secret
`SLACK_WEBHOOK_SECRET`	No	`""`	Slack webhook verification secret
`STRIPE_API_KEY`	No	`""`	Stripe API key (cloud billing only)
`STRIPE_WEBHOOK_SECRET`	No	`""`	Stripe webhook secret (cloud billing only)
`SENTRY_DSN`	No	`""`	Sentry DSN for error tracking
`LOG_DRAIN`	No	`console`	`console` or `logtail`
`LOGTAIL_TOKEN`	No	`""`	LogTail source token
`EMAIL_ENABLED`	No	`false`	Enable transactional emails
`RESEND_API_KEY`	No	`""`	Resend API key for emails
`BULLBOARD_PATH`	No	`""`	URL path to access BullBoard dashboard
`BULLBOARD_USERNAME`	No	`""`	BullBoard login username
`BULLBOARD_PASSWORD`	No	`""`	BullBoard login password
`CRON_GITHUB_RETRY_FAILED_WEBHOOKS_EVERY_MINUTES`	No	`30`	Retry interval for failed webhooks

Web (`sweetr/web`)

Variable	Required	Default	Description
`API_ENDPOINT`	Yes	—	Full URL to the API (e.g., `https://sweetr.example.com/api`)
`AUTH_COOKIE_DOMAIN`	Yes	—	Domain for auth cookies (e.g., `example.com`)
`GITHUB_APP`	Yes	—	GitHub App slug (same as `GITHUB_APP_HANDLE`)
`SENTRY_DSN`	No	`""`	Sentry DSN for frontend error tracking
`APP_ENV`	No	`production`	Environment name for Sentry

Upgrading

To upgrade to a new version:

cd sweetr
docker compose pull
docker compose up -d

Database migrations run automatically on API container startup. To pin a specific version instead of latest, edit the image tags in docker-compose.yml:

services:
  api:
    image: sweetr/api:1.2.0
  web:
    image: sweetr/web:1.2.0

Monitoring (Optional)

Sentry

Add to your API .env:

SENTRY_DSN=https://your-sentry-dsn

For frontend error tracking, also add to your .env:

SENTRY_DSN=https://your-frontend-sentry-dsn

The web container reads this as the SENTRY_DSN environment variable.

LogTail

LOG_DRAIN=logtail
LOGTAIL_TOKEN=your-logtail-token

BullBoard (Job Queue Dashboard)

To enable the BullBoard dashboard for monitoring background jobs:

BULLBOARD_PATH=/bullboard
BULLBOARD_USERNAME=admin
BULLBOARD_PASSWORD=<secure-password>

Access it at https://your-domain.com/api/bullboard.

Troubleshooting

API fails to start

Check the container logs:

docker compose logs api

Common causes:

Database connection failed: Ensure Postgres is healthy with docker compose ps. The API waits for migrations to run on startup.
Missing environment variables: The API will log which required variables are missing.
Redis connection failed: Ensure Dragonfly is healthy. Check that REDIS_CONNECTION_STRING uses the Docker service name (e.g., redis://dragonfly:6379).

Web app shows blank page

Check the browser console for errors. Common causes:

API_ENDPOINT is wrong: Make sure it’s the full URL reachable from the browser (not an internal Docker hostname).
CORS errors: Ensure FRONTEND_URL on the API matches the URL you’re accessing the web app from.

Database migration errors

If migrations fail on startup, check the API logs. You may need to connect to Postgres directly:

docker compose exec postgres psql -U postgres -d sweetr

Port conflicts

If port 80 or 443 is already in use, either stop the conflicting service or change the Caddy port mappings in docker-compose.yml:

caddy:
  ports:
    - "8080:8080" # Change host port

Then update your Caddyfile to match (e.g., :8080 {) and adjust FRONTEND_URL and API_ENDPOINT in .env accordingly.

Welcome

Metrics & Insights

Automations

Platform

About Us

Minimum System Requirements

Quick Start

Manual Setup

Prerequisites

Repository permissions

Organization permissions

Account permissions

Environment Variables Reference

API (`sweetr/api`)

Web (`sweetr/web`)

Upgrading

Monitoring (Optional)

Sentry

LogTail

BullBoard (Job Queue Dashboard)

Troubleshooting

API fails to start

Web app shows blank page

Database migration errors

Port conflicts

​Minimum System Requirements

​Quick Start

​Manual Setup

​Prerequisites

​Repository permissions

​Organization permissions

​Account permissions

​Subscribe to events

​Environment Variables Reference

​API (sweetr/api)

​Web (sweetr/web)

​Upgrading

​Monitoring (Optional)

​Sentry

​LogTail

​BullBoard (Job Queue Dashboard)

​Troubleshooting

​API fails to start

​Web app shows blank page

​Database migration errors

​Port conflicts

Minimum System Requirements

Quick Start

Manual Setup

Prerequisites

Repository permissions

Organization permissions

Account permissions

Subscribe to events

Environment Variables Reference

API (`sweetr/api`)

Web (`sweetr/web`)

Upgrading

Monitoring (Optional)

Sentry

LogTail

BullBoard (Job Queue Dashboard)

Troubleshooting

API fails to start

Web app shows blank page

Database migration errors

Port conflicts