Merge pull request #61 from multinet-app/doc-fix

Simplify confusing usage of password environment variables

.gitignore

@@ -1,3 +1,4 @@
 venv/
 .vscode/
-.DS_Store
+.DS_Store
+__pycache__

docker-compose.yaml

@@ -12,7 +12,7 @@ services:
     ports:
       - "${ARANGO_PORT:-8529}:8529"
     environment:
-      - ARANGO_ROOT_PASSWORD=${MULTINET_ROOT_PASSWORD:-openSesame}
+      - ARANGO_ROOT_PASSWORD=${ARANGO_PASSWORD:-letmein}
     volumes:
       - "${ARANGO_DATA:-/var/arangodb}:/var/lib/arangodb3"
       - "${ARANGO_DATA:-/var/arangodb}-apps:/var/lib/arangodb-apps"

docs/installation.rst

@@ -6,27 +6,49 @@ Installation
 =================
 
 Set Up Multinet/Girder
-^^^^^^^^^^^^^^^^^^^^^^
+----------------------
+
 1. Clone this repository: ``git clone
    https://github.com/multinet-app/multinet-girder; cd multinet-girder``.
-2. Start the mongo and arango databases using docker-compose:
-   ``MULTINET_ROOT_PASSWORD=yourSecretPassword docker-compose up -d``.  NOTE:
-   macOS users may encounter errors in this step regarding filemounts denied to
-   the Docker process; to solve this issue, create two directories somewhere
-   (e.g. ``mkdir -p ~/.local/multinet/mongo``, ``mkdir -p
+2. Start the mongo and arango databases using docker-compose: ``docker-compose
+   up``.  NOTE: macOS users may encounter errors in this step regarding
+   filemounts denied to the Docker process; to solve this issue, create two
+   directories somewhere (e.g. ``mkdir -p ~/.local/multinet/mongo; mkdir -p
    ~/.local/multinet/arango``), launch the Docker container using
-   ``MULTINET_APP_PASSWORD=yourSecretPassword MONGO_DATA=~/.local/multinet/mongo
-   ARANGO_DATA=~/.local/multinet/arango docker-compose up -d``.
+   ``MONGO_DATA=~/.local/multinet/mongo ARANGO_DATA=~/.local/multinet/arango
+   docker-compose up -d``.
 3. Use pipenv to create a virtual environment and install the dependencies:
    ``pipenv install``.
 4. Build the Girder web client: ``pipenv run girder build``.
-5. Start the Multinet server: ``MULTINET_APP_PASSWORD=yourSecretPassword yarn
-   start:server``.
+5. Start the Multinet server: ``yarn start:server``.
 6. Open the Multinet Girder application and register a user (which will become
    an admin user): http://localhost:9090.
 
+A Note on Passwords
+~~~~~~~~~~~~~~~~~~~
+
+When the Arango database is launched for the first time in Step 2 above, if the
+Arango data directory does not exist it will be created and populated with
+required startup data, including a password. The default password is
+``letmein``, but it can be set to something different through the
+``ARANGO_PASSWORD`` environment variable.
+
+When the Multinet server is started in Step 5, it will operate using the default
+password to communicate with Arango. Therefore, if you launched Arango using a
+custom password, you should launch the server with that same password, also via
+an ``ARANGO_PASSWORD`` environment variable.
+
+To illustrate, if the Step 2 invocation looks like::
+
+  ARANGO_PASSWORD=hunter2 docker-compose up
+
+then the corresponding command to launch the server in Step 5 will look like::
+
+  ARANGO_PASSWORD=hunter2 yarn start:server
+
 Run Sample Client
-^^^^^^^^^^^^^^^^^
+-----------------
+
 1. Move into the client code directory: ``cd client``.
 2. Install dependencies: ``yarn install``.
 3. Serve the application: ``yarn serve``.

multinet/multinet/db.py

@@ -19,7 +19,7 @@ def db(name, arango=None):
     return arango.db(
         name,
         username="root",
-        password=os.environ['MULTINET_APP_PASSWORD'])
+        password=os.environ.get('ARANGO_PASSWORD', 'letmein'))
 
 
 @with_client