README.md 6.59 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

Daniel W Bond's avatar
Daniel W Bond committed
44
`$ sudo apt-get install libldap2-dev mysql-server mysql-client libmysqlclient-dev python-mysqldb libsasl2-dev libjpeg-dev`
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.

Daniel W Bond's avatar
Daniel W Bond committed
100
``GRANT ALL ON bookshare.* TO 'bookworm'@'localhost';`` ``FLUSH PRIVILEGES;``
101

Daniel W Bond's avatar
Daniel W Bond committed
102 103
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
104 105
Exit the mysql shell by typing `exit`.

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

108
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.
109

110
### Haystack Configuration
111

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

114
### Starting up the test server
115

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

119
### Docker and Deployment
120

121
For server deployment, not for most local work
122

123 124 125 126 127 128
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.

129 130 131 132
### Servers

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

133
## To-do
134

Daniel W Bond's avatar
Daniel W Bond committed
135
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!
136 137 138 139 140 141 142

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