2 __Description__: A django application for sharing and uploading class notes.
4 __Copyright__: FinalsClub, a 501c3 non-profit organization
6 __License__: GPLv3 except where otherwise noted
8 __Contact__: info@karmanotes.org
10 v3.0 of the karmanotes.org website from the FinalsClub Foundation
17 KarmaNotes is an online database of college lecture notes. KarmaNotes empowers college students to participate in the free exchange of knowledge.
21 Clone the project from the central repo using your github account:
23 git clone git@github.com:FinalsClub/karmaworld.git
25 If you aren't using a system setup for github, then grab the project with
28 git clone https://github.com/FinalsClub/karmaworld.git
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}`.
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`).
40 ## External Service Dependencies
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.
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.
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.
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`:
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:
58 root /var/www/karmaworld/karmaworld/;
62 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.
66 If you need to setup the project for development, it is highly recommend that
67 you grab an existing development virtual machine or create one yourself.
68 Configure the virtual machine for production with the steps shown in the
69 next section (Production Install). Instructions for creating a virtual machine
72 1. Install [VirtualBox](http://www.virtualbox.com/)
74 1. Install [vagrant](http://www.vagrantup.com/) 1.3 or higher
76 1. Use Vagrant to create the virtual machine.
77 * While in `cd {project_root}`, type `vagrant up`
81 If you're starting to work on this project and you need it setup for production,
82 follow the steps below.
84 1. Ensure the following are installed:
86 * `PostgreSQL` (server and client)
90 * `virtualenv` and `virtualenvwrapper`
92 1. Generate a PostgreSQL database and a role with read/write permissions.
93 * For Debian, these instructions are helpful: https://wiki.debian.org/PostgreSql
95 1. Modify configuration files.
96 * There are settings in `{project_root}/karmaworld/settings/dev.py`
97 * There are additional configuration options for external dependencies
98 under `{project_root}/karmaworld/secret/`.
99 * Copy files with the example extension to the corresponding filename
100 without the example extension (e.g.
101 `cp filepicker.py.example filepicker.py`)
102 * Modify those files.
103 * Ensure `PROD_DB_USERNAME`, `PROD_DB_PASSWORD`, and `PROD_DB_NAME`
104 inside `db_settings.py` match the role, password, and database
105 generated in the previous step.
106 * Ensure *.py in `secret/` are never added to the git repo. (.gitignore
107 should help warn against taking this action)
109 1. Make sure that /var/www exists, is owned by the www-data group, and that
110 the user is a member of the www-data group.
112 1. Make sure that you're in the root of the project that you just cloned and
115 fab -H 127.0.0.1 first_deploy
117 This will make a virtualenv, install the development dependencies and create
120 1. Now you can run ``./manage.py runserver`` and visit the site in the browser.
122 # Accessing the Vagrant Virtual Machine
124 ## Connecting to the VM via SSH
125 If you have installed a virtual machine using `vagrant up`, you can connect
126 to it by running `vagrant ssh` from `{project_root}`.
128 ## Connecting to the development website on the VM
129 To access the website running on the VM, point your browser at
130 http://localhost:6659/ using your host computer.
132 Port 6659 on your local machine is set to forward to the VM's port 80.
134 Fun fact: 6659 was chosen because of OM (sanskrit) and KW (KarmaWorld) on a
137 ## Updating the VM code repository
138 Once connected to the virtual machine by SSH, you will see `karmaworld` in
139 the home directory. That is the `{project_root}` in the virtual machine.
141 `cd karmaworld` and then use `git fetch; git merge` and/or `git pull origin` as
144 The virtual machine's code repository is set to use your host machine's
145 local repository as the origin. So if you make changes locally and commit them,
146 without pushing them anywhere, your VM can pull those changes in for testing.
148 This may seem like duplication. It is. The duplication allows your host machine
149 to maintain git credentials and manage repository access control so that your
150 virtual machine doesn't need sensitive information. Your virtual machine simply
151 pulls from the local repository on your local file system without needing
154 ## Other Vagrant commands
155 Please see [vagrant documentation](http://docs.vagrantup.com/v2/cli/index.html)
156 for more information on how to use the vagrant CLI to manage your development
162 * KarmaNotes.org is a project of the FinalsClub Foundation with generous funding from the William and Flora Hewlett Foundation
164 * Also thanks to [rdegges](https://github.com/rdegges/django-skel) for the django-skel template