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

David Haynes's avatar
David Haynes committed
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-3.5+-blue.svg)]() [![Django version](https://img.shields.io/badge/Django-2.0-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
This repo is a simple Django Rest Framework (DRF) project that contains the
10
database backend and API for SRCT-developed What's Open applications.
Tyler Hallada's avatar
Tyler Hallada committed
11

bhnvi dubey's avatar
bhnvi dubey committed
12 13
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,
14
we definitely need designers and technical writers.
bhnvi dubey's avatar
bhnvi dubey committed
15 16 17

There are many things that can be done with this project (see the project [Issues](https://git.gmu.edu/srct/whats-open/issues)
section), but sometimes it's the small things that count, so don't be afraid of
18
contributing just for a spelling mistake.
Tyler Hallada's avatar
Tyler Hallada committed
19

bhnvi dubey's avatar
bhnvi dubey committed
20 21 22
If you need help at all please contact any SRCT member in the `#whats-open`
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
23 24 25
willing to help.

Check out some of the other What's Open projects!
26 27 28 29 30

- 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
31 32 33

# Setup instructions for local development

bhnvi dubey's avatar
bhnvi dubey committed
34
What's Open currently supports developers on Linux and macOS systems. Here's our
35 36
walk-through of steps we will take:

37 38 39 40
<details><summary>
</h2> 1) Install <code>git</code> on your system.</h2>
</summary>
<p>
41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60

`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:**
bhnvi dubey's avatar
bhnvi dubey committed
61

62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84
    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
85 86 87 88 89 90 91
</p>
</details>

<details><summary>
</h2> 2) Clone the whats-open codebase </h2>
</summary>
<p>
92 93 94 95 96 97 98 99 100 101 102 103 104


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

105 106 107 108 109 110 111
</p>
</details>

<details><summary>
</h2> 3) Get whats-open up and running </h2>
</summary>
<p>
112

113 114 115 116 117 118 119
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`.

120 121 122 123
<details><summary>
</h3> Docker</h3>
</summary>
<p>
124 125 126 127 128 129 130

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:

131 132 133
- 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/
134

bhnvi dubey's avatar
bhnvi dubey committed
135
Additionally, you will need to install docker-compose: https://docs.docker.com/compose/install/
136

137
Inside the `whats-open/` root directory run:
138

139
    docker-compose up
140

bhnvi dubey's avatar
bhnvi dubey committed
141
You should see that the server is running by going to http://localhost:8000
142 143 144 145 146 147 148 149 150
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
```

151 152 153
### Loading Default Data

Django apps use fixtures to load default data for testing. To load the api's fixtures use the following command in the terminal:
154

155 156 157 158 159 160 161 162 163 164 165 166
```
docker exec whats_open_api python3 /whats-open/whats-open/manage.py loaddata --format json categoriesFixture locationFixture openTimeFixture scheduleFixture settingsFixture
```


</p>
</details>

<details><summary>
</h2> Manual Setup </h2>
</summary>
<p>
167
Manual Setup involves all of the same steps as Docker, but just done manually.
168 169

First, install python, pip, and virtualenv on your system.
170 171 172 173

- `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
174 175 176 177 178 179 180

Open a terminal and run the following command:

    sudo apt update

Next, with:

bhnvi dubey's avatar
bhnvi dubey committed
181
    sudo apt install python3 python3-dev python3-pip
182
    sudo pip3 install virtualenv
183 184 185

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

186 187 188 189
You will also need the following `gdal` packages for GeoDjango support:

```
sudo add-apt-repository -y ppa:ubuntugis/ubuntugis-unstable
190 191 192 193
sudo apt update
sudo apt upgrade # if you already have gdal 1.11 installed
sudo apt install gdal-bin python-gdal python3-gdal # if you don't have gdal 1.11 already installed
```
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
#### 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';

bhnvi dubey's avatar
bhnvi dubey committed
226
For local development, password strength is less important, but use a strong
227 228 229 230
passphrase for deployment. You can choose a different username.

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

bhnvi dubey's avatar
bhnvi dubey committed
231
This allows your database user to create all the tables it needs on the What's
232 233 234 235 236 237 238
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
239
doesn't get screwed up. This database is called 'test\_' + whatever your normal
bhnvi dubey's avatar
bhnvi dubey committed
240
database is named. Note that for permissions it doesn't matter that this database
241 242
hasn't yet been created.

243
The .\* is to grant access all tables in the database, and 'flush privileges'
244 245 246 247 248 249
reloads privileges to ensure that your user is ready to go.

Exit the mysql shell by typing:

    exit

bhnvi dubey's avatar
bhnvi dubey committed
250
At this point we will need to set some environment variables.
251 252 253 254 255 256 257 258 259 260 261 262 263 264 265

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

bhnvi dubey's avatar
bhnvi dubey committed
266 267
Virtual environments are used to keep separate project packages from the main
computer, so you can use different versions of packages across different
268 269
projects and ease deployment server setup.

bhnvi dubey's avatar
bhnvi dubey committed
270 271
It's often recommended to create a special directory to store all of your
virtual environments together (ie. development/virtualenv/), though they can be
272 273 274
placed wherever is most convenient.

Then in your virtual environment directory run:
275

276 277
    virtualenv -p python3 whats_open
    source whats_open/bin/activate
278

bhnvi dubey's avatar
bhnvi dubey committed
279
to create your virtual environment and activate it. If you ever need to exit
280 281 282 283
your virtual environment, simply run:

    deactivate

bhnvi dubey's avatar
bhnvi dubey committed
284
Now, the packages you need to install for Go are in in the top level of the
285 286 287 288
project's directory structure(whats-open/).

Next with,

289
    pip install -r requirements.txt
290 291 292
    cd whats_open/
    python3 manage.py makemigrations
    python3 manage.py migrate
293 294 295 296

you setup the project.

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

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

300
    python3 manage.py runserver
301

bhnvi dubey's avatar
bhnvi dubey committed
302
Go to http://127.0.0.1:8000/ in your browser and you should see the website.
303

bhnvi dubey's avatar
bhnvi dubey committed
304 305
Initially, there won't be any restaurants showing. You will need to add them to
the database.
306 307 308 309 310

Run,

    python manage.py createsuperuser

bhnvi dubey's avatar
bhnvi dubey committed
311
to create a superuser to use when signing in to the admin interface.
312

bhnvi dubey's avatar
bhnvi dubey committed
313
Go to http://127.0.0.1:8000/admin/ to add new Restaurant and Schedule objects
314
to your database.
Tyler Hallada's avatar
Tyler Hallada committed
315

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

318 319 320 321 322 323 324 325 326 327 328 329 330 331
### Loading Default Data

Django apps use fixtures to load default data for testing. To load the api's fixtures use the following command:

```
python3 manage.py loaddata --format json categoriesFixture locationFixture openTimeFixture scheduleFixture settingsFixture
```

</p>
</details>

</p>
</details>

332
# Modifying and Deploying Code
Tyler Hallada's avatar
Tyler Hallada committed
333 334 335 336 337 338

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
339
your friend.
340

341 342
## CONTRIBUTING.md

bhnvi dubey's avatar
bhnvi dubey committed
343
This document goes into detail about how to contribute to the repo, including
344 345 346 347 348 349 350 351 352
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

bhnvi dubey's avatar
bhnvi dubey committed
353 354
You should adhere to the style of the repo code. Consistency is key! PEP8
guidelines are strongly recommended but not enforced at the time. Please comment your code, I will not accept commits that contain uncommented code.
355 356 357 358 359

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