Last updated December 03, 2024

This article explains how to use the Heroku Local CLI plugin.

Run Your App Locally with the Heroku Local Command-Line Tool

Heroku Local is a command-line tool to run Procfile-backed apps. It’s installed automatically as part of the Heroku CLI. Heroku Local reads configuration variables from a .env file. Heroku Local uses node-foreman to accomplish its tasks.

Start Your App Locally

To start all the process types defined in your Procfile, enter:

$ heroku local

To start a particular process type, specify the process type. For example, web or worker.

$ heroku local web

You can now test the app locally. Press Ctrl+C to shut it down when you’re done.

Here are some of the command line options.

• To use a different Procfile, use the -f flag: heroku local -f Procfile.test.

• To use a different environment file, use the -e flag: heroku local -e .env.test.

• To use a different port, use the -p flag: heroku local -p 7000. If you don’t specify a port, 5006 is used.

For more information, enter heroku help local at the command line.

Run a One-Off Command Locally

With Heroku Local, you can run a single one-off command locally. For example: heroku local:run rails console. This command is analogous to Heroku’s one-off dynos.

Set Up Your Local Environment Variables

When running your app, typically you use a set of config vars to capture the app’s configuration. For example, say your app uses S3 for image storage. You want to store the credentials to S3 as config vars. If you run your app locally, you want to use a different S3 bucket than if you run it in production.

With the .env file, you can capture all the config vars you need to run your app locally. When you start your app using any of the heroku local commands, the .env file is read, and each name/value pair is inserted into the environment, to mimic the action of config vars.

View Your App’s Config Vars

To view all your app’s config vars, enter heroku config.

Look at the Contents of Your .env File

$ cat .env

Here’s an example .env file.

S3_KEY=mykey
S3_SECRET=mysecret

Add a Config Var to Your .env File

To add a config var to your .env file, edit it and add a new name=value pair on a new line.

Copy Heroku Config Vars to Your Local .env File

Sometimes you want to use the same config var in local and Heroku environments. For each config var that you want to add to your .env file, use this command.

$ heroku config:get CONFIG-VAR-NAME -s  >> .env

Don’t commit the .env file to source control. Only use it for local configuration. Update your .gitignore file to exclude the .env file.

Keep in mind that your deployed production app can connect to different services than your local development app. For example, your deployed production app can have a DATABASE_URL config var that references a Heroku Postgres database, but your local app has a DATABASE_URL variable in the .env file that references your local installation of Postgres.

Run Your App Locally Using Foreman

As an alternative to using Heroku Local, you can use Foreman to run your app locally. It’s not officially supported, but if you want to use it, you can get more information by visiting the Foreman GitHub repository.

Foreman is a command-line tool for running Procfile-backed apps. Foreman reads configuration variables from a .env file.

Start Your App Locally

$ foreman start
18:06:23 web.1     | started with pid 47219
18:06:23 worker.1  | started with pid 47220
18:06:25 worker.1  | (in /Users/adam/myapp)
18:06:27 web.1     | => Awesome web application server output

If you had a Procfile with web and worker process types, Foreman starts one of each process type, with the output interleaved on your terminal. Your web process loads on port 5000 because this is what Foreman provides as a default in the $PORT env var. It’s important that your web process respects this value because the Heroku platform uses it when you deploy.

You can now test the app locally. Press Ctrl+C to shut it down when you are done.

Alternatively, you can select a different environment file at launch with the -e flag. For example: foreman -e alternate_env start.

Run a One-Off Command Locally

You can run a single one-off command locally with Foreman. For example: foreman run rails console. This command is analogous to Heroku’s one-off dynos.

Run Your Cloud Native Buildpack App Locally Using Pack

As an alternative to using Heroku Local, apps using the cnb stack can use pack to run locally. Pack is a CLI tools maintained by the Cloud Native Buildpack project that can build applications using buildpacks into runnable OCI images.

Build Your App into an OCI image

To produce an OCI image from your app using pack, you must run pack build. To produce the same image that Heroku builds for your app when you deploy, use the heroku/builder:24 build image.

pack build <your-image-name> \
  --builder heroku/builder:24 \
  --path .

Run the App Image

After creating the OCI image for your app, you can run it in Docker (or any alternative OCI runtime). For example, using docker run:

docker run \
  --publish 5006:5006 \
  --env PORT=5006 \
  --env-file ./.env \
  --rm --interactive --tty <your-image-name>

docker run starts the app’s web process in a Docker container. The --publish 5006:5006 binds port 5006 of the container to port 5006 of the host so you can access your app locally. You must also set the --env PORT=5006 so that your web process knows which container port to bind to when it starts.

Running Commands

You can run other commands using your app’s Docker image. For example, to execute bash:

docker run \
  --publish 5006:5006 \
  --env PORT=5006 \
  --entrypoint launcher \
  --rm --interactive --tty node-getting-started bash