README.md 10.4 KB
Newer Older
1
# What's Open
Tyler Hallada's avatar
Tyler Hallada committed
2

3
[![build status](https://git.gmu.edu/srct/whats-open/badges/master/build.svg)](https://git.gmu.edu/srct/whats-open/commits/master) [![coverage report](https://git.gmu.edu/srct/whats-open/badges/master/coverage.svg)](https://git.gmu.edu/srct/whats-open/commits/master) [![python version](https://img.shields.io/badge/python-2.7-blue.svg)]() [![Django version](https://img.shields.io/badge/Django-1.10-brightgreen.svg)]()
Tyler Hallada's avatar
Tyler Hallada committed
4

5
6
7
The What's Open project is an initiative at George Mason University by Mason
Student Run Computing and Technology (SRCT) to display which dining locations
are currently open on George Mason University's campus.
8

9
10
This repo is a simple Django Rest Framework (DRF) project that contains the
database backend and API for SRCT developed What's Open applications. 
Tyler Hallada's avatar
Tyler Hallada committed
11

12
13
14
15
What's Open needs all the help it can get. Even if you don't feel 
like you can be helpful with the heavily technical aspects, 
we definitely need designers and technical writers.
 
16
There are many things that can be done with this project (see the project [Issues](https://git.gmu.edu/srct/whats-open/issues) 
17
18
section), but sometimes it's the small things that count, so don't be afraid of 
contributing just for a spelling mistake.
Tyler Hallada's avatar
Tyler Hallada committed
19

20
If you need help at all please contact any SRCT member in the `#whats-open` 
21
22
23
24
25
channel in our [slack group](https://srct.slack.com). We want people to 
contribute, so if you are struggling, or just want to learn, then we are 
willing to help.

Check out some of the other What's Open projects!
26
27
28
29
 - https://git.gmu.edu/srct/whats-open-android
 - https://git.gmu.edu/srct/whats-open-ios
 - https://git.gmu.edu/srct/whats-open-web
 - https://git.gmu.edu/srct/whats-open-alexa
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100

# Setup instructions for local development

What's Open currently supports developers on Linux and macOS systems. Here's our 
walk-through of steps we will take:

1. Install `git` on your system.
2. Clone the whats-open codebase.
3. Get whats-open up and running with the method of your choice.

## 1) Install `git` on your system.

`git` is the version control system used for SRCT projects.

### On Linux Based Systems

**with apt:**

Open a terminal and run the following command:

    sudo apt update

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

Next, with:

    sudo apt install git

you install `git` onto your system.

**with pacman:**
  
    pacman -S git

### On macOS

We recommend that you use the third party Homebrew package manager for macOS,
which allows you to install packages from your terminal just as easily as you
could on a Linux based system. You could use another package manager (or not
use one at all), but Homebrew is highly reccomended.

To get homebrew, run the following command in a terminal:

    /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)

**Note**: You do NOT need to use `sudo` when running any Homebrew commands, and
it likely won't work if you do.

Next, to make sure Homebrew is up to date, run:

    brew update

Finally we can install git with:

    brew install git

## 2) Clone the whats-open codebase

Now, we're going to clone down a copy of the whats-open codebase from [git.gmu.edu](http://git.gmu.edu/srct/whats-open),
the SRCT code respository with SSH.

**a)** Configure your ssh keys by following the directions at:

[git.gmu.edu/help/ssh/README](http://git.gmu.edu/help/ssh/README).

**b)** Now, on your computer, navigate to the directory in which you want to download the project (ie. perhaps one called `development/SRCT`), and run

    git clone git@git.gmu.edu:srct/whats-open.git

## 3) Get whats-open up and running

101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
Now that we have `git` setup and cloned down the code you can

    cd whats-open/

and get to working on setting up a development environment! There are two options
to go about doing this: `Docker` and `Manual Setup`.

### Docker

We can automate the setup process through [Docker](https://www.docker.com/what-docker)
containers! This allows us to quickly get started and standardize development
environments across machines.

Installing Docker on your system:

 - For macOS: [https://docs.docker.com/docker-for-mac/]()
 - For Windows: [https://docs.docker.com/docker-for-windows/]()
 - For your specific *nix distro: [https://docs.docker.com/engine/installation/]() 

Additionally, you will need to install docker-compose: [https://docs.docker.com/compose/install/]()

Next inside the `whats-open/` root directory run:

    docker-compose build

If that doesn't work, try:

    sudo docker-compose build

Then, follow up with:

    docker-compose up

If that doesn't work, try:

    sudo docker-compose build

You should see that the server is running by going to [http://localhost:8000]()
in your browser. Any changes you make to your local file system will be mirrored in the server.

If you would like to log into the admin interface then use the following credentials:

```
user: admin@masonlive.gmu.edu
pass: admin
```

### Manual Setup

Manual Setup involves all of the same steps as Docker, but just done manually.
151
152
153
154
155
156
157
158
159
160
161
162

First, install python, pip, and virtualenv on your system.
  * `python` is the programming language used for Django, the web framework used by whats-open.
  * `pip` is the python package manager.
  * `virtualenv` allows you to isolate pip packages within virtual environments

Open a terminal and run the following command:

    sudo apt update

Next, with:

163
    sudo apt install python3 python3-dev python3-pip 
164
    sudo pip3 install virtualenv
165
166
167

you install `python`, `pip`, and `virtualenv`.

168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
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
240
241
242
243
244
245
246
247
248
#### Database Setup

What's Open is built on top of a `MySQL` database and thus, we must set it up.

Run:

    sudo apt install mysql-server mysql-client libmysqlclient-dev python-mysqldb

to install mysql packages onto your system.

Load up the mysql shell by running

    mysql -u root -p

and putting in your mysql password.

Create the database by running:

    CREATE DATABASE wopen;

You can choose a different name for your database if you desire.

Double check your database was created by running:

    SHOW DATABASES;

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 'wopen'@'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.

    GRANT ALL ON wopen.* TO 'wopen'@'localhost';

This allows your database user to create all the tables it needs on the What's 
Open database.

Run:

    GRANT ALL ON test_wopen.* TO 'wopen'@'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.

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

Exit the mysql shell by typing:

    exit


At this point we will need to set some environment variables. 

If you are using bash then just copy paste the following into your terminal:

```
export WOPEN_SECRET_KEY=$(dd if=/dev/urandom count=100 | tr -dc "A-Za-z0-9" | fold -w 60 | head -n1 2>/dev/null)
export WOPEN_EMAIL_DOMAIN="@masonlive.gmu.edu"
export WOPEN_DB_NAME="wopen"
export WOPEN_DB_USER="wopen"
export WOPEN_DB_PASSWORD="password"
export WOPEN_DB_PORT=3306
export WOPEN_DB_HOST=
```

## The Virtual Enviornment

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 ease deployment server setup.

It's often recommended to create a special directory to store all of your 
virtual environments together (ie. development/virtualenv/), though they can be 
placed wherever is most convenient.

Then in your virtual environment directory run:
249

250
251
    virtualenv -p python3 whats_open
    source whats_open/bin/activate
252
253
254
255
256
257
258
259
260
261
262

to create your virtual environment and activate it. If you ever need to exit 
your virtual environment, simply run:

    deactivate

Now, the packages you need to install for Go are in in the top level of the 
project's directory structure(whats-open/).

Next with,

263
    pip install -r requirements.txt
264
265
266
    cd whats_open/
    python3 manage.py makemigrations
    python3 manage.py migrate
267
268
269
270

you setup the project.

# Running the local web server
Tyler Hallada's avatar
Tyler Hallada committed
271

Tyler Hallada's avatar
Tyler Hallada committed
272
273
Now that everything is set-up you can run the server on your computer.

274
    python3 manage.py runserver
275
276
277
278
279
280
281
282
283
284
285
286
287
288

Go to [http://127.0.0.1:8000/]() in your browser and you should see the website. 

Initially, there won't be any restaurants showing. You will need to add them to 
the database. 

Run,

    python manage.py createsuperuser

to create a superuser to use when signing in to the admin interface. 

Go to [http://127.0.0.1:8000/admin/]() to add new Restaurant and Schedule objects 
to your database.
Tyler Hallada's avatar
Tyler Hallada committed
289

290
With that, everything should be good to go!
Tyler Hallada's avatar
Tyler Hallada committed
291

292
# Modifying and Deploying Code
Tyler Hallada's avatar
Tyler Hallada committed
293
294
295
296
297
298

With the means of testing the website, you can really start contributing.

If you're new to Django and don't know where to start, I highly recommend
giving the [tutorial](https://docs.djangoproject.com/en/dev/intro/tutorial01/)
a try. However, it leaves out a lot of important things, so remember, Google is
299
your friend.
300
301
302
303
For the JavaScript, I will be using jQuery whenever possible because I prefer
it to straight up JavaScript. jQuery has [great
documentation](http://docs.jquery.com/) and I've found [Mozilla's documentation
on JavaScript](https://developer.mozilla.org/en-US/docs/JavaScript) to be
304
useful as well. But if your Google-fu is sharp, that should suffice.
305

306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
## CONTRIBUTING.md

This document goes into detail about how to contribute to the repo, including 
guidelines for commit messages and details on the workflow of the project.

## Opening issues

There are templates for issue descriptions located on the new issue page. I will
close issues with poor descriptions or who do not follow the standard.

## Coding style

You should adhere to the style of the repo code. Consistancy is key! PEP8 
guidelines are strongly reccomended but not enforced at the time. Please comment your code, I will not accept commits that contain uncommented code.

## Getting Help

I encourage you to join the [#whats-open channel](https://srct.slack.com/messages/go/details/) in SRCT's [Slack Group](https://srct.slack.com)
if you have any questions on setup or would like to contribute.