Add description for running commands in Docker

docs/installing.rst

@@ -16,11 +16,15 @@ The following commands can be ran to setup Humulus in docker:
     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
+    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 \
-    sudo docker exec -it couchdb /usr/bin/curl -X PUT http://admin:password@127.0.0.1:5984/_replicator
+      -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/_global_changes
+    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
@@ -38,9 +42,123 @@ The following commands can be ran to setup Humulus in docker:
       -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 \
-    sudo docker exec -it -e HUMULUS_SETTINGS=/app/settings.py -e FLASK_APP=humulus humulus flask import-styles
+      -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]/'``
+
+.. _`Flask documentation for sessions`: https://flask.palletsprojects.com/en/1.1.x/quickstart/#sessions
+
+``COUCH_URL``
+^^^^^^^^^^^^^
+
+The URL to find a `CouchDB`_ server at.
+
+**Example**: ``http://couchdb:5984``
+
+.. _`CouchDB`: http://couchdb.apache.org/
+
+``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`_.
+
+.. _`Flask CLI`: https://flask.palletsprojects.com/en/1.1.x/cli/
+
+``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
+
+.. _`styleguide.xml`: https://github.com/meanphil/bjcp-guidelines-2015/blob/master/styleguide.xml
+
+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