noting RabbitMQ for local dev

[oweals/karmaworld.git] / README.md

diff --git a/README.md b/README.md
index 6e429d39744ec53d8c28ae5cce9ead80c45dc211..9c4afd74c930fa7425de7541edb52c8cb8b56af7 100644 (file)
--- a/README.md
+++ b/README.md
@@ -55,6 +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.
+
+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)
@@ -254,7 +267,12 @@ signed by a proper authority.
 Follow [Heroku's SSL setup](https://devcenter.heroku.com/articles/ssl-endpoint)
 to get SSL running on your server.
 
-# Local Install
+You may set the `SSL_REDIRECT` environment variable to `true` to make KarmaNotes
+redirect insecure connections to secure ones.
+
+# Local
+
+## Install
 
 KarmaNotes is a Heroku application. Download the [Heroku toolbelt](https://toolbelt.heroku.com/).
 
@@ -267,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
@@ -284,14 +319,14 @@ KarmaNotes is a Heroku application. Download the [Heroku toolbelt](https://toolb
 
 To run KarmaNotes on Heroku, do `heroku create` and `git push heroku master` as typical
 for a Heroku application. Set your the variable `BUILDPACK_URL` to
-`https://github.com/charlesconnell/heroku-buildpack-karmanotes` to use a buildpack designed
-to support KarmaNotes.
+`https://github.com/FinalsClub/heroku-buildpack-karmanotes` to use a buildpack
+designed to support KarmaNotes.
 
 You will need to import the US Department of Education's list of accredited schools.
    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`