Skip to content

Project Dev Onboarding

Jump to bottom
connie m edited this page Nov 11, 2017 · 6 revisions

PROJECT DEVELOPMENT INSTRUCTIONS

🏃 QUICK JUMP

👋 INTRO

  • This wiki doc is a guide meant to help with getting started on developing the project.
  • It is being maintained by Connie (ping me @maknoon in the comments if you have any questions).
  • Anything formatted like directory$ command -params val will be a bash command that you can execute in your terminal application.
    • directory refers to the name of the directory you should be in when you are invoking the command.
    • if no directory is specified you can execute it anywhere
  • These instructions are optimized for Mac OSX development environment, with XCode tools already installed.
    • If you do not have XCode, you can install that from your App Store here.
    • Note that pretty much every command except the brew ones will work on Linux or Windows bash.

💻 SETUP AND TESTING

❗️ The following steps are mandatory for development.

clone from github

  • To clone the master branch of the project from Github, navigate to a home directory of your choice, then:
    $ git clone https://github.com/maknoon/airdb.git
  • Go to the repo to check that it looks good: $ cd airdb

❗️ The following instructions will help you setup a local version of airdb that you can test locally. If you do not plan on installing or testing locally, skip ahead to Testing on Live Server.

installing project dependencies

  • Make sure you have Python2.7 installed:
    $ brew update && brew install python
    • This should automattically install the pip package manager for Python2.7.
  • Install all project dependencies using the package manager:
    airdb$ pip install -r requirements.txt
    • NOTE: CHECK the output in your terminal to ensure that everything has installed correctly! If you see any errors complaining about permissions, try airdb$ sudo pip install -r requirements.txt

mysql server setup

  • Install & setup a MySQL server on your local machine:
    $ brew install mysql
    • The setup will prompt you to set a password for your root user. Do so & remember that password.
    • Next start the MySQL server:
      $ mysql.server start
    • Create a new database called airdb on your local MySQL server's database:
      $ mysqladmin -u root -p create airdb
      • This operation will prompt you to enter your root password.
  • Setup the airline user on airdb:
    • Login to the server as root first:
      $ mysql -u root -p
    • Inside the console, create a new user called airline (with password of your choice), and then grant privileges for using airdb to this new user:
      mysql$ CREATE USER 'airline'@'localhost' IDENTIFIED BY 'password';
      mysql$ GRANT ALL PRIVILEGES ON airdb . * TO 'airline'@'localhost';
      mysql$ FLUSH PRIVILEGES;
    • Check your setup. exit the mysql server and try to login as the user airline:
      $ mysql -u airline -p
    • Make sure you enter the password for the airline user.
  • Now make sure that the project configurations are correct by creating a config.py file in the project directory, with the following information:
env = 0
host = 'localhost'
dbname = 'airdb'
dbusr = 'airline'
dbpwd = 'password' # this is the password you made for airline earlier

running the application

  • Run the application using:
    airdb$ python airplane.py
  • airdb should now be running on your localhost, served to the standard Flask port 5000. To confirm, visit http://localhost:5000/ in a web browser.

🚀 TESTING ON LIVE SERVER

setup ssh tunneling

  • Add our private SSH key cpsc304.pem to your ~/.ssh directory
  • Change permissions on key to read-only:
    $ chmod 400 ~/.ssh/cpsc304.pem
  • Add the following to your ~/.ssh/config file (create one if it does not exist):
Host air
	Hostname [the ipv4 addr]
	User ubuntu
	IdentityFile ~/.ssh/cpsc304.pem
  • You can now access the server by simply invoking $ ssh air

to test on live server

  • rsync your (tested!) changes to EC2 instance. In the PARENT DIRECTORY of the repo, execute:
    $ rsync -av --exclude-from 'airdb/excl.txt' airdb/ air:airdb/
  • SSH into instance and type:
    $ sudo apachectl restart
  • Restart the server and exit to see your changes live at the server's ipv4 address
  • Test endpoints by visiting http://i.p.v.4.addr/name-of-endpoint

note on query parameters

  • Most of our endpoints will probably be served using URL-encoded query parameters. The format of a URL for this is something like:
    http://i.p.v.4.addr/endpoint?one={val1}&two={val2}
    Where one, two are names of parameters defined in our code and {val1}, {val2} should be replaced by the corresponding values that you want to pass to into those params.
  • Later to support special characters we will probably have to add URL decoding in our code, but for now some special characters may have weird behavior if used as test values

👍 HELPFUL GIT BASH COMMANDS

We are using a minimalized version of feature branch development. This will help keep the master & dev branches clean of buggy code when we ship our project. Before you begin working, make sure you are not committing code directly into master or dev!

general git commands

Note: all of the following git commands must be executed while your working directory is the airdb repository.

  • How to tell which branch you are on:
    $ git status
  • To checkout a new branch:
    $ git checkout -b new_branch_name
    new_branch_name will contain all the commits from the current branch you were on before, which means if your branch was dev before, new_branch_name will have everything from dev in it as well
  • To commit and push changes to your branch:
    $ git add .
    $ git commit -m 'Your commit message here'
    $ git push origin your_branch_name
  • To pull commits in from a different remote branch, while on your own branch (useful for pulling in other people's changes):
    $ git pull origin remote_branch_name
    Tip: Always pull any new changes from the master & dev before you commit your own changes to check that everything looks good on your branch to resolve any merge conflicts before they appear on the repository.
  • If you find yourself accidentally on the wrong branch but have code that you want to keep, use stash:
    $ git stash
    $ git checkout -b new_branch_name
    $ git stash apply stash@{0}

a note on pull requests

  • Opening pull requests (PRs) manually on git by going to the branches tab and clicking "New pull request". For new features, MAKE SURE that the base branch you want to merge into is dev and not master!
  • It is best practice to have 1 or 2 other people review your PR, then fix & commit any changes you made based on the code review & reply to the comments on the pull request indicating that they were fixed.
  • Once fixes are tested, committed & pushed to your PR, make sure that your branch contains no merge conflicts with dev or master (i.e. both are up to date) - you can check using $ git pull origin dev and then fix any conflicts if there are any locally before pushing again.
  • Finally, go to your pull request and click "Merge pull request" at the bottom to merge your working code.

👍 HELPFUL LINUX BASH COMMANDS

These are some helpful commands for development on the server.

  • To view a live-updated app error log in the terminal:
    $ tail -f /var/log/apache2/error.log
  • To restart the server:
    $ sudo apachectl restart
Clone this wiki locally