Skip Navigation
Show nav
Heroku Dev Center
  • Get Started
  • Documentation
  • Changelog
  • Search
  • Get Started
    • Node.js
    • Ruby on Rails
    • Ruby
    • Python
    • Java
    • PHP
    • Go
    • Scala
    • Clojure
  • Documentation
  • Changelog
  • More
    Additional Resources
    • Home
    • Elements
    • Products
    • Pricing
    • Careers
    • Help
    • Status
    • Events
    • Podcasts
    • Compliance Center
    Heroku Blog

    Heroku Blog

    Find out what's new with Heroku on our blog.

    Visit Blog
  • Log inorSign up
View categories

Categories

  • Heroku Architecture
    • Dynos (app containers)
    • Stacks (operating system images)
    • Networking & DNS
    • Platform Policies
    • Platform Principles
  • Command Line
  • Deployment
    • Deploying with Git
    • Deploying with Docker
    • Deployment Integrations
  • Continuous Delivery
    • Continuous Integration
  • Language Support
    • Node.js
    • Ruby
      • Working with Bundler
      • Rails Support
    • Python
      • Background Jobs in Python
      • Working with Django
    • Java
      • Working with Maven
      • Java Database Operations
      • Working with Spring Boot
      • Java Advanced Topics
    • PHP
    • Go
      • Go Dependency Management
    • Scala
    • Clojure
  • Databases & Data Management
    • Heroku Postgres
      • Postgres Basics
      • Postgres Getting Started
      • Postgres Performance
      • Postgres Data Transfer & Preservation
      • Postgres Availability
      • Postgres Special Topics
    • Heroku Data For Redis
    • Apache Kafka on Heroku
    • Other Data Stores
  • Monitoring & Metrics
    • Logging
  • App Performance
  • Add-ons
    • All Add-ons
  • Collaboration
  • Security
    • App Security
    • Identities & Authentication
    • Compliance
  • Heroku Enterprise
    • Private Spaces
      • Infrastructure Networking
    • Enterprise Accounts
    • Enterprise Teams
    • Heroku Connect (Salesforce sync)
      • Heroku Connect Administration
      • Heroku Connect Reference
      • Heroku Connect Troubleshooting
    • Single Sign-on (SSO)
  • Patterns & Best Practices
  • Extending Heroku
    • Platform API
    • App Webhooks
    • Heroku Labs
    • Building Add-ons
      • Add-on Development Tasks
      • Add-on APIs
      • Add-on Guidelines & Requirements
    • Building CLI Plugins
    • Developing Buildpacks
    • Dev Center
  • Accounts & Billing
  • Troubleshooting & Support
  • Integrating with Salesforce
  • Command Line
  • Running Apps Locally

Running Apps Locally

English — 日本語に切り替える

Last updated March 13, 2023

Table of Contents

  • Run your app locally using the Heroku Local command line tool
  • Set up your local environment variables
  • Copy Heroku config vars to your local .env file
  • Run your app locally using Foreman

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

Run your app locally using the Heroku Local command line tool

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

Start your app locally

To locally start all of the process types that are defined in your Procfile:

$ heroku local

heroku local is a shorter alternative to heroku local:start which does the same thing.

To locally 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 are 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, 5000 is used.

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

Run a one-off command locally

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

Set up your local environment variables

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

The .env file lets you capture all the config vars that you need in order 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 of your app’s config vars, type 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

Credentials and other sensitive configuration values should not be committed to source-control. In Git exclude the .env file with: echo .env >> .gitignore.

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 may want to use the same config var in both local and Heroku environments. For each config var that you want to add to your .env file, use the following command:

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

Do not commit the .env file to source control. It should only be used for local configuration. Update your .gitignore file to exclude the .env file.

Keep in mind that your deployed production app may be connecting to different services than your local development app. For example, your deployed production app might have a DATABASE_URL config var that references a Heroku Postgres database, but your local app might have 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 still 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 both web and worker process types, Foreman will start 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 respect this value, since it’s used by the Heroku platform 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 by using the -e flag like this: foreman -e alternate_env start.

Run a one-off command locally

Foreman also lets you easily run a single one-off command locally. For example: foreman run rails console. This is analogous to Heroku’s one-off dynos.

Keep reading

  • Command Line

Feedback

Log in to submit feedback.

Using CLI Plugins The Heroku CLI

Information & Support

  • Getting Started
  • Documentation
  • Changelog
  • Compliance Center
  • Training & Education
  • Blog
  • Podcasts
  • Support Channels
  • Status

Language Reference

  • Node.js
  • Ruby
  • Java
  • PHP
  • Python
  • Go
  • Scala
  • Clojure

Other Resources

  • Careers
  • Elements
  • Products
  • Pricing

Subscribe to our monthly newsletter

Your email address:

  • RSS
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku Blog
    • Heroku News Blog
    • Heroku Engineering Blog
  • Heroku Podcasts
  • Twitter
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku
    • Heroku Status
  • Facebook
  • Instagram
  • Github
  • LinkedIn
  • YouTube
Heroku is acompany

 © Salesforce.com

  • heroku.com
  • Terms of Service
  • Privacy
  • Cookies
  • Cookie Preferences