README.md 13.6 KB
Newer Older
1
# ROOMLIST
Daniel W Bond's avatar
Daniel W Bond committed
2

3
Roomlist is a secure, privacy-oriented service for Mason students to find their on-campus neighbors.
Daniel W Bond's avatar
Daniel W Bond committed
4

5
## On Contributing
Daniel W Bond's avatar
Daniel W Bond committed
6

7
Roomlist welcomes all the help it can get. Even if you don't feel like you can be helpful the more technical aspects, we definitely need designers, technical writers, and testers.
Daniel W Bond's avatar
Daniel W Bond committed
8
9
10

There are many things that can be done with this project (see the "To Do" section), but sometimes it's the small things that count, so don't be afraid of contributing just a small spelling mistake.

Jason D Yeomans's avatar
Jason D Yeomans committed
11
If you need help at all please contact a SRCT member. We want people to contribute, so if you are struggling, or just want to learn we are more than willing to help.
Daniel W Bond's avatar
Daniel W Bond committed
12

13
The project manager for this project is [Jason Yeomans](jyeoman2@gmu.edu), and a lead developer is [Daniel Bond](dbond2@gmu.edu).
Daniel W Bond's avatar
Daniel W Bond committed
14
15
16

Please visit the [SRCT Wiki](http://wiki.srct.gmu.edu/) for more information on this and other SRCT projects, along with other helpful links and tutorials.

17
## Setting everything up for development
Daniel W Bond's avatar
Daniel W Bond committed
18

19
These instructions are for Ubuntu and Debian, or related Linux distributions. (If you'd like to help write the instructions for Mac OSX, please do!)
Daniel W Bond's avatar
Daniel W Bond committed
20

21
### Prerequisities
Daniel W Bond's avatar
Daniel W Bond committed
22

23
24
25
26
27
28
29
30
31
32
33
34
First, install python, pip, and git on your system. Python is the programming language used for Django, the web framework used by Roomlist. 'Pip' is the python package manager. Git is the version control system used for SRCT projects.

Open a terminal and run the following commands.

`sudo apt-get update`

This retrieves links to the most up-to-date and secure versions of your packages. Next, with

`sudo apt-get install python python-dev python-pip git`

you install python and git.

35
Now, we're going to clone down a copy of the Roomlist codebase from git.gmu.edu, the SRCT code respository.
36
37
38
39
40
41
42

Configure your ssh keys by following the directions at git.gmu.edu/help/ssh/README.

Now, on your computer, navigate to the directory in which you want to download the project (perhaps one called development/ or something similar), and run

`git clone git@git.gmu.edu:srct/roomlist.git`

43
44
45
46
47
48
49
50
51
52
### Package Installation

Next, install these packages from the standard repositories

`$ sudo apt-get install libldap2-dev mysql-server mysql-client libmysqlclient-dev python-mysqldb libsasl2-dev libjpeg-dev redis-server`

If prompted to install additional required packages, install those as well.

When prompted to set your mysql password, it's advisable to set it as the same as your normal superuser password.

53
54
### The Virtual Environment

55
Virtual environments are used to keep separate project packages from the main computer, so you can use different versions of packages across different projects and also ease deployment server setup.
56
57
58
59
60
61
62
63
64
65
66
67
68

It's often recommended to create a special directory to store all of your virtual environments together, but some prefer keeping their virtual environment in the top level of their project's director. If you choose the latter, make sure to keep the virtual environment folders out of version control.

(For example, `mkdir ~/venv`, `cd ~/venv`)

Run `sudo pip install virtualenv`

to install virtualenv system-wide, and then run

`virtualenv roomlist`

in your virtual environment directory to create your virtual environment. Activate it by typing

69
`source roomlist/bin/activate`
70
71
72
73
74

If you ever need to exit your virtual environment, simply run

`deactivate`

75
Now, the packages you need to install for Roomlist are in in the top level of the project's directory structure. Run
76
77
78
79
80
81

`pip install -r requirements.txt`

to in install all of the packages needed for the project.

### Creating the Database
Daniel W Bond's avatar
Daniel W Bond committed
82

83
84
Roomlist is configured for using a mysql database, (though you can change this in config.py)
By default, the database is called 'roomlist' in the configurations, and the user, 'roommate'.
85

86
Load up the mysql shell by running
87

88
``mysql -u root -p``
89

90
and putting in your mysql password.
91

92
Create the database by running
93

94
``CREATE DATABASE roomlist;``
95

96
You can choose a different name for your database. Double check your database was created
97

98
``SHOW DATABASES;``
99

100
Though you can use an existing user to access this database, here's how to create a new user and give them the necessary permissions to your newly created database.
101

102
103
``CREATE USER 'roommate'@'localhost' IDENTIFIED BY 'password';``
For local development, password strength is less important, but use a strong passphrase for deployment. You can choose a different username.
104

105
106
``GRANT ALL ON roomlist.* TO 'roommate'@'localhost';``
This allows your database user to create all the tables it needs on the bookshare database. (Each model in each app's models.py is a separate table, and each attribute a column, and each instance a row.)
107

108
109
``GRANT ALL ON test_roomlist.* TO 'roommate'@'localhost';`` ``FLUSH PRIVILEGES;``
When running test cases, django creates a test database so your 'real' database doesn't get screwed up. This database is called 'test_' + whatever your normal database is named. Note that for permissions it doesn't matter that this database hasn't yet been created.
110

111
The .\* is to grant access all tables in the database, and 'flush privileges' reloads privileges to ensure that your user is ready to go.
112

113
Exit the mysql shell by typing `exit`.
114

115
Now, to configure your newly created database with the project settings, and set up your project's cryptographic key, copy the secret.py.template in settings/ to secret.py. Follow the comment instructions provided in each file to set your secret key and database info.
116

117
Also copy config.py.template to config.py. You won't need to make any changes here off the bat. See more information about this file under the 'Deployment' section.
118

119
Run `python manage.py makemigrations` to create the tables and rows and columns for your database. This command generates sql code based on your database models. If you don't see output noting the creation of a number of models, add the app name to the end of the command, e.g. `python manage.py makemigrations housing`.
120

121
122
123
124
125
126
127
128
129
Then run `python manage.py migrate` to execute that sql code and set up your database. Migrations also track how you've changed your models over the life of your database, which allows you to make changes to your tables without screwing up existing information.

Finally, run `python manage.py createsuperuser` to create an admin account, using the same username and email as you'll access through CAS. This means your 'full' email address, for instance gmason@masonlive.gmu.edu. Your password will be handled through CAS, so you can just use 'password' here.

(If you accidentally skip this step, you can run `python manage.py shell` and edit your user from there.)

## Loading in demo data

The project includes a number of json files with demo data to load into the database, for Majors and also for all freshman housing. Run `python manage.py loaddata accounts/major_fixtures.json`. You'll see output saying 'Installed 79 objects from 1 fixture(s) if all goes smoothly. Follow this with `python manage.py loaddata housing/initial_data.json` and a sizeable number of housing objects should be 'installed'.
Daniel W Bond's avatar
Daniel W Bond committed
130

131
132
133
134
## Starting search

To start off indexing your models for searching, run `python manage.py update_index`.

135
## Starting up the test server
136

137
138
139
With your virtual environment active, run

`python manage.py runserver` in the directory with `manage.py`
Daniel W Bond's avatar
Daniel W Bond committed
140
141
142

Head over to localhost:8000 and see the site!

143
144
## Configuring the Social Media Applications

145
146
147
148
Social media authentication is provided through a package called [django-allauth](http://django-allauth.readthedocs.org/en/stable/installation.html). You can refer to those documentation pages for more information.

What we're trying to accomplish with social media authentication is to verify users are linking to accounts they actually control. If we trusted users sufficiently to not type in gibberish or link to twitter.com/realDonaldTrump, we could provide a character field for each site.

149
150
Head over to localhost:8000/admin. Under 'Social Accounts', click on 'Social Applications'. Click 'Add social application' in the upper right hand corner. Start off by adding Facebook.

151
152
153
154
155
156
157
158
159
160
161
162
163
164
To fill in the name, id, key, and site for Facebook, and for all of the social media sites, you'll need to become a Developer for the site in question.

Navigate to, for example, the Facebook web login [documentation page](https://developers.facebook.com/docs/facebook-login/web). On the toolbar across the top of the page, you'll see a tab called 'My Apps'. Hovering over it, you'll see the option to Register as a Developer. Click the link, accept the Facebook platform and privacy policies, and you'll be ready to go. Depending on how fleshed out your profile page is, you may be prompted for more information (such as a phone number).

On the page you'll be [redirected to](https://developers.facebook.com/quickstarts/), select the web app option. You'll be prompted to type the name of your new app. Go with something simple, like 'roomlist'. A dropdown will show an option to create a new app. Put Education as the category. Skip over 'namespace': that's used for specifically defining the app's name via Facebook's API. For the line labeled 'Site URL', type 'localhost:8000'. Hit 'next' and then click the link above the listed functionality that says 'Skip to Developer Dashboard'. (For the record, we're implementing the Login functionality.)

After you click 'create app ID' and successfully complete a captcha, you'll be shown your app's dashboard. The two things you need on roomlist are right up at the top, the App ID and the App Secret.

The user interface might be a bit different, particularly if you've done development with Facebook before, and some of these fields you may need to add after you've created the app. You may need to click 'Add Platform' from the Settings page of your app's Dashboard.

Back on the Django admin page, start filling in fields. App Name to Name, App ID to Client id, App Secret to Secret Key. The 'Sites' section is a security measure you can have in place to make sure that your app is only called from the urls you expect, and is what you put in for the 'Site URL' for the Facebook configuration.

Under 'Available Sites', click the little green plus button and add a new site. The Domain Name will be '127.0.0.1' and the Display Name 'localhost'. By default, Django has already gone to the trouble of creating 'example.com' as a site. Move example.com back to available sites and make sure 127.0.0.1 is added to Chosen Sites.

165
166
By default, example.com is the first site. We'll add our site id, localhost. In settings.py, this is already accounted for; the default there is SITE_ID = 2.

167
Something you'll need to carefully specify is the callback (or redirect) url. This is where your user is sent once they have successfully authenticated with the outside social media site.
168
169
170
171
172

Let's add localhost to our Available sites.

Now, to Instagram.

173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
Instagram actually asks you what you want to build and then will choose to give you access or not. Cross your fingers and let's begin the process.

Sign up as developer. Your website (localhost:8000) phone number (if you haven't already given it to Instagram, see above) and what you want to build with the API. 'Verify users are linking to social media accounts they in fact control.

Register Your Application.

Manage clients.

Register new client ID.

Application name

Description

Company name(?) SRCT
You must enter an absolute URI that starts with http:// or https://
Submission error: all fields are required.
Website URL localhost:8000
Valid redirect urls: localhost:8000 (tab after to make it a link)
http://localhost:8000/accounts/instagram/login/callback/
contact email
Captcha

196
197
Next, to Twitter.

198
199
200
201
202
203
Must actually be unique

Use http://127.0.0.1:8000/

Permissions: Read only

204
205
Finally, to Google.

206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
Google's auth setup process is unquestionably the most confusing of the bunch, and yet we proceed, despite the number of students who will link their Google+ page will likely be no more than four.

Project name-- google gives you the project name

enable and manage apis

google+

credentials

add credentials

oauth2 client id
web application
name
authorized javascript origins
http://127.0.0.1:8000
authorized redirect urls
with trailing slash localhost

you'll see them in a popup...

roomlist or generated roomlist?

project consent screen
email address
product name shown to users

domain verification

your site must be registered on the search console

watch out for trailing spaces!!

240
241
242
243
### Notes on Cacheing

Roomlist's urls are set to be cached for periods of time set so that ordinary user experience will not be impacted, but a substantial load will be lifted from a deployment server. However, this can be annoying when you're making and want to check small changes rapidly on development. You can edit the respective apps' urls.py files and remove the cacheing configurations, but make sure that you do not include such edits in any pushes!

244
245
## Deployment

246
247
A number of deployment-related settings have been moved from settings.py to config.py in settings/ for ease of use. Make sure to never have DEBUG mode on when running your project in deployment.

248
249
250
251
252
253
### Docker

For server deployment, not for most local work

## To-do

254
The list of to-do items is kept track of on the gitlab Roomlist issues page. https://git.gmu.edu/srct/roomlist/issues
255
256

Each issue includes details about the bugs and features, and links to documentation and tutorials to help with fixing that specific issue.
Daniel W Bond's avatar
Daniel W Bond committed
257

258
Contact the project manager or any of its developers if you'd like help picking an unassigned issue.
Daniel W Bond's avatar
Daniel W Bond committed
259

260
## About Mason SRCT
Daniel W Bond's avatar
Daniel W Bond committed
261
262

**S**tudent - **R**un **C**omputing and **T**echnology (*SRCT*, pronounced "circuit") is a student organization at George Mason University which enhances student computing at Mason. SRCT establishes and maintains systems which provide specific services for Mason's community.