Merge pull request #469 from NYUCCL/fix-heroku-docs-mention-setup-com…

…mand

update heroku doc to mention psiturk-heroku-config command!

doc/tutorials/heroku.rst

@@ -29,7 +29,9 @@ horsepower beyond 512MB memory and one node.
 
 What follows is a step-by-step tutorial for setting up a `psiTurk` example
 experiment on `Heroku` (both the experiment itself and ad) with a `PostgreSQL`
-database for collecting data:
+database for collecting data.
+
+All commands listed in this tutorial are meant to be typed into your terminal application.
 
 #. Go to the `Heroku website <https://www.heroku.com>`_ and create a new account
  if you don't already have one.
@@ -39,27 +41,22 @@ database for collecting data:
  the `Heroku Command Line Interface <https://devcenter.heroku.com/articles/heroku-cli>`_
  are installed on your computer.
 
-#. Create a psiTurk example at a desired location (all commands listed in this
- tutorial are meant to be typed into your terminal application)::
+#. * **If you don't already have a psiturk experiment:**
 
- psiturk-setup-example
+ Create a psiTurk example at a desired location ::
 
- .. important::
- If you're starting from a preexisting psiturk app, you need to grab several
- files from `/psiturk/example`: `requirements.txt`, `herokuapp.py`,
- `runtime.txt`, and `Procfile`. Place them in your project root, next to
- your `config.txt`.
+ psiturk-setup-example
 
- See the :ref:`migrating` guide for more information on migrating preexisting psiturk experiments.
+ Navigate into your newly created psiTurk example folder::
 
-#. Navigate into your newly created psiTurk example folder::
+ cd psiturk-example
 
-  cd psiturk-example
+ * **If you are starting from an already-existing psiturk project:**
 
- Or if you are starting from an already-existing psiturk project, navigate
- to your project root dir.
+ Navigate to your project root directory.
 
-#. Initialize a Git repository in the root dir of your psiturk project the
+#. **If your experiment is not already in a git repository:**
+ Initialize a Git repository in the root dir of your psiturk project the
  psiTurk (your current working directory)::
 
  git init
@@ -77,79 +74,90 @@ database for collecting data:
  your ``.git/config`` file, which will make it so that any `heroku` commands
  run from your project folder will be run against your newly-created heroku app.
 
-#. Set a database that your heroku app will use.
+#. Run the following psiturk shell command::
 
- **Recommended:** create a Postgres database on the newly created `Heroku` app::
+  psiturk-heroku-config
 
- heroku addons:create heroku-postgresql
+ Running this command copies all files from psiturk's `heroku_files folder <https://github.com/NYUCCL/psiTurk/tree/master/psiturk/heroku_files>`_
+ into your experiment's root directory. These are needed for your experiment to run on Heroku.
 
- This will provision a psiturk-compatible postgresql database, and set an
- environment variable on your app called ``DATABASE_URL`` that points to your database.
- To see the ``DATABASE_URL`` given to you by heroku for this newly-provisioned postgresql database,
- you can run the following::
+ This command also runs ``heroku config:set ON_CLOUD=1`` in your shell on your behalf.
+ This sets an environment variable called ``ON_CLOUD`` to the value ``1`` in your heroku app's environment.
+ Setting ``ON_CLOUD=1`` in your environment tells psiturk to use `some sensible defaults <sensible-cloud-defaults_>`_ for several config settings.
+ Specifically, it sets defaults for ``host``, ``threads``, ``errorlog``, and ``accesslog``.
 
-  heroku config
+ .. _sensible-cloud-defaults: https://github.com/NYUCCL/psiTurk/blob/master/psiturk/default_configs/cloud_config_defaults.txt
 
- .. important::
- This URL includes your username and password. Anyone who has access to the ``database_url`` can
- connect to your database and has access to the data stored in it!
+ .. warning::
 
