README.md 8.94 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
While Bookshare has made its way into a beta release, it still 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

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.

11 12
The beta release was tagged April 26, 2015 in the master branch. All development aside from emergency exception handling and security vulnerabilities, additional test cases, and supplemental documentation should be made in the 1.0 release branch.

13 14
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.

15
The project lead for this project is **Daniel Bond** (*dbond2@gmu.edu* ).
16 17 18

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.

19 20
## Setting everything up for development

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

### 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`
31

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

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

36 37 38
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
39 40 41 42 43 44 45

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

### Package Installation

Next, install these packages from the standard repositories

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

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

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

52 53
### The Virtual Environment

Daniel W Bond's avatar
Daniel W Bond committed
54
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
55

56 57
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.

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

60 61 62 63 64 65
Run `sudo pip install virtualenv`

to install virtualenv system-wide, and then run

`virtualenv bookshare`

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

`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
77

78 79
### Creating the Database

Daniel W Bond's avatar
Daniel W Bond committed
80 81
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'.
82

Daniel W Bond's avatar
Daniel W Bond committed
83
Load up the mysql shell by running
84

Daniel W Bond's avatar
Daniel W Bond committed
85
``mysql -u root -p``
86

87 88
and putting in your mysql password.

Daniel W Bond's avatar
Daniel W Bond committed
89 90
Create the database by running

Daniel W Bond's avatar
Daniel W Bond committed
91
``CREATE DATABASE bookshare;``
Daniel W Bond's avatar
Daniel W Bond committed
92 93 94 95

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

``SHOW DATABASES;``
96

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

102 103 104 105 106
``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.
107

Daniel W Bond's avatar
Daniel W Bond committed
108 109
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
110 111
Exit the mysql shell by typing `exit`.

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

114
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.
115

116 117 118 119 120 121 122 123
### 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!



124 125 126 127 128 129 130 131 132 133 134 135 136 137
### 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.

138
### Haystack Configuration
139

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

142
### Starting up the test server
143

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

147
### Docker and Deployment
148

149
For server deployment, not for most local work
150

151 152 153 154 155 156
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.

157 158 159 160
### Servers

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

161 162 163 164
### Cacheing

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

165
## To-do
166

Daniel W Bond's avatar
Daniel W Bond committed
167
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!
168 169 170 171 172 173

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