Table of Contents
The set of dynos declared in your Procfile and managed by the dyno manager via
heroku ps:scale are known as the dyno formation. These dynos do the app’s regular business (such as handling web requests and processing background jobs) as it runs. But when you wish to do one-off administrative or maintenance tasks for the app, you’ll want to spin up a one-off dyno using the
heroku run command.
After you push your application to Heroku, the slug compiler generates a slug containing the application. The application may contain many components, including a web server, a console application, and scripts to initialize the database. While the web dyno would be defined in the Procfile and managed by the platform, the console and script would only be executed when needed. These are one-off dynos.
Any time spent executing a one-off dyno will contribute to usage and will be charged just like any other dyno.
Formation dynos vs. one-off dynos
One-off dynos run alongside other dynos, exactly like the app’s web, worker, and other formation dynos. They get all the benefits of dyno isolation.
Each dyno has its own ephemeral filesystem, not shared with any other dyno, that is discarded as soon as you disconnect. This filesystem is populated with the slug archive - so one-off dynos can make full use of anything deployed in the application.
There are four differences between one-off dynos (run with
heroku run) and formation dynos (run with
- One-off dynos run attached to your terminal, with a character-by-character TCP connection for
STDOUT. This allows you to use interactive processes like a console. Since
STDOUTis going to your terminal, the only thing recorded in the app’s logs is the startup and shutdown of the dyno.
- One-off dynos terminate as soon as you press Ctrl-C or otherwise disconnect in your local terminal. One-off dynos never automatically restart, whether the process ends on its own or whether you manually disconnect.
- One-off dynos are named in the scheme
run.Nrather than the scheme
- One-off dynos can never receive HTTP traffic, since the routers only routes traffic to dynos named
Other than these differences, the dyno manager makes no distinction between one-off dynos and formation dynos.
An example one-off dyno
One-off dynos are created using
heroku run. To see one-off dynos in action, execute the
bash command, available in all applications deployed to Heroku:
$ heroku run bash Running bash attached to terminal... up, run.1 ~ $
At this point you have a one-off dyno executing the
bash command - which provides a shell environment that can be used to explore the file system and process environment.
Interact with the shell and list all the files that you deployed:
~ $ ls Procfile project.clj src bin ...
If you had a batch file in the
bin directory, you can simply execute it, just as you can many other unix commands:
~ $ echo "Hi there" Hi there ~ $ pwd /app ~ $ bin/do-work
Remove a few files, and exit:
~ $ rm Procfile project.clj ~ $ exit
Because each dyno is populated with its own copy of the slug-archive, the deleted files won’t change your running application.
One-off dyno execution syntax
heroku run takes two types of parameters - you can either supply the command to execute, or a process type that is present in your application’s Procfile.
If you supply a command, either a script or other executable available to your application, then it will be executed as a one-off dyno, together with any additional arguments. For example, to execute the Python interpreter with a file
dowork.py supplied as an argument, then execute
heroku run python dowork.py.
If you instead supply a process type, as declared in a
Procfile, then its definition will be substituted, and executed together with any additional arguments. For example, given the following
myworker: python dowork.py
heroku run myworker 42 will run
python dowork.py 42 as a one-off dyno.
Types of one-off dynos
Some types of one-off dynos include:
- Initialising databases or running database migrations. (e.g.
node migrate.js migrate)
- Running a console (also known as a REPL shell) to run arbitrary code or inspect the app’s models against the live database. (e.g.
- One-time scripts committed into the app’s repo (e.g.
In your local environment, you invoke these one-off dynos by a direct shell command inside the app’s checkout directory. For example:
To pass command line flags to the command being executed, you can quote the entire string to be executed to avoid the Heroku CLI processing the flags:
heroku run "rake --help"
$ rake db:migrate (in /Users/adam/widgets) == CreateWidgets: migrating ================================================== -- create_table(:widgets) -> 0.0040s == CreateWidgets: migrated (0.0041s) =========================================
You can do the exact same thing, but run against your latest Heroku release by prefixing your command with
$ heroku run rake db:migrate (in /app) Migrating to CreateWidgets (20110204210157) == CreateWidgets: migrating ================================================== -- create_table(:widgets) -> 0.0497s == CreateWidgets: migrated (0.0498s) =========================================
Likewise, if you can run a console in your local environment by executing a command, as you can with Rails and
rails console command:
$ rails console Loading development environment (Rails 3.0.3) ruby-1.9.2-p136 :001 > Widget.create :name => 'Test' => #<Widget id: 1, name: "Test", size: nil, created_at: "2011-05-31 02:36:39", updated_at: "2011-05-31 02:36:39">
Running the same command against your deployed Heroku app will execute it, and attach it to your terminal:
$ heroku run rails console Running rails console attached to terminal... up, run.2 Loading production environment (Rails 3.0.3) irb(main):001:0> Widget.create :name => 'Test' => #<Widget id: 1, name: "Test", size: nil, created_at: "2011-05-31 02:37:51", updated_at: "2011-05-31 02:37:51">
Running tasks in background
You can run a dyno in the background using
heroku run:detached. Unlike
heroku run, these dynos will send their output to your logs instead of your console window. You can use
heroku logs to view the output from these commands:
$ heroku run:detached rake db:migrate Running rake db:migrate... up, run.2 Use 'heroku logs -p run.2' to view the log output.
Stopping one-off dynos
You can check your current running dynos using
$ heroku ps === run: one-off processes run.7364: starting 2013/03/13 15:38:08 (~ 1s ago): `bash` === web: `bundle exec unicorn -p $PORT -c ./config/unicorn.rb` web.1: up 2013/03/13 15:08:07 (~ 30m ago) web.2: up 2013/03/12 17:06:09 (~ 22h ago)
If you wish to stop a running one-off dyno, use
heroku ps:stop with its name.
$ heroku ps:stop run.1 Stopping run.1 process... done
A one-off dyno will not stop if you issue
heroku ps:restart on your application.
One-off dyno timeout
It is possible to trap
SIGHUP and cause your dyno to continue running even when the connection is closed. See the signal manual page for more information.
Connections to one-off dynos will be closed after one hour of inactivity (in both input and output). When the connection is closed, the dyno will be sent
SIGHUP. This idle timeout helps prevent unintended charges from leaving interactive console sessions open and unused.
Detached dynos have no connection, so they have no timeout. However, like all dynos, one-off dynos are cycle every 24 hours. As a result, a one-off dyno will run for a maximum of 24 hours.
One-off dyno size
By default, one-off dynos run at the 1X size irrespective of the default dyno size of your app. You can run one-off dynos at a 2X or PX size by using the
$ heroku run --size=2X rake heavy:job
$ heroku run --size=PX rake heavy:job
See the Default scaling limits section for limits on how many one-off dynos can run concurrently.
Timeout awaiting process
heroku run command opens a connection to Heroku on port 5000. If your local network or ISP is blocking port 5000, or you are experiencing a connectivity issue, you will see an error similar to:
$ heroku run rails console Running rails console attached to terminal... Timeout awaiting process
You can test your connection to Heroku by trying to connect directly to
rendezvous.runtime.heroku.com on port 5000 using telnet. A successful session will look like this:
$ telnet rendezvous.runtime.heroku.com 5000 Trying 22.214.171.124... Connected to ec2-50-19-103-36.compute-1.amazonaws.com. Escape character is '^]'.
If you do not get this output, your computer is being blocked from accessing our services. We recommend contacting your IT department, ISP, or firewall manufacturer to move forward with this issue.
Since your app is spread across many dynos by the dyno manager, there is no single place to SSH into. You deploy and manage apps, not servers.
You can invoke a shell as a one-off dyno:
$ heroku run bash
However, there is little to be gained from doing so. The filesystem is ephemeral, and the dyno itself will only live as long as your console session.
When you find yourself wanting SSH access, instead try using tools that properly accounts for Heroku’s distributed environment, such as the heroku command line tool and one-off dynos.