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 # Development Install
  41
  42 If you need to setup the project for development, it is highly recommend that
  43 you grab an existing development virtual machine or create one yourself.
  44 Configure the virtual machine for production with the steps shown in the
  45 next section (Production Install). Instructions for creating a virtual machine
  46 follow:
  47
  48 1. Install [VirtualBox](http://www.virtualbox.com/)
  49
  50 1. Install [vagrant](http://www.vagrantup.com/) 1.3 or higher
  51
  52 1. Use Vagrant to create the virtual machine.
  53     * While in `cd {project_root}`, type `vagrant up`
  54
  55 # Production Install
  56
  57 If you're starting to work on this project and you need it setup for production,
  58 follow the steps below.
  59
  60 1. Ensure the following are installed:
  61    * `git`
  62    * `PostgreSQL` (server and client)
  63    * `nginx`
  64    * `Python`
  65    * `PIP`
  66    * `virtualenv` and `virtualenvwrapper`
  67
  68 1. Generate a PostgreSQL database and a role with read/write permissions.
  69    * For Debian, these instructions are helpful: https://wiki.debian.org/PostgreSql
  70
  71 1. Modify configuration files.
  72    * There are settings in `{project_root}/karmaworld/settings/dev.py`
  73    * There are additional configuration options for external dependencies
  74      under `{project_root}/karmaworld/secret/`.
  75        * Copy files with the example extension to the corresponding filename
  76          without the example extension (e.g.
  77          `cp filepicker.py.example filepicker.py`)
  78        * Modify those files.
  79            * Ensure `PROD_DB_USERNAME`, `PROD_DB_PASSWORD`, and `PROD_DB_NAME`
  80              inside `db_settings.py` match the role, password, and database
  81              generated in the previous step.
  82        * Ensure *.py in `secret/` are never added to the git repo. (.gitignore
  83          should help warn against taking this action)
  84
  85 1. Make sure that /var/www exists, is owned by the www-data group, and that
  86    the user is a member of the www-data group.
  87
  88 1. Make sure that you're in the root of the project that you just cloned and
  89    run
  90
  91         fab -H 127.0.0.1 first_deploy
  92
  93    This will make a virtualenv, install the development dependencies and create
  94    the database tables.
  95
  96 1. Now you can run ``./manage.py runserver`` and visit the site in the browser.
  97
  98 # Accessing the Vagrant Virtual Machine
  99
 100 ## Connecting to the VM via SSH
 101 If you have installed a virtual machine using `vagrant up`, you can connect
 102 to it by running `vagrant ssh` from `{project_root}`.
 103
 104 ## Connecting to the development website on the VM
 105 To access the website running on the VM, point your browser at
 106 http://localhost:6659/ using your host computer.
 107
 108 Port 6659 on your local machine is set to forward to the VM's port 80.
 109
 110 Fun fact: 6659 was chosen because of OM (sanskrit) and KW (KarmaWorld) on a
 111 phone: 66 59.
 112
 113 ## Updating the VM code repository
 114 Once connected to the virtual machine by SSH, you will see `karmaworld` in
 115 the home directory. That is the `{project_root}` in the virtual machine.
 116
 117 `cd karmaworld` and then use `git fetch; git merge` and/or `git pull origin` as
 118 desired.
 119
 120 The virtual machine's code repository is set to use your host machine's
 121 local repository as the origin. So if you make changes locally and commit them,
 122 without pushing them anywhere, your VM can pull those changes in for testing.
 123
 124 This may seem like duplication. It is. The duplication allows your host machine
 125 to maintain git credentials and manage repository access control so that your
 126 virtual machine doesn't need sensitive information. Your virtual machine simply
 127 pulls from the local repository on your local file system without needing
 128 credentials, etc.
 129
 130 ## Other Vagrant commands
 131 Please see [vagrant documentation](http://docs.vagrantup.com/v2/cli/index.html)
 132 for more information on how to use the vagrant CLI to manage your development
 133 VM.
 134
 135 Thanks
 136 ======
 137
 138 * KarmaNotes.org is a project of the FinalsClub Foundation with generous funding from the William and Flora Hewlett Foundation
 139
 140 * Also thanks to [rdegges](https://github.com/rdegges/django-skel) for the django-skel template