Honcho: manage Procfile-based applications

Welcome! This is the home of Honcho and its documentation. Honcho is:

  1. A Python port of David Dollar’s Foreman: a command-line application which helps you manage and run Procfile-based applications. It helps you simplify deployment and configuration of your applications in both development and production environments.

  2. Secondarily, Honcho is a Python library/API for running multiple external processes and multiplexing their output.

The current version of Honcho is 1.1.1.dev42+g8af6317 and it can be downloaded from GitHub or installed using pip: see Installing Honcho.

Documentation index

What are Procfiles?

A Procfile is a file which describes how to run your application. If you need to run a simple web application, you might have a Procfile that looks like this:

web: python myapp.py

You’d then be able to run your application using the following command:

$ honcho start

Now, if running your application is as simple as typing python myapp.py, then perhaps Honcho isn’t that useful. But imagine that a few months have passed, and running your application is now substantially more complicated. You need to have the following running in parallel: a web server, a high priority job queue worker, and a low priority job queue worker. In addition, you’ve established that you need to run your application under a proper web server like gunicorn. Now the Procfile starts to be useful:

web: gunicorn -b "0.0.0.0:$PORT" -w 4 myapp:app
worker: python worker.py --priority high,med,low
worker_low: python worker.py --priority med,low

Again, you can start all three processes with a single command:

$ honcho start

Honcho also supports runpy invocation:

$ python -m honcho start

As you add features to your application, you shouldn’t be forced to bundle everything up into a single process just to make the application easier to run. The Procfile format allows you to specify how to run your application, even when it’s made up of multiple independent components. Honcho (and Foreman, and Heroku) can parse the Procfile format and run your application.

Why did you port Foreman?

Foreman is a great tool! The fact I chose to port it to Python shouldn’t be interpreted as saying anything negative about Foreman. But I have often worked in Python-only development environments where I didn’t want to install Ruby just so I could run Procfile applications. Python, on the other hand, is part of the Linux Standard Base, so even in “Ruby-only” environments it will typically still be installed.

(Oh, and I also I wanted to learn about asynchronous I/O in Python.)

Installing Honcho

If you have a working Python and pip installation, you should be able to simply

pip install honcho

and get a working installation of Honcho. You can probably also easy_install honcho. But please, don’t: get with the program.

Further reading and assistance

For more about the Procfile format, .env files, and command-line options to Honcho, see Using Procfiles.

If you have any difficulty using Honcho or this documentation, please get in touch with me, Nick Stenning, on Twitter at @nickstenning or by email: <my first name> at whiteink dot com.

Indices and tables