Installing

Docker

It is recommended to install Humulus using docker. You can run a container for CouchDB and a container for Humulus on the same machine. Docker makes it easy to update to the latest version.

The following commands can be ran to setup Humulus in docker:

# Create a network for all of this to run under
sudo docker network create humulus

# Create a CouchDB container with admin user credentials admin/password
sudo docker run -d -e COUCHDB_USER=admin -e COUCHDB_PASSWORD=password \
  --network humulus --name couchdb couchdb:latest
# Create the databases needed to run in single server mode
sudo docker exec -it couchdb /usr/bin/curl \
  -X PUT http://admin:password@127.0.0.1:5984/_users
sudo docker exec -it couchdb /usr/bin/curl \
  -X PUT http://admin:password@127.0.0.1:5984/_replicator
sudo docker exec -it couchdb /usr/bin/curl \
  -X PUT http://admin:password@127.0.0.1:5984/_global_changes

# Create a config file for humulus
sudo mkdir -p /opt/humulus
sudo tee /opt/humulus/settings.py <<EOF
SECRET_KEY = "$(uuidgen -r)"
COUCH_URL = "http://couchdb:5984"
COUCH_USERNAME = "admin"
COUCH_PASSWORD = "password"
COUCH_DATABASE = "humulus"
HUMULUS_PASSWORD = "foobar"
EOF
# Run a container for humulus
sudo docker run -d -e HUMULUS_SETTINGS=/app/settings.py \
  --mount type=bind,source=/opt/humulus/settings.py,destination=/app/settings.py,ro \
  -p 8000:8000 --network humulus --name humulus shouptech/humulus:latest

# Setup the database and import BJCP styles
sudo docker exec -it \
  -e HUMULUS_SETTINGS=/app/settings.py -e FLASK_APP=humulus humulus \
  flask build-couch
sudo docker exec -it \
  -e HUMULUS_SETTINGS=/app/settings.py -e FLASK_APP=humulus humulus \
  flask import-styles

After doing the above, point your web browser to http://localhost:8000. Login with the password configured for HUMULUS_PASSWORD. Now get to work creating recipes.

Configuration

When launching Humulus, you must point an environment variable, HUMULUS_SETTINGS, to a python file containing configuration variables.

The following variables must be defined:

SECRET_KEY

The key used to cryptographically sign session cookies. See the Flask documentation for sessions.

Example: b'_5#y2L"F4Q8z\n\xec]/'

COUCH_URL

The URL to find a CouchDB server at.

Example: http://couchdb:5984

COUCH_USERNAME

The username to connect to CouchDB with.

Example: admin

COUCH_PASSWORD

The password to connect to CouchDB with.

Example: password

COUCH_DATABASE

The CouchDB database to connect to. If the database does not exist, and the user defined in COUCH_USERNAME has permission, the database will be created while executing the build-couch command.

Example: humulus

HUMULUS_PASSWORD

The password used for logging into the application. You cannot create, modify, or, delete recipes if you’re not logged in with this password.

Example: password

Command Line Interface

The following commands can be executed using the Flask CLI. To execute the commands, you must set the environment variable, FLASK_APP to humulus, and set HUMULUS_SETTINGS to the file created. See Configuration.

build-couch

Used to initialize the Couch database. This command creates the database if not found, and also updates any views that are missing, and/or, out of date.

export FLASK_APP=humulus
export HUMULUS_SETTINGS=/path/to/settings.py
flask build-couch

import-styles

Imports the 2015 BJCP style guidelines. Retrieves a styleguide.xml from GitHub and then writes the data to the Couch database.

export FLASK_APP=humulus
export HUMULUS_SETTINGS=/path/to/settings.py
flask import-styles

Commands in Docker

If you’re running Humulus using Docker (the recommended way), you can execute the commands inside the docker container:

sudo docker exec -it \
  -e HUMULUS_SETTINGS=/app/settings.py -e FLASK_APP=humulus humulus \
  flask build-couch
sudo docker exec -it \
  -e HUMULUS_SETTINGS=/app/settings.py -e FLASK_APP=humulus humulus \
  flask import-styles