Honcho

Honcho is a Python-based tool for managing Procfile-based applications. It serves two primary purposes:

1. CLI Tool: A command-line application (a Python port of Foreman) that helps simplify the deployment and configuration of applications by running multiple processes defined in a Procfile simultaneously.
2. Python Library/API: A library for running multiple external processes and multiplexing their output.

You can create a .env file alongside your Procfile to define environment variables that will be available to all processes started by Honcho.

Honcho also automatically injects a HONCHO_PROCESS_NAME variable into the subprocess environment. This variable is a unique string composed of the process name and an integer counter (e.g., web.1, web.2, queue.1).

To specify a custom Procfile location via environment variables, you can set PROCFILE=<path> inside your .env file. This takes priority over the default Procfile name.

$ cat >.env <<EOF
RACK_ENV=production
ASSET_ROOT=https://myapp.s3.amazonaws.com/assets
PROCFILE=Procfile
EOF

To make your custom exporter detectable by Honcho, you must register your class under the honcho_exporters entry point in your package's setup.py (or equivalent configuration).

from setuptools import setup

setup(
    name='honcho_export_simple',
    ...
    entry_points={
        'honcho_exporters': [
            'simple=honcho_export_simple:SimpleExport',
        ],
    },
)

Honcho manages applications defined by a Procfile. Follow these steps to run your application:

1. Create a Procfile: Define your processes. Each line should follow the format type: command.
2. Create a .env file (Optional): Use this file to configure environment variables for your application.
3. Run Honcho: Execute the honcho start command to launch all processes defined in your Procfile.

# 1. Create a Procfile
$ cat >Procfile <<EOM
web: python serve.py
redis: redis-server
EOM

# 2. Create a .env file (Optional)
$ cat >.env <<EOM
PORT=6000
REDIS_URI=redis://localhost:6789/0
EOM

# 3. Run the app
$ honcho start

Honcho manages and runs applications defined in a Procfile. A Procfile describes how to run various components of your application (e.g., a web server and multiple workers) in parallel.

Example Procfile

Create a file named Procfile in your project root:

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

Starting the application

You can start all processes defined in the Procfile using the honcho start command, or by using runpy invocation:

# Using the CLI
honcho start

# Using runpy
python -m honcho start

When submitting a pull request for Honcho, ensure the following requirements are met:

1. Include tests: Every PR must include corresponding tests.
2. Update documentation: If adding new functionality, update the documentation and ensure new functions or classes include proper docstrings.
3. Python version compatibility: Ensure the changes work across all supported Python versions. Verify that tests pass on the CI platform.

To contribute to Honcho, follow these steps to set up a local development environment using a virtualenv and editable installation:

1. Fork the repository on GitHub.
2. Clone your fork locally.
3. Create a virtualenv and install the package in editable mode with the [export] extra and tox.
4. Create a new branch for your changes.
5. Run tests using tox to ensure compatibility across Python versions.
6. Commit, push, and submit a pull request.

# Clone your fork
git clone git@github.com:your_name_here/honcho.git

# Set up virtualenv and install in editable mode
mkvirtualenv honcho
cd honcho/
pip install -e .[export] tox

# Create a development branch
git checkout -b name-of-your-bugfix-or-feature

Honcho uses tox to manage testing across different Python versions. Use tox to run the full test suite, which utilizes pytest internally.

To run all environments:

tox

To run a specific environment (e.g., Python 3.9):

tox -e py39

To list all available tox environments:

tox -l

To pass arguments directly to the underlying pytest command, use -- after the tox command. For example, to stop after the first error using a PyPy interpreter:

tox -e pypy -- -x

A Procfile is a plain text file placed at the root of your application's source tree that describes the components required to run your application. Each line follows the syntax <process type>: <command>.

• <process type>: A unique string identifying the process (e.g., web, worker, my_process_123). It can contain alphanumerics, underscores, and dashes ([A-Za-z0-9_-]+).
• <command>: The shell commandline to be executed to spawn that process type.

Honcho can export your Procfile configuration into various process management formats. Shipped exporters include upstart, supervisord, runit, and systemd.

Use the following command syntax:

$ honcho export FORMAT LOCATION

By default, Honcho starts one instance of each process type. You can adjust this by using the --concurrency option.

If you have a working Python and pip installation, you can install Honcho using the following command:

pip install honcho