Heroku

Deploy Compiler to Heroku using container-based deployment. This guide covers dynos with ephemeral storage, where repositories are fetched on demand. For Kubernetes, ECS or another platform, see Other platforms.

Prerequisites

A Heroku account with container registry access
The Heroku CLI installed

How it works

Heroku dynos have ephemeral filesystems: any files written to disk are lost when the dyno restarts. This deployment configures Compiler to:

Store repository metadata in Heroku Postgres (persistent)
Clone repositories on demand to /tmp/repos (ephemeral)
Automatically re-clone missing repositories when needed

Setup

Create a wrapper repository

Create a new repository with the following heroku.yml:

heroku.yml

build:
  docker:
    web: Dockerfile
release:
  image: web
  command:
    - npx drizzle-kit migrate
run:
  web: npm run start

And a Dockerfile that pulls the Compiler image:

Dockerfile

FROM ghcr.io/usecompiler/compiler:main

Create the Heroku app

heroku create your-app-name
heroku stack:set container -a your-app-name

Add Heroku Postgres

heroku addons:create heroku-postgresql:essential-0 -a your-app-name

This sets the DATABASE_URL environment variable automatically. Heroku Postgres requires SSL, so enable it:

heroku config:set DATABASE_SSL=true -a your-app-name

Add Redis

Redis is required: the app refuses to start without REDIS_URL. It holds resumable stream state so a client can reconnect to an in-progress response.

heroku addons:create heroku-redis:mini -a your-app-name

Configure environment variables

heroku config:set TOKEN_ENCRYPTION_KEY=$(node -e "console.log(require('crypto').randomBytes(32).toString('hex'))") -a your-app-name
heroku config:set REPOS_DIR=/tmp/repos -a your-app-name

Deploy

git push heroku main

Environment variables

Variable	Description
`DATABASE_URL`	Set automatically by the Heroku Postgres add-on
`DATABASE_SSL`	Set to `true` for Heroku Postgres (appends `?sslmode=require`)
`TOKEN_ENCRYPTION_KEY`	32-byte hex string for encrypting tokens
`REPOS_DIR`	Set to `/tmp/repos` for ephemeral storage
`REDIS_URL`	Set automatically by the Heroku Key-Value Store add-on

The AI provider (Anthropic API or AWS Bedrock) and GitHub App credentials are configured through the onboarding flow, not as environment variables.

Behavior on dyno restart

When a Heroku dyno restarts:

All cloned repositories in /tmp/repos are lost
Repository metadata remains in Heroku Postgres
The server starts immediately
When a user loads the app, a sync gate detects missing repositories and triggers re-cloning
The user sees a loading screen until their repositories are ready

Performance considerations

On eco dynos, the app sleeps after 30 minutes of inactivity. Waking up triggers a full restart, so repositories are re-cloned on the first page load.

Updating

If the upstream Dockerfile changed, pull it first, then push:

git pull
git push heroku main

Or rebuild with the latest base image:

heroku container:push web -a your-app-name
heroku container:release web -a your-app-name

Getting started

Deployment

Configuration

Reference

Prerequisites

How it works

Setup

Environment variables

Behavior on dyno restart

Performance considerations

Updating

​Prerequisites

​How it works

​Setup

​Environment variables

​Behavior on dyno restart

​Performance considerations

​Updating

Prerequisites

How it works

Setup

Environment variables

Behavior on dyno restart

Performance considerations

Updating