README.md 6.67 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 copy 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, 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
Run `python manage.py makemigrations` and `python manage.py migrate` to configure something called 'migrations', which allow you to make changes to the tables in your database without screwing up existing information. Then run `python manage.py createsuperuser` to create an admin account, using the same username and email as you'll access through CAS. Finally, run `python manage.py syncdb` to set up all the tables in your empty database.
Daniel W Bond's avatar
Daniel W Bond committed
118

119
## Starting up the test server
120

121 122 123
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
124 125 126

Head over to localhost:8000 and see the site!

127 128 129 130 131 132 133 134
## Deployment

### Docker

For server deployment, not for most local work

## To-do

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

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
138

139
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
140

141
## About Mason SRCT
Daniel W Bond's avatar
Daniel W Bond committed
142 143

**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.