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
  13
  14
  15 # Purpose
  16
  17 KarmaNotes is an online database of college lecture notes.  KarmaNotes empowers college students to participate in the free exchange of knowledge.
  18
  19 # Pre-Installation
  20
  21 Clone the project from the central repo using your github account:
  22
  23     git clone git@github.com:FinalsClub/karmaworld.git
  24
  25 If you aren't using a system setup for github, then grab the project with
  26 this command instead:
  27
  28     git clone https://github.com/FinalsClub/karmaworld.git
  29
  30 Generally speaking, this will create a subdirectory called `karmaworld` under
  31 the directory where the `git` command was run. This git repository directory
  32 will be referred to herein as `{project_root}`.
  33
  34 There might be some confusion as the git repository's directory will likely be
  35 called `karmaworld` (this is `{project_root}`), but there is also a `karmaworld`
  36 directory underneath that (`{project_root}/karmaworld`) alongside files like
  37 `fabfile.py` (`{project_root}/fabfile.py`) and `README.md`
  38 (`{project_root}/README.md`).
  39
  40 ## External Service Dependencies
  41
  42 Notice: 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.
  43
  44 ### Filepicker
  45 This software uses [Filepicker.io](https://www.inkfilepicker.com/) for uploading files. This requires an account with Filepicker and some additional third party file hosting site where Filepicker may send uploaded files.
  46
  47 ### Amazon S3
  48 This software uses [Amazon S3](http://aws.amazon.com/s3/) as a third party file hosting site. The primary use case is a destination for Filepicker files.  A secondary use case is hosting static files.
  49
  50 To obviate the need for hosting static files through S3 (noting it still serves a different purpose), see the workaround noted [in this Github ticket](https://github.com/FinalsClub/karmaworld/issues/192#issuecomment-30193617). For good measure, that workaround is repeated here. Make the following changes to `karmaworld/settings/prod.py`:
  51
  52 1. comment out everything about static_s3 from imports
  53 2. comment out storages from the `INSTALLED_APPS`
  54 3. change `STATIC_URL` to `'/assets/'`
  55 4. comment out the entire storages section (save for part of `INSTALLED_APPS` and `STATIC_URL`)
  56 5. add this to the nginx config:
  57
  58     location /assets/ {
  59         root /var/www/karmaworld/karmaworld/;
  60     }
  61
  62 ### Google Drive
  63 This software uses [Google Drive](https://developers.google.com/drive/) to convert documents to and from various file formats. Google credentials will be required as well as a Google Drive account which has been registered with the Google Cloud Console.
  64
  65 # Development Install
  66
  67 If you need to setup the project for development, it is highly recommend that
  68 you grab an existing development virtual machine or create one yourself.
  69 Configure the virtual machine for production with the steps shown in the
  70 next section (Production Install). Instructions for creating a virtual machine
  71 follow:
  72
  73 1. Install [VirtualBox](http://www.virtualbox.com/)
  74
  75 1. Install [vagrant](http://www.vagrantup.com/) 1.3 or higher
  76
  77 1. Configure external dependencies on the host machine:
  78     * Under `{project_root}/karmaworld/secret/`:
  79         1. Copy files with the example extension to the corresponding filename
  80           without the example extension (e.g.
  81           `cp filepicker.py.example filepicker.py`)
  82         1. Modify those files, but ignore `db_settings.py` (Vagrant takes care of that one)
  83         1. Ensure *.py in `secret/` are never added to the git repo. (.gitignore
  84           should help warn against taking this action)
  85
  86 1. Use Vagrant to create the virtual machine.
  87     * While in `cd {project_root}`, type `vagrant up`
  88
  89 1. Connect to the VM with `vagrant ssh`
  90
  91 1. While connected to the VM with SSH, type `cd karmanotes` and then follow
  92     the instructions starting in Production Install about running
  93     `fab -H 127.0.0.1 first_deploy`.
  94
  95 1. Once the above instructions are completed, port 80 on the VM will be hosted
  96     as port 6659 on the host system. From the host system, fire up your
  97     favorite browser and point it at `localhost:6659`.
  98
  99 # Production Install
 100
 101 If you're starting to work on this project and you need it setup for production,
 102 follow the steps below.
 103
 104 1. Ensure the following are installed:
 105    * `git`
 106    * `PostgreSQL` (server and client)
 107    * `nginx`
 108    * `Python`
 109    * `PIP`
 110    * `virtualenv` and `virtualenvwrapper`
 111
 112 1. Generate a PostgreSQL database and a role with read/write permissions.
 113    * For Debian, these instructions are helpful: https://wiki.debian.org/PostgreSql
 114
 115 1. Modify configuration files.
 116    * There are settings in `{project_root}/karmaworld/settings/dev.py`
 117    * There are additional configuration options for external dependencies
 118      under `{project_root}/karmaworld/secret/`.
 119        * Copy files with the example extension to the corresponding filename
 120          without the example extension (e.g.
 121          `cp filepicker.py.example filepicker.py`)
 122        * Modify those files.
 123            * Ensure `PROD_DB_USERNAME`, `PROD_DB_PASSWORD`, and `PROD_DB_NAME`
 124              inside `db_settings.py` match the role, password, and database
 125              generated in the previous step.
 126        * Ensure *.py in `secret/` are never added to the git repo. (.gitignore
 127          should help warn against taking this action)
 128
 129 1. Make sure that /var/www exists, is owned by the www-data group, and that
 130    the user is a member of the www-data group.
 131
 132 1. Make sure that you're in the root of the project that you just cloned and
 133    run
 134
 135         fab -H 127.0.0.1 first_deploy
 136
 137    This will make a virtualenv, install the development dependencies and create
 138    the database tables.
 139
 140    During this process, you will be queried to create a Django site admin.
 141    Provide information. You will be asked to remove duplicate schools. Respond
 142    with yes.
 143
 144 1. If everything went well, gunicorn should be running the website on port 8000
 145     and nginx should be serving gunicorn on port 80.
 146
 147 # Accessing the Vagrant Virtual Machine
 148
 149 ## Connecting to the VM via SSH
 150 If you have installed a virtual machine using `vagrant up`, you can connect
 151 to it by running `vagrant ssh` from `{project_root}`.
 152
 153 ## Connecting to the development website on the VM
 154 To access the website running on the VM, point your browser at
 155 http://localhost:6659/ using your host computer.
 156
 157 Port 6659 on your local machine is set to forward to the VM's port 80.
 158
 159 Fun fact: 6659 was chosen because of OM (sanskrit) and KW (KarmaWorld) on a
 160 phone: 66 59.
 161
 162 ## Updating the VM code repository
 163 Once connected to the virtual machine by SSH, you will see `karmaworld` in
 164 the home directory. That is the `{project_root}` in the virtual machine.
 165
 166 `cd karmaworld` and then use `git fetch; git merge` and/or `git pull origin` as
 167 desired.
 168
 169 The virtual machine's code repository is set to use your host machine's
 170 local repository as the origin. So if you make changes locally and commit them,
 171 without pushing them anywhere, your VM can pull those changes in for testing.
 172
 173 This may seem like duplication. It is. The duplication allows your host machine
 174 to maintain git credentials and manage repository access control so that your
 175 virtual machine doesn't need sensitive information. Your virtual machine simply
 176 pulls from the local repository on your local file system without needing
 177 credentials, etc.
 178
 179 ## Other Vagrant commands
 180 Please see [vagrant documentation](http://docs.vagrantup.com/v2/cli/index.html)
 181 for more information on how to use the vagrant CLI to manage your development
 182 VM.
 183
 184 Thanks
 185 ======
 186
 187 * KarmaNotes.org is a project of the FinalsClub Foundation with generous funding from the William and Flora Hewlett Foundation
 188
 189 * Also thanks to [rdegges](https://github.com/rdegges/django-skel) for the django-skel template