From fe1158dc61d807c1a9a83396cfd9a56726fff46f Mon Sep 17 00:00:00 2001 From: Mike Shoup Date: Tue, 6 Aug 2019 13:34:58 -0600 Subject: [PATCH] Add config variables and cli commands --- docs/installing.rst | 115 +++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 109 insertions(+), 6 deletions(-) diff --git a/docs/installing.rst b/docs/installing.rst index 2000671..31fa9f9 100644 --- a/docs/installing.rst +++ b/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 -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 + 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 @@ -38,9 +42,108 @@ 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 -e HUMULUS_SETTINGS=/app/settings.py -e FLASK_APP=humulus humulus flask import-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 variables, +``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