README.md 8.73 KB
Newer Older
1
# SRCT Bookshare
Daniel W Bond's avatar
Daniel W Bond committed
2
3
4

SRCT Bookshare is a platform for GMU students to buy and sell their textbooks.

5
## On Contributing
6

7
Bookshare is still in its childhood and needs all the help it can get. Even if you don't feel like you can be helpful with the more technical aspects, we definitely need designers, technical writers, and testers.
8
9
10
11
12

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.

If you need help at all please contact any SRCT member. We want people to contribute, so if you are struggling, or just want to learn we are more than willing to help.

Jean Michel Rouly's avatar
Jean Michel Rouly committed
13
The project lead for this project is **Eric Cawi** ( *ecawi@gmu.edu* ) and lead developer is **Michel Rouly** ( *jrouly@gmu.edu* ).
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
18
## Setting everything up for development

Daniel W Bond's avatar
Daniel W Bond committed
19
20
These instructions are for Debian and Ubuntu. Server configuration information adopted from 
Michel Rouly's [research-questions](https://github.com/jrouly/research-questions) documentation.
21
22
23
24
25
26
27
28

### Prerequisites

First, install python, Pip, and Git on your system. Python is the programming language used by Django. '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`
29
30

`sudo apt-get install python python-dev`python-pip git`
31
32
33

Next, we're going to download a copy of the bookshare codebase from git.gmu.edu, the SRCT code repository.

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

Now on your computer, navigate to the directory you in which you want to download the project, and run
37
38
39
40
41
42
43

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

### Package Installation

Next, install these packages from the standard repositories

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

Daniel W Bond's avatar
Daniel W Bond committed
46
If prompted to install additional required packages, install those as well.
47

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

50
51
### The Virtual Environment

Daniel W Bond's avatar
Daniel W Bond committed
52
Virtual environments are used to keep separate a projects packages from the main computer system, so you can use different versions of packages across different projects and ease deployment server setup.
Daniel W Bond's avatar
Daniel W Bond committed
53

54
55
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 directory. If you choose the latter, make sure to keep the virtual environment folders out of version control.

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

58
59
60
61
62
63
Run `sudo pip install virtualenv`

to install virtualenv system-wide, and then run

`virtualenv bookshare`

Daniel W Bond's avatar
Daniel W Bond committed
64
in your virtualenvironment directory to create your virtualenvironment. Activate it by running
65
66
67
68
69
70
71
72
73
74

`source bookshare/bin/activate`

in the virtualenvironment directory.

Now, the packages you need to install for bookshare are in the top level of the project's directory structure. Run

`pip install -r requirements.txt`

to install all of the packages needed for the project.
Daniel W Bond's avatar
Daniel W Bond committed
75

76
77
### Creating the Database

Daniel W Bond's avatar
Daniel W Bond committed
78
79
Bookshare is configured for using a mysql database, (though you can change this in settings.py and secret.py.)
By default, the database is called 'bookshare' in the configurations, and the user, 'bookworm'.
80

Daniel W Bond's avatar
Daniel W Bond committed
81
Load up the mysql shell by running
82

Daniel W Bond's avatar
Daniel W Bond committed
83
``mysql -u root -p``
84

85
86
and putting in your mysql password.

Daniel W Bond's avatar
Daniel W Bond committed
87
88
Create the database by running

Daniel W Bond's avatar
Daniel W Bond committed
89
``CREATE DATABASE bookshare;``
Daniel W Bond's avatar
Daniel W Bond committed
90
91
92
93

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

``SHOW DATABASES;``
94

Daniel W Bond's avatar
Daniel W Bond committed
95
96
97
98
99
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.

``CREATE USER 'bookworm'@'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.

100
101
102
103
104
``GRANT ALL ON bookshare.* TO 'bookworm'@'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.)

``GRANT ALL ON test_bookshare.* TO 'bookworm'@'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.
105

Daniel W Bond's avatar
Daniel W Bond committed
106
107
The .\* is to grant access all tables in the database, and 'flush privileges' reloads privileges to ensure that your user is ready to go.

Daniel W Bond's avatar
Daniel W Bond committed
108
109
Exit the mysql shell by typing `exit`.

Daniel W Bond's avatar
Daniel W Bond committed
110
111
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.

112
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.
113

114
115
116
117
118
119
120
121
### Configuring the Cache

#### Notes on Cacheing

Bookshare'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!



122
123
124
125
126
127
128
129
130
131
132
133
134
135
### Email

Note: if you do not set this, the app will work 95% fine, except you will not be able to test sending email.

Amazon's Simple Email Service (SES) is set to the default on Bookshare, but these are actually generic settings that can handle any smtp server. Simply change the EMAIL_HOST, EMAIL_HOST_USER, and EMAIL_HOST_PASSWORD in secret.py, and change the EMAIL_PORT if necessary in settings.py.

You will also need to change the default recipient email addresses in trades/views.py; these are set by default to Amazon's testing email address with the actual user email addresses commented out above. (The same holds for deployment; change the recipent address to send emails to the actual recipients!)

### API Keys

Optional: sending email with Amazon's SES is set to the default on Bookshare. Create an SES account and set the host, user, and password in secret.py.

Optional: if you want to upload user media files to Amazon's Simple Storage Service (S3), you can add API keys for an S3 bucket to secret.py and set MEDIA_S3 to True in settings.py.

136
### Haystack Configuration
137

138
When your database is empty, this won't do much good, but once you've created a few objects, run 'python manage.py update_index' to set up your database objects for search.
Daniel W Bond's avatar
Daniel W Bond committed
139

140
### Starting up the test server
141

Daniel W Bond's avatar
Daniel W Bond committed
142
Now that your environment is configured, you can test out the Django test server to make
143
144
sure everything works locally. Simply run the command ``$ python manage.py runserver``

145
### Docker and Deployment
146

147
For server deployment, not for most local work
148

149
150
151
152
153
154
This project involves the uploading of files. While any images larger than five
megapixels are automatically scaled down on upload, this does not prevent
malicious individuals from uploading a massive file first. Nginx (or your
favorite server) MUST be configured to halt upload streaming once a particular
threshold is reached.

155
156
157
158
### Servers

You have three options from which to choose to serve your project for deployment. Apache + nginix, pure Apache, or pure nginx.

159
160
161
162
### Cacheing

Bookshare is in the process of being configured to use Redis for its cacheing.

163
## To-do
164

Daniel W Bond's avatar
Daniel W Bond committed
165
The list of to-do items is kept track of on the gitlab bookshare issues page. https://git.gmu.edu/srct/bookshare/issues Ask the project manager if you have any questions!
166
167
168
169
170
171
172

## License

Copyright (C) 2013 Mason SRCT: Daniel Bond, Michel Rouly, Eric Cawi, and contributors

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. See the LICENSE file in the root directory of this project for more information.