README.md

   1 # KarmaWorld
   2 __Description__: A django application for sharing and uploading class notes.
   3
   4 __Copyright__: FinalsClub, a 501c3 non-profit organization
   5
   6 __License__: GPLv3 except where otherwise noted
   7
   8 __Contact__: info@karmanotes.org
   9
  10 v3.0 of the karmanotes.org website from the FinalsClub Foundation
  11
  12 # Purpose
  13
  14 KarmaNotes is an online database of college lecture notes.  KarmaNotes empowers college students to participate in the free exchange of knowledge.
  15
  16 # Pre-Installation
  17
  18 ## Code
  19
  20 Before doing anything, you'll need the code. Grab it from github.
  21
  22 Clone the project from the central repo using your github account:
  23
  24     git clone git@github.com:FinalsClub/karmaworld.git
  25
  26 If you aren't using a system setup for github, then grab the project with
  27 this command instead:
  28
  29     git clone https://github.com/FinalsClub/karmaworld.git
  30
  31 Generally speaking, this will create a subdirectory called `karmaworld` under
  32 the directory where the `git` command was run. This git repository directory
  33 will be referred to herein as `{project_root}`.
  34
  35 There might be some confusion as the git repository's directory will likely be
  36 called `karmaworld` (this is `{project_root}`), but there is also a `karmaworld`
  37 directory underneath that (`{project_root}/karmaworld`) alongside files like
  38 `fabfile.py` (`{project_root}/fabfile.py`) and `README.md`
  39 (`{project_root}/README.md`).
  40
  41 ## External Service Dependencies
  42
  43 Notice: This software makes use of external third party services which require
  44 accounts to access the service APIs. Without these third parties available,
  45 this software may require considerable overhaul. These services have
  46 API keys that you must provide to KarmaNotes as environment variables. The
  47 best way to do this is by using a `.env` file. Copy `.env.example` to `.env`
  48 and populate the fields as required.
  49
  50 ### Filepicker
  51 This software uses [Filepicker.io](https://www.inkfilepicker.com/) for uploading
  52 files. This requires an account with Filepicker.
  53
  54 Filepicker requires an additional third party file hosting site where it may
  55 send uploaded files. For this project, we have used Amazon S3.
  56
  57 Your Filepicker API key must be provided in `FILEPICKER_API_KEY` and your
  58 secret in `FILEPICKER_SECRET`.
  59
  60 ### Amazon S3
  61
  62 #### for Filepicker
  63 This software uses [Amazon S3](http://aws.amazon.com/s3/) as a third party file
  64 hosting site. The primary use case is a destination for Filepicker files. The
  65 software won't directly need any S3 information for this use case; it will be
  66 provided directly to Filepicker.
  67
  68 #### for Static File hosting
  69 A secondary use case for S3 is hosting static files. The software will need to
  70 update static files on the S3 bucket. In this case, the software will need the
  71 S3 bucket name, access key, and secret key.
  72
  73 The code assumes S3 is used for static files in a production environment. To
  74 obviate the need for hosting static files through S3 (noting that it still might
  75 be necessary for Filepicker), a workaround was explained [in this Github ticket](https://github.com/FinalsClub/karmaworld/issues/192#issuecomment-30193617).
  76
  77 That workaround is repeated here. Make the following changes to
  78 `{project_root}/karmaworld/settings/prod.py`:
  79
  80 1. comment out everything about static_s3 from imports
  81 2. comment out storages from the `INSTALLED_APPS`
  82 3. change `STATIC_URL` to `'/assets/'`
  83 4. comment out the entire storages section (save for part of `INSTALLED_APPS` and `STATIC_URL`)
  84 5. add this to the nginx config:
  85
  86     location /assets/ {
  87         root /var/www/karmaworld/karmaworld/;
  88     }
  89
  90 ### IndexDen
  91 KarmaNotes uses IndexDen to create a searchable index of all the notes
  92 in the system. Create an free IndexDen account at [their homepage](http://indexden.com/).
  93 You will be given a private URL that accesses your IndexDen account.
  94 Set the environment variable INDEXDEN_PRIVATE_URL to your private URL and
  95 INDEXDEN_INDEX to the name
  96 of the index you want KarmaNotes to use. The index will be created automatically when
  97 KarmaNotes is run if it doesn't already exist. For example,
  98 ```
  99 INDEXDEN_PRIVATE_URL='http://:secretsecret@secret.api.indexden.com'
 100 INDEXDEN_INDEX='karmanotes_something_something'
 101 ```
 102
 103 ### Google Drive
 104 This software uses [Google Drive](https://developers.google.com/drive/) to
 105 convert documents to and from various file formats.
 106
 107 A Google Drive service account with access to the Google Drive is required.
 108 This may be done with a Google Apps account with administrative privileges, or ask
 109 your business sysadmin.
 110
 111 These are the instructions to create a Google Drive service account:
 112 https://developers.google.com/drive/delegation
 113
 114 When completed, set the environment variables `GOOGLE_CLIENT_SECRETS`,
 115 `GOOGLE_USER`, and `GOOGLE_SERVICE_KEY_BASE64`.
 116
 117 ### Twitter
 118
 119 Twitter is used to post updates about new courses. Access to the Twitter API
 120 will be required for this task.
 121
 122 If this Twitter feature is desired, the consumer key and secret as well as the
 123 access token key and secret are needed by the software.
 124
 125 If the required environment variables are not found, then no errors will occur
 126 and no tweets will be posted.
 127
 128 To set this up, create a new Twitter application at https://dev.twitter.com/apps/new.
 129 Make sure this application has read/write access. Generate an access token. Go to your
 130 OAuth settings, and grab the "Consumer key", "Consumer secret", "Access token", and
 131 "Access token secret". Set these to the variables `TWITTER_CONSUMER_KEY`,
 132 `TWITTER_CONSUMER_SECRET`, `TWITTER_ACCESS_TOKEN_KEY`, `TWITTER_ACCESS_TOKEN_SECRET`
 133
 134
 135 ### SSL Certificate
 136
 137 If you wish to host your system publicly, you'll need an SSL certificate
 138 signed by a proper authority.
 139
 140 If you are working on local system for development, a self signed certificate
 141 will suffice. There are plenty of resources available for learning how to
 142 create one, so that will not be detailed here. Note that the Vagrant file will
 143 automatically generated a self signed certificate within the virtual machine.
 144
 145 The certificate should be installed using nginx.
 146
 147 # Local Install
 148
 149 KarmaNotes is a Heroku application. Download the [Heroku toolbelt](https://toolbelt.heroku.com/).
 150
 151 To run KarmaNotes locally, do `foreman start`. Before your first run, there are
 152 a few setup steps:
 153   1. `virtualenv venv`
 154   1. `source venv/bin/activate`
 155   1. `pip install -r requirements.txt`
 156   1. `pip install -r requirements-dev.txt`
 157   1. `foreman run python manage.py syncdb --migrate --noinput`
 158   1. `foreman run python manage.py createsuperuser`
 159   1. `foreman run python manage.py fetch_usde_csv ./schools.csv`
 160   1. `foreman run python manage.py import_usde _csv ./schools.csv`
 161   1. `foreman run python manage.py sanitize_usde_schools`
 162
 163
 164 # Heroku Install
 165
 166 KarmaNotes is a Heroku application. Download the [Heroku toolbelt](https://toolbelt.heroku.com/).
 167
 168 To run KarmaNotes on Heroku, do `heroku create` and `git push heroku master` as typical
 169 for a Heroku application. This will deploy KarmaNotes to Heroku with a supporting buildpack.
 170
 171 You will need to import the US Department of Education's list of accredited schools.
 172    1. Fetch USDE schools with
 173       `heroku run python manage.py fetch_usde_csv ./schools.csv`
 174    1. Upload the schools into the database with
 175       `heroku run python /manage.py import_usde _csv ./schools.csv`
 176    1. Clean up redundant information with
 177       `heroku run python /manage.py sanitize_usde_schools`
 178
 179
 180 # Django Database management
 181
 182 ## South
 183
 184 We have setup Django to use
 185 [south](http://south.aeracode.org/wiki/QuickStartGuide) for migrations. When
 186 changing models, it is important to run
 187 `foreman run python manage.py schemamigration` which will create a migration
 188  to reflect the model changes into the database. These changes can be pulled
 189 into the database with `foreman run python manage.py migrate`.
 190
 191 Sometimes the database already has a migration performed on it, but that
 192 information wasn't told to south. There are subtleties to the process which
 193 require looking at the south docs. As a tip, start by looking at the `--fake`
 194 flag.
 195
 196 # Assets from Third Parties
 197
 198 A number of assets have been added to the repository which come from external
 199 sources. It would be difficult to keep a complete list in this README and keep
 200 it up to date. Software which originally came from outside parties can
 201 generally be found in `karmaworld/assets`.
 202
 203 Additionally, all third party Python projects (downloaded and installed with
 204 pip) are listed in these files:
 205
 206 * `requirements.txt`
 207 * `requirements-dev.txt`
 208
 209 # Thanks
 210
 211 * KarmaNotes.org is a project of the FinalsClub Foundation with generous funding from the William and Flora Hewlett Foundation
 212
 213 * Also thanks to [rdegges](https://github.com/rdegges/django-skel) for the django-skel template