## External Service Dependencies
-Notice: This software makes use of external third party services which require
+Notice: A number of services are required even if running the KarmaWorld web
+service [locally](#local). Some of the services are recommended, and some are
+completely optional even if running the web service on Heroku.
+
+This software makes use of external third party services which require
accounts to access the service APIs. Without these third parties available,
-this software may require considerable overhaul. These services have
-API keys, credentials, and other information that you must provide to KarmaWorld
-as environment variables. The best way to persist these environment variables is
-by using a `.env` file. Copy `.env.example` to `.env` and populate the fields as
-required.
+this software may require considerable overhaul. These services have API keys,
+credentials, and other information that you must provide to KarmaWorld
+as environment variables.
-A number of services are required even if running the KarmaWorld web service
-locally, some of the services are recommended, and some are completely optional
-even if running the web service on Heroku.
+The best way to persist these API keys in environment variables is by using a
+`.env` file. Copy `.env.example` to `.env` and populate the fields as required.
Many of these services have free tiers and can be used without charge for
development testing purposes.
+* Reminder
+ * Copy `.env.example` to `.env` and populate the environment variables there.
* Required Services
* [Google Drive](#google-drive)
* [Filepicker](#filepicker)
This may be done with a Google Apps account with administrative privileges, or ask
your business sysadmin.
-Follow [Google's instructions](https://developers.google.com/drive/delegation)
-to create a Google Drive service account.
+Follow [Google's instructions](https://developers.google.com/drive/web/auth/web-server)
+to create a Google Drive service account. If using Google Apps, it is worth
+looking at [these instructions](https://developers.google.com/drive/delegation).
+
+Populate the `GOOGLE_USER` environment variable with the email address of the
+user whose Google Drive will be accessed. This is typically your own email
+address.
+
+Google Drive used to use p12 files by default. Now a new-style JSON file is
+downloaded by default when creating new credentials. Until the code has been
+[updated](https://github.com/FinalsClub/karmaworld/issues/437) to use the
+new-style JSON file, make sure to click the `Generate a new P12 key` button.
+
+While on the Credentials page (with the `Generate a new P12 key` button
+visible), note the Service account Email address. It will have a format like
+`numbers-alphanumerics@developer.gserviceaccount.com`. Copy this value and
+paste it into the `GOOGLE_SERVICE_EMAIL` environment variable.
Convert the p12 file into a Base64 encoded string for the
`GOOGLE_SERVICE_KEY_BASE64` environment variable. There are many ways to do
with open('file.p12', 'r') as f:
print binascii.b2a_base64(f.read)
-Copy the contents of `client_secret_*.apps.googleusercontent.com.json` into the
-`GOOGLE_CLIENT_SECRETS` environment variable.
-
### Filepicker
-This software uses [Filepicker.io](https://www.inkfilepicker.com/) for uploading
+This software uses [Filepicker](https://www.filepicker.com/) for uploading
files. This requires an account with Filepicker.
Filepicker can use an additional third party file hosting site where it may
send uploaded files. This project, in production, uses Amazon S3 as the third
party. See the Amazon S3 section above for more information.
+In development, an S3 bucket will not be necessary. The Free Plan should
+suffice.
+
Create a new App with Web SDK and provide the Heroku App URL for the
Application's URL. You'll be given an API Key for the App. Paste this into the
`FILEPICKER_API_KEY` environment variable.
Find the 'App Security' button on the left hand side of the web site. Make sure
-'Use Security' is enabled. Generate a new secret key. Paste this key into the
+'Use Security' is enabled. Generate a new app secret. It might require
+reloading the page to see the new secret. Paste this secret into the
`FILEPICKER_SECRET` environment variable.
If you have an upgraded plan, you can configure Filepicker to have access to
## Configuring foreman
-KarmaNotes runs on Heroku as a webapp and thus makes use of a Procfie. While
+KarmaNotes runs on Heroku as a webapp and thus makes use of a Procfile. While
not strictly necessary, KarmaWorld can use the same basic Procfile which is
convenient and consistent.
1. `source venv/bin/activate`
1. `pip install -r requirements.txt`
* on Debian systems, some packages are required for pip to succeed:
- * `apt-get install python-dev libpython-dev python-psycopg2 libmemcached-dev libffi-dev libssl-dev postgresql-server-dev-X.Y`
+ * `apt-get install python-dev libpython-dev python-psycopg2 libmemcached-dev libffi-dev libssl-dev postgresql-server-dev-X.Y`libxml2-dev libxslt-dev
1. `pip install -r requirements-dev.txt`
+
+## Configuration
+
+Make sure [External Service Dependencies](#external-service-dependencies) are
+satisfied. This includes running a local database and RabbitMQ instance as
+desired.
+
+ 1. configure `.env` as per [instructions](#external-service-dependencies)
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`
* `fetching_usde_csv` requires `7zip` to be installed for processing compressed
archives. On Debian-based systems, this entails `apt-get install p7zip-full`
+If using `DJANGO_SETTINGS_MODULE='karmaworld.settings.dev'` in `.env`, static
+file hosting should be done by local files. `DEFAULT_FILE_STORAGE` should be
+set to `django.core.files.storage.FileSystemStorage`.
+
+If using `DJANGO_SETTINGS_MODULE='karmaworld.settings.prod'` in `.env`, static
+file hosting is done by `DEFAULT_FILE_STORAGE` defined in `.env`.
+
## Run
Make sure you are inside your virtual environment (`source venv/bin/activate`).
projects / oweals / karmaworld.git / blobdiff