- .. important::
- psiTurk prefers environment variables over all other config file settings.
- Most environment settings need to prepend ``PSITURK_`` to the corresponding
- config setting name, with the exception of two environment variables:
+ **Heads up!** The `sample config.txt file <sample-config-txt_>`_ generated by psiturk 3 shows defaults in your config.txt commented out
+ (prepended with a ``;``). Cloud defaults will override any defaults that are commented-out in your config.txt.
 
- 1. ``DATABASE_URL``
- 2. ``PORT``
+ .. _sample-config-txt: https://github.com/NYUCCL/psiTurk/blob/master/psiturk/example/config.txt.sample
 
- These two, if present in the environment, are respected even if not prepended by ``PSITURK_``.
+ But if the cloud defaults are set in your config.txt then
+ the cloud defaults will be overridden. To remedy this, you will need to either:
 
- This means that if ``DATABASE_URL`` is set in your heroku environment, it will override
- any setting you have in ``config.txt``.
+ 1. change them in your config.txt or re-comment them out, or
+ 2. set environment variables on heroku for the corresponding cloud defaults that take precedence over your ``config.txt`` values.
 
- .. note::
- If you already have a publicly-accessible database hosted elsewhere, then you can
- do one of the following:
+  For the latter, any of the config settings can be overridden in the heroku environment
+  by setting ``PSITURK_{uppercase_config_name}`` via ``heroku config:set``. For example, to override a config.txt ``threads``
+  on heroku, one could run the following::
 
- 1. list its url as your ``database_url`` in your config.txt and be sure that ``DATABASE_URL`` is not set in your
- heroku environment (check ``heroku config``), or
- 2. set its url in your heroku environment (``heroku config:set DATABASE_URL=your-url``)
+ heroku config:set PSITURK_THREADS=1
 
-#. Set an environment variable on your heorku app which will set `some sensible
- defaults <sensible-cloud-defaults_>`_ for several config settings::
+#. Set a database that your heroku app will use.
+
+ * **To get a free heroku-hosted postgresql database:**
+
+ Create a Postgres database on the newly created `Heroku` app::
 
- heroku config:set ON_CLOUD=1
+ heroku addons:create heroku-postgresql
 
- Specifically, it sets defaults for ``host``, ``threads``, ``errorlog``, and ``accesslog``.
+ This will provision a psiturk-compatible postgresql database, and set an
+ environment variable on your app called ``DATABASE_URL`` that points to your database.
 
- .. _sensible-cloud-defaults: https://github.com/NYUCCL/psiTurk/blob/master/psiturk/default_configs/cloud_config_defaults.txt
+ To see the ``DATABASE_URL`` given to you by heroku for this newly-provisioned postgresql database,
+ you can run the following::
 
+ heroku config
 
- .. warning::
+ .. important::
+ This URL includes your username and password. Anyone who has access to the ``database_url`` can
+ connect to your database and has access to the data stored in it!
 
- **Heads up!** The `sample config.txt file <sample-config-txt_>`_ shows defaults in your config.txt commented out
- (prepended with a ``;``). Cloud defaults will override any defaults that are commented-out in your config.txt.
+ * **If you already have a publicly-accessible database hosted elsewhere:**
 
- .. _sample-config-txt: https://github.com/NYUCCL/psiTurk/blob/master/psiturk/example/config.txt.sample
+ Then you can do one of the following:
+
+ 1. list its url as your ``database_url`` in your config.txt and be sure that ``DATABASE_URL`` is not set in your
+ heroku environment (check ``heroku config``), or
+ 2. set its url in your heroku environment (``heroku config:set DATABASE_URL=your-url``)
 
- But if the cloud defaults are set in your config.txt then
- the cloud defaults will be overridden. To remedy this, you will need to either:
+ .. important::
+ psiTurk prefers environment variables over all other config file settings.
+ Most environment settings need to prepend ``PSITURK_`` to the corresponding
+ config setting name, with the exception of two environment variables:
 
-  1.  change them in your config.txt or re-comment them out, or
-  2.  set environment variables on heroku for the corresponding cloud defaults that take precedence over your ``config.txt`` values.
+ 1. ``DATABASE_URL``
+ 2. ``PORT``
 
- For the latter, any of the config settings can be overridden in the heroku environment
- by setting ``PSITURK_{uppercase_config_name}`` via ``heroku config:set``. For example, to override a config.txt ``threads``
- on heroku, one could run the following::
+ These two, if present in the environment, are respected even if not prepended by ``PSITURK_``.
 
- heroku config:set PSITURK_THREADS=1
+ This means that if ``DATABASE_URL`` is set in your heroku environment, it will override
+ any setting you have in ``config.txt``.
 
 #. **Optional**: if you want to use the :ref:`psiturk dashboard <dashboard-overview>` from your heroku
- instance, then set your AWS credentials as environment variables within your heroku app, replacing ``<XYZ>`` with your access and secret
- keys for `Amazon Web Services <amt_setup.html#obtaining-aws-credentials>`_::
+ instance to run AWS some commands, or if you want your heroku instance to run any :ref:`tasks <tasks-overview>` created
+ by the dashboard:
 
