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

# Move from Heroku to floo

> Move a Heroku app, its config vars, jobs, database, and domain to floo.

Move a Heroku app to floo with a `Dockerfile` and `floo.app.toml`. Map its processes and scheduled jobs, import its config vars, restore its database, and move its domain.

Requires the app's code in a GitHub repository, the [floo CLI](https://getfloo.com/docs/guides/install.md) signed in with `floo auth login`, and the [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli-commands) signed in to the app. Without a GitHub repository, `floo deploy --hosted` deploys from a copy floo hosts; see [Deploy without a GitHub repository](https://getfloo.com/docs/deploy/without-github.md).

In its [March 2026 update](https://www.heroku.com/blog/march-2026-update/), Heroku said it has moved to a sustaining engineering model.

## What maps to what

| On Heroku | On floo |
| - | - |
| Buildpacks detect the language and build the app | A `Dockerfile` that serves on `0.0.0.0:$PORT` ([Dockerfiles](https://getfloo.com/docs/guides/dockerfiles.md)) |
| `web:` in the `Procfile` | `[services.web]` with `type = "web"` |
| `worker:` and other process types | `[services.<name>]` with `type = "worker"` and `command` |
| `release:` (release phase) | `migrate_command` on the service; a failure stops the deploy ([migrations](https://getfloo.com/docs/guides/postgres.md#schema-portability-across-dev-and-prod)) |
| Heroku Scheduler | `[cron.<name>]` in `floo.app.toml` ([cron jobs](https://getfloo.com/docs/guides/cron-jobs.md)) |
| Config vars | `floo env` with `--env dev` or `--env prod` ([env vars](https://getfloo.com/docs/guides/environment-variables.md)) |
| Heroku Postgres | `[managed.default]` with `type = "postgres"`, `DATABASE_URL` injected ([Postgres](https://getfloo.com/docs/guides/postgres.md)) |
| Heroku Key-Value Store | `[managed.cache]` with `type = "redis"`, `REDIS_URL_CACHE` injected ([Redis](https://getfloo.com/docs/guides/redis.md)) |
| Pipeline staging and production apps | One app with dev and prod: a push deploys dev, a GitHub release publishes prod ([environments](https://getfloo.com/docs/guides/environments.md#the-flow)) |
| Review apps | A preview per pull request once `[github] preview_environments = true` ([previews](https://getfloo.com/docs/guides/preview-environments.md)) |
| `heroku rollback` | `floo rollback` ([rollbacks](https://getfloo.com/docs/guides/rollbacks.md)) |
| `heroku domains:add` | `[domains."<host>"]` in `floo.app.toml` ([custom domains](https://getfloo.com/docs/guides/custom-domains.md)) |

## 1. Add a Dockerfile

floo builds every service from a `Dockerfile`. Start from a [recommended Dockerfile](https://getfloo.com/docs/guides/dockerfiles.md#recommended-dockerfiles) or the stack guide for [Rails](https://getfloo.com/docs/build/rails.md), [Django](https://getfloo.com/docs/build/django.md), [FastAPI](https://getfloo.com/docs/build/fastapi.md), [Express](https://getfloo.com/docs/build/express.md), or [Next.js](https://getfloo.com/docs/build/nextjs.md). Install the same runtime version the buildpack used, and make the final stage start the `web` command from the `Procfile`.

Add a `.dockerignore` so local dependency folders and `.env*` files stay out of the build context.

## 2. Map the Procfile

A Python app with a worker, a release command, and a nightly Heroku Scheduler job:

```text Procfile theme={null}
web: gunicorn app.main:app --bind 0.0.0.0:$PORT
worker: python -m app.worker
release: alembic upgrade head
```

Run `floo init my-app`, then edit `floo.app.toml` to match the processes and jobs:

```toml floo.app.toml theme={null}
[app]
name = "my-app"

[services.web]
type = "web"
path = "."
port = 8000
ingress = "public"
command = "gunicorn app.main:app --bind 0.0.0.0:$PORT"

[services.worker]
type = "worker"
path = "."
command = "python -m app.worker"

[managed.default]
type = "postgres"

[cron.nightly-report]
schedule = "0 3 * * *"
command = "python -m app.nightly_report"
service = "web"

[domains."app.example.com"]
service = "web"
```

`command` runs as `sh -c`, so `$PORT` expands. The worker shares the web service's image, so it needs its own `command`. Add `migrate_command = "alembic upgrade head"` to `[services.web]` after the data is in ([step 5](#5-move-the-database)). Set `access_mode = "accounts"` under `[app]` if only invited people should reach the app ([App sign-in](https://getfloo.com/docs/guides/app-auth.md)).

Each Heroku Scheduler job becomes a `[cron.<name>]` block with the job's command. Scheduler's three intervals are `*/10 * * * *` (every 10 minutes), `0 * * * *` (hourly), and a daily expression such as `0 3 * * *`. floo reads schedules in UTC, runs a job for up to 1,500 seconds, and does not retry it.

```bash theme={null}
floo deploy --preflight
```

## 3. Import config vars

`heroku config --shell` prints config vars in shell format. Exclude variables for Heroku's add-ons; floo injects `DATABASE_URL`, `PG*`, and Redis URLs for its managed services. Add `.env.heroku` and `.env.import` to `.gitignore` before creating them:

```bash theme={null}
heroku config --shell --app my-heroku-app > .env.heroku
grep -v -E '^(DATABASE_URL|HEROKU_|REDIS_URL|REDIS_TLS_URL)' .env.heroku > .env.import
```

Keep both files outside git. Import `.env.import` after the first deploy creates the app. If the app reads `REDIS_URL`, point it at `REDIS_URL_CACHE`.

## 4. Deploy to dev

```bash theme={null}
git add . && git commit -m "chore: move to floo"
floo deploy
```

The first `floo deploy` stops with one link if floo can't read the repository yet. Install the floo GitHub App on the repository's owner, then run `floo deploy` again. It waits until the dev deploy is live, and `floo status --app my-app --json` shows why if it is not. The first build or startup can fail if it needs variables that have not been imported yet. Once the app exists, import them and rebuild:

```bash theme={null}
floo env import .env.import --app my-app
floo env list --app my-app
floo deploy --rebuild --app my-app
```

New keys are secrets except for build-time prefixes. Review the values before importing them to dev; use test credentials for services that must not receive dev traffic. Keep `.env.import` until you have imported the prod values in step 6; then delete both files.

## 5. Move the database

The dev deploy creates the managed database. Capture a Heroku Postgres backup, download it, convert it to SQL, and load it into floo's dev database with `psql`:

```bash theme={null}
heroku pg:backups:capture --app my-heroku-app
heroku pg:backups:download --app my-heroku-app
pg_restore --clean --if-exists --no-owner --no-privileges --file app.sql latest.dump
floo run --service web -- psql --single-transaction --set ON_ERROR_STOP=1 --file app.sql
floo db query --app my-app "SELECT COUNT(*) FROM information_schema.tables WHERE table_schema = 'public'"
```

Heroku backups use `pg_dump`'s custom format, and Heroku's own restore example names the file `latest.dump`. `floo run` sets the `PG*` variables for the dev database, so `psql` connects with no connection string. If the load stops on the `heroku_ext` schema, create it first, as [Heroku's docs](https://devcenter.heroku.com/articles/heroku-postgres-import-export) advise:

```bash theme={null}
floo run --service web -- psql --command "CREATE SCHEMA heroku_ext"
```

Then add `migrate_command` to `[services.web]` and push. The dump carries your migration tool's history table, so the first run finds nothing to apply.

`floo run` opens a dev session, so these commands load dev. Prod gets its own database with the first release ([step 6](#6-move-the-domain)). After that release, load the same file into prod with prod's `DATABASE_URL`:

```bash theme={null}
psql --single-transaction --set ON_ERROR_STOP=1 --file app.sql "$(floo env get DATABASE_URL --app my-app --env prod --reveal-secrets)"
floo db query --app my-app --env prod "SELECT COUNT(*) FROM information_schema.tables WHERE table_schema = 'public'"
```

`floo env get` needs a write-scoped floo API key, and each read is audited. `--reveal-secrets` lets it print a connection string, and the command substitution keeps the URL out of your shell history. `--clean --if-exists` in the converted file drops each table before recreating it, so the load also works after the release's `migrate_command` has created the schema. To export a managed database, see [`floo db dump`](https://getfloo.com/docs/cli/database#dump).

## 6. Move the domain

A custom domain serves prod. Replace `owner/repo` with your GitHub repository and publish the first release:

```bash theme={null}
gh release create v1 --repo owner/repo
floo env import .env.import --app my-app --env prod
gh release create v2 --repo owner/repo
floo domains show app.example.com --app my-app
```

Prod env vars apply with the next release, which is why the import sits between two releases. After the first release creates the prod database, restore and verify its data before changing the traffic record. Delete `.env.heroku` and `.env.import` after verifying the prod import. `floo domains show` prints two records:

| Purpose | Type | Name | Target |
| - | - | - | - |
| Certificate | CNAME | `_acme-challenge.app.example.com` | The target floo prints |
| Traffic | CNAME | `app.example.com` | `edge.getfloo.com` |

Publish the certificate record first; it does not change where traffic goes. Then replace the record that points at the Heroku DNS target (the `<name>.herokudns.com` value `heroku domains --app my-heroku-app` lists, per [Heroku's custom domains article](https://devcenter.heroku.com/articles/custom-domains)) with the floo one. For an apex such as `example.com`, use an `ALIAS` or `ANAME` to `edge.getfloo.com`, or an `A` record to `34.117.26.37`.

```bash theme={null}
floo domains watch app.example.com --app my-app
```

Keep the Heroku app until the domain is `active`. Pointing the traffic record back at Heroku is the move's rollback.

## Roll back on floo

Choose a deploy ID from the list, check its environment, and replace `DEPLOY_ID`:

```bash theme={null}
floo deploys --app my-app --env prod
floo rollback my-app DEPLOY_ID
```

`heroku rollback` restores the slug and its config vars. `floo rollback` re-points traffic at an earlier image only: env vars keep their current values, and `migrate_command` does not run. See [Releases and rollbacks](https://getfloo.com/docs/guides/rollbacks.md).

## Review apps and pipelines

Heroku creates a review app for each pull request once review apps are on. floo previews are off until you turn them on; each pull request then gets its own URL and its own Postgres branch:

```toml partial theme={null}
[github]
preview_environments = true
preview_ttl_hours = 72
```

A Heroku pipeline promotes a staging app's build to a production app. On floo, one app has both environments: a push deploys dev, and `gh release create` publishes that commit to prod. See [Preview environments](https://getfloo.com/docs/guides/preview-environments.md) and [Production environments](https://getfloo.com/docs/guides/environments.md).

## Agent prompt

Paste into your agent from the repository root. Replace `my-app`, `my-heroku-app`, and `<owner/repo>`.

```text theme={null}
Move this app from Heroku to floo. floo app name: my-app. Heroku app: my-heroku-app. Read https://getfloo.com/docs/migrate/from-heroku.md first.
1. Confirm the floo org with `floo orgs list`. If the org has no plan, have me run `floo billing upgrade`.
2. Add a Dockerfile from https://getfloo.com/docs/guides/dockerfiles.md for this app's language, with the runtime version the buildpack used, and a .dockerignore that excludes dependency folders and .env*. The final stage starts the Procfile's web command and binds 0.0.0.0:$PORT.
3. Run `floo init my-app`. In floo.app.toml, map each Procfile process: web to [services.web] with type = "web" and command set to the web line; every other process to [services.<name>] with type = "worker" and its command. Add [managed.default] with type = "postgres" if the app uses Heroku Postgres. Do not add migrate_command yet.
4. Ask me whether the app uses Heroku Scheduler. If it does, ask me for each job's command and interval, then add a [cron.<name>] block for each with the same command and service = "web". Schedules are UTC.
5. Ask me whether the app is for invited people only; if so, set access_mode = "accounts" under [app].
6. Add .env.heroku and .env.import to .gitignore. Run `heroku config --shell --app my-heroku-app > .env.heroku`. Write every line that does not start with DATABASE_URL, HEROKU_, REDIS_URL or REDIS_TLS_URL to .env.import. Never print the values or commit either file.
7. Commit with git, then run `floo deploy --preflight --json` and fix every error. Commit any resulting changes.
8. Run `floo deploy --json`. If it stops with a GitHub setup link, give me the link and wait for me to install the floo GitHub App, then run it again. Once the app exists, import .env.import with `floo env import .env.import --app my-app` and run `floo deploy --rebuild --app my-app`. Keep the files for the prod import, then delete them.
9. If the app has a database, run `heroku pg:backups:capture --app my-heroku-app`, `heroku pg:backups:download --app my-heroku-app`, `pg_restore --clean --if-exists --no-owner --no-privileges --file app.sql latest.dump`, then `floo run --service web -- psql --single-transaction --set ON_ERROR_STOP=1 --file app.sql`. Compare each table's row count with Heroku.
10. Set the release command from the Procfile as migrate_command on [services.web], commit, and push.
11. Run each job with `floo cron run JOB_NAME --app my-app` and check `floo logs query --app my-app --cron JOB_NAME`, replacing JOB_NAME with the job name.
12. Report the dev URL and `floo status --app my-app --json`. Stop there: I publish the release and change DNS.
```

## Where Heroku is stronger

As of November 9, 2026, from Heroku's documentation:

* **No Dockerfile.** [Buildpacks](https://devcenter.heroku.com/articles/buildpacks) detect the language and build the app with minimal configuration. floo builds from a Dockerfile you keep in the repository.
* **One-off dynos in the cloud.** [`heroku run`](https://devcenter.heroku.com/articles/one-off-dynos) starts a dyno next to the app's other dynos. `floo run` runs the command on your machine with the dev env vars.
* **Rollback includes config.** [`heroku rollback`](https://devcenter.heroku.com/articles/releases) restores the build and its config vars together. `floo rollback` restores the image only.
* **Postgres extras.** Standard-tier databases can add [followers](https://devcenter.heroku.com/articles/heroku-postgres-ha) for read scaling, and [Dataclips](https://devcenter.heroku.com/articles/dataclips) share query results as links. floo offers neither.
* **Review apps by default.** With review apps on, Heroku [creates one](https://devcenter.heroku.com/articles/github-integration-review-apps) as soon as a pull request opens. floo previews are opt-in per app or per pull request.

## What it costs

One small full-stack app, priced as of November 9, 2026:

* One web service with light traffic.
* A small Postgres database, about 1 GB.
* Sign-in so about 5 named people can use the app, and nobody else.
* One job that runs once a day.
* floo's numbers are the personal-app estimate on [getfloo.com/pricing](https://getfloo.com/pricing): "a default-size service (1 vCPU, 0.5 GiB) busy about an hour a day, a 1 GiB database and light traffic. Builds and logs are extra."

Heroku's [SSO](https://devcenter.heroku.com/articles/sso-for-heroku) covers signing in to Heroku's dashboard and CLI, not an app's visitors, so on Heroku the app's own code handles the 5 people's sign-in in every row.

| Setup | Per month | What it includes |
| - | - | - |
| Heroku Eco + Essential-0 | \$10 | [Eco](https://devcenter.heroku.com/articles/eco-dyno-hours) is $5 for 1,000 dyno hours shared by the account's Eco dynos; a web dyno sleeps after 30 minutes without traffic. Only personal apps, not apps in a Heroku Team, can use Eco. [Essential-0](https://www.heroku.com/pricing) is $5 with 1 GB of disk. |
| Heroku Basic + Essential-0 | \$12 | Basic is \$7 per dyno ([pricing](https://www.heroku.com/pricing)), one dyno per process type ([dyno tiers](https://devcenter.heroku.com/articles/dyno-tiers)). |
| Heroku Standard-1X + Essential-0 | \$30 | Standard-1X is \$25 per dyno ([pricing](https://www.heroku.com/pricing)). |
| Heroku Scheduler, any row | Dyno time | The add-on is [free](https://elements.heroku.com/addons/scheduler); each run is a one-off dyno that [counts toward dyno usage](https://devcenter.heroku.com/articles/scheduler). |
| floo Starter, scales to zero | \$10 | The $4 plan includes 4 credits; the other $6 comes from extra credits, bought $10 at a time and never expiring. Web service $5, Postgres $5, sign-in for people and agents included, daily task and traffic under $1 each. 1 builder, 1 app ([pricing](https://getfloo.com/pricing)). |
| floo Starter, always warm | \$25 | Web service \$20 with an instance always ready, the rest as above. |

floo's Pro plan is $25 a month with $25 of credits and 5 builder seats; Team is $250 a month with $250 of credits and 50 builder seats. Rates are on [getfloo.com/pricing](https://getfloo.com/pricing).

## Next steps

> [card] [Dockerfiles](https://getfloo.com/docs/guides/dockerfiles.md)
>
> Requirements, layer order, and recommended Dockerfiles.

> [card] [Postgres](https://getfloo.com/docs/guides/postgres.md)
>
> Injected variables, migrations, and preview branches.

> [card] [Cron jobs](https://getfloo.com/docs/guides/cron-jobs.md)
>
> Schedules, timeouts, manual runs, and failure handling.

> [card] [Custom domains](https://getfloo.com/docs/guides/custom-domains.md)
>
> DNS records, apex domains, and activation.


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