noting RabbitMQ for local dev

[oweals/karmaworld.git] / README.md

diff --git a/README.md b/README.md
index b06d85b3baea2136745765bfc01b5fa82b391e29..9c4afd74c930fa7425de7541edb52c8cb8b56af7 100644 (file)
--- a/README.md
+++ b/README.md
@@ -55,14 +55,19 @@ documentation will operate assuming Heroku is in use.
 
 See README.heroku for more information.
 
+
 ### Celery Queue
 Celery uses the Apache Message Queueing Protocol for passing messages to its workers.
-We recommend using Heroku's CloudAMQP add-on, getting your own CloudAMQP account, or
+
+For production, we recommend using Heroku's CloudAMQP add-on, getting your own CloudAMQP account, or
 running a queueing system on your own. The `CLOUDAMQP_URL` environment variable must be set correctly
 for KarmaNotes to be able to use Celery. The `CELERY_QUEUE_NAME` environment variable
 must be set to the name of the queue you wish to use. Settings this to something unique
 allows multiple instances of KarmaNotes (or some other software) to share the same queueing server.
 
+For development on localhost, `RabbitMQ` is the default for `djcelery` and is well supported. Ensure
+`RabbitMQ` is installed for local development.
+
 ### Amazon S3
 The instructions for creating an [S3](http://aws.amazon.com/s3/) bucket may be
 [found on Amazon.](http://docs.aws.amazon.com/AmazonS3/latest/gsg/CreatingABucket.html)
@@ -265,7 +270,9 @@ to get SSL running on your server.
 You may set the `SSL_REDIRECT` environment variable to `true` to make KarmaNotes
 redirect insecure connections to secure ones.
 
-# Local Install
+# Local
+
+## Install
 
 KarmaNotes is a Heroku application. Download the [Heroku toolbelt](https://toolbelt.heroku.com/).
 
@@ -278,11 +285,28 @@ a few setup steps:
   1. `foreman run python manage.py syncdb --migrate --noinput`
   1. `foreman run python manage.py createsuperuser`
   1. `foreman run python manage.py fetch_usde_csv ./schools.csv`
-  1. `foreman run python manage.py import_usde _csv ./schools.csv`
+  1. `foreman run python manage.py import_usde_csv ./schools.csv`
   1. `foreman run python manage.py sanitize_usde_schools`
 
+* `fetch_usde_csv` downloads school records and stores them to `./schools.csv`. This file name
+     and location is arbitrary. As long as the same file is passed into `import_usde_csv` for
+     reading, everything should be fine.
+
+* `fetching_usde_csv` requires `7zip` to be installed for processing compressed
+     archives. On Debian-based systems, this entails `apt-get install p7zip-full`
+
+## Run
+
+Ensure environment variables are available to `foreman` by copying `.env.example`
+to `.env` and update those variables as appropriate for your local system.
+
 To run KarmaNotes locally, make sure you are inside your
 virtual environment (`source venv/bin/activate`) and run `foreman start`.
+
+`foreman` will load the `.env` file and manage running all processes in a way
+that is similar to that of Heroku. This allows better consistency with local,
+staging, and production deployments.
+
 Press ctrl-C to kill foreman. Foreman will run Django's runserver command.
 If you wish to have more control over how this is done, you can do
 `foreman run python manage.py runserver <options>`. For running any other
@@ -302,7 +326,7 @@ You will need to import the US Department of Education's list of accredited scho
    1. Fetch USDE schools with
       `heroku run python manage.py fetch_usde_csv ./schools.csv`
    1. Upload the schools into the database with
-      `heroku run python /manage.py import_usde _csv ./schools.csv`
+      `heroku run python /manage.py import_usde_csv ./schools.csv`
    1. Clean up redundant information with
       `heroku run python /manage.py sanitize_usde_schools`