Zoom buttons on notes
[oweals/karmaworld.git] / 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