> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usecompiler.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Heroku

> Deploy Compiler to Heroku dynos using container-based deployment.

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](/deployment/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:

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

## Setup

<Steps>
  <Step title="Create a wrapper repository">
    Create a new repository with the following `heroku.yml`:

    ```yaml heroku.yml theme={null}
    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 Dockerfile theme={null}
    FROM ghcr.io/usecompiler/compiler:main
    ```
  </Step>

  <Step title="Create the Heroku app">
    ```bash theme={null}
    heroku create your-app-name
    heroku stack:set container -a your-app-name
    ```
  </Step>

  <Step title="Add Heroku Postgres">
    ```bash theme={null}
    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:

    ```bash theme={null}
    heroku config:set DATABASE_SSL=true -a your-app-name
    ```
  </Step>

  <Step title="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.

    ```bash theme={null}
    heroku addons:create heroku-redis:mini -a your-app-name
    ```
  </Step>

  <Step title="Configure environment variables">
    ```bash theme={null}
    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
    ```
  </Step>

  <Step title="Deploy">
    ```bash theme={null}
    git push heroku main
    ```
  </Step>
</Steps>

## 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:

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

## Performance considerations

<Note>
  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.
</Note>

## Updating

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

```bash theme={null}
git pull
git push heroku main
```

Or rebuild with the latest base image:

```bash theme={null}
heroku container:push web -a your-app-name
heroku container:release web -a your-app-name
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.