Honcho: manage Procfile-based applications¶
Welcome! This is the home of Honcho and its documentation. Honcho is:
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.
Secondarily, Honcho is a Python library/API for running multiple external processes and multiplexing their output.
- Using Procfiles
- API Documentation
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
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.
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
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