- heroku config:set aws_access_key_id=<XYZ>
- heroku config:set aws_secret_access_key=<XYZ>
+ * Set your AWS credentials as environment variables within your
+ heroku app, replacing ``<XYZ>`` with your access and secret
+ keys for `Amazon Web Services <amt_setup.html#obtaining-aws-credentials>`_::
+
+ heroku config:set aws_access_key_id=<XYZ>
+ heroku config:set aws_secret_access_key=<XYZ>
 
 #. Stage all the files in your psiTurk example to your Git repository: ::
 
@@ -171,7 +179,7 @@ database for collecting data:
 
 #. You can run through your heroku-hosted experiment by visiting your heroku app's url.
 
- To get it, run ``heroku domains`` from the root of your local psiturk app,
+ To get your app's url, run ``heroku domains`` from the root of your local psiturk app,
  and visit your app's reported domain url in a browser. From that url, you can conveniently obtain a debugging url by clicking
  "Begin by viewing the `ad`."
 
@@ -186,21 +194,25 @@ database for collecting data:
  1. your ``config.txt`` file, or
  2. your own local environment.
 
+ .. warning::
+
+ If you opt to set your database url in your ``config.txt`` file, then be cautious
+ about sharing your experiment code -- the url contains your database username and password!
+
  Once your local psiturk app uses the same database as your heroku app, then you can run the
  following to download your experiment data, regardless of whether you have run through
  your experiment hosted locally *or* on Heroku::
 
  psiturk download_datafiles
 
  This should generate three datafiles for you in your local directory:
- ``trialdata.csv``, ``questiondata.csv``, and ``eventdata.csv``.
 
- Congratulations, you've now gathered data from an experiment running on `Heroku`!
+ * ``trialdata.csv``,
+ * ``questiondata.csv``, and
+ * ``eventdata.csv``.
 
- .. warning::
+ Congratulations, you've now gathered data from an experiment running on `Heroku`!
 
- If you opt to set your database url in your ``config.txt`` file, then be cautious
- about sharing your experiment code -- the url contains your database username and password!
 
  .. note::
  psiTurk will look for a file called ``.env`` in the root of your psiturk app and read in any
@@ -227,7 +239,7 @@ From your *local* ``psiTurk`` session, you can now
 `create and modify HITs <command_line/hit.html>`_. When these are accessed by
 Amazon Mechanical Turk workers, the workers will be directed to the `psiTurk`
 session running on your `Heroku` app. This means that it is never necessary to
-launch `psiTurk` and run `server on` from _anywhere_ to run an experiment on
+launch `psiTurk` and run `server on` from *anywhere* to run an experiment on
 Heroku. The server is automatically running, accessible via your Heroku domain
 url. (Of course, if you want to debug locally, you can still run a local server.)