Using the Amazon AMI

Alex H. Wagner, PhD edited this page Aug 4, 2017 · 4 revisions

Developers interested in contributing to the DGIdb codebase will need to set up an environment for examining the effect of any changes made to the code. This guide details covers getting started on development quickly, from setting up your AWS development environment to submitting your code through GitHub.

Set up development environment

Boot up and connect to an AWS instance

Creating a new AWS instance from the DGIdb AMI

  1. Log into the AWS EC2 management console

  2. Navigate to the us-west-2 (Oregon) subdomain

  3. Navigate to Images->AMIs and search 'Public images' for the 'dgidb-dev_<DATE>' AMI (currently ami-f2ca2c8a)

  4. Right-click on the dgidb-dev_<DATE> AMI and select 'Launch'

  5. The recommended configuration follows, with unmentioned attributes left at defaults:

    Configuration

    Type Tag Security Group
    t2.micro Name=dgidb_[username] See Security table
    Security
    Type Protocol Port Range Source
    SSH TCP 22 0.0.0.0/0
    Custom TCP Rule TCP 3000-3000 0.0.0.0/0
  6. Create or select an existing SSH key. See the Amazon documentation for more information on this subject

  7. Launch instance

Log into your AWS EC2 instance

  1. Navigate to the instances page on the EC2 management console
  2. Locate the instance with the name tag designated in step 5 above
  3. Check if the instance state is running
  • If the state is stopped, right-click on the instance and select Instance State -> Start
  • Move on to step 4 once the instance state is running
  1. Select the instance and copy the Public IP listed in the instance description at the bottom of the page

  2. Open a terminal (or ssh client software, such as PuTTY) and connect using the following:

    ssh credentials

    attribute value
    username ubuntu
    ssh key private key from step 6 above
    ip address Public IP from step 4 of this section

    Using the GNU ssh utility, the command would look like this:

    ssh -i /path/to/private_key.pem ubuntu@PUBLIC_IP
    

Launching services

  1. From your ssh session, launch screen (more about screen):
screen -S dgidb
  1. Change to the dgi-db directory, update the server, and launch it
cd dgi-db
git pull origin master
rails s -b 0.0.0.0
  1. Verify that the server has started correctly (the following text is displayed):
[TIMESTAMP] INFO  WEBrick 1.3.1
[TIMESTAMP] INFO  ruby 2.3.1 (2016-04-26) [x86_64-linux]
[TIMESTAMP] INFO  WEBrick::HTTPServer#start: pid=2701 port=3000
  1. Test that the client is accessible over the web, by opening a web browser and navigating to http://INSTANCE_PUBLIC_IP:3000

  2. Detach from screen by pressing ctrl-a, ctrl-d

Contributing code

Configuring git and GitHub forks

  1. Fork the DGIdb (https://github.com/griffithlab/dgi-db) GitHub repository (see how to fork a GitHub repository)
  2. In your ssh session, configure git to use your credentials:
git config --global user.name "Your Name"
git config --global user.email your.email@host.domain

After completing these steps, all that remains is linking to these forks as remotes from your local git repository on your instance. This can be done via https (recommended) or ssh.

Configuring git remotes for GitHub over https (recommended)

For users WITH 2-factor authentication enabled that are NOT sharing login credentials for their AWS instance, consider using SSH instead.

  1. Add your forks as remotes using your GitHub username
cd dgi-db
git remote add FORK_NAME https://github.com/YOUR_USERNAME/dgi-db.git
  1. Create a personal access token (only if using GitHub 2-factor authentication)

For instructions on creating a personal access token, go here. Be sure to grant repo permissions for the token. Use this token as a password when accessing the remote repository using git on the command line.

Configuring git remotes for GitHub over ssh (advanced users)

WARNING: If you are sharing your login credentials to your AWS instance, DO NOT USE THIS METHOD

  1. Add your forks as remotes using your GitHub username
cd dgi-db
git remote add FORK_NAME git@github.com:YOUR_USERNAME/dgi-db.git
  1. Add SSH keys from your AWS instance to your GitHub account using the GitHub instructions.

Making changes

Changes to the codebases for the server are reflected live on http://INSTANCE_PUBLIC_IP:3000. Before you begin making changes, you should create a new branch in the corresponding directory:

git checkout -b FEATURE_NAME

You can read more about branching with git here.

After you have made changes that you want to keep, commit them to the current branch and push to your GitHub fork:

git add -A
git commit -m 'DESCRIPTION OF CHANGES'

Next, ensure that your changes do not conflict with other users' changes:

git pull origin master

If conflicts arise, see this article on how to resolve them.

Next, push your changes to GitHub:

git push -u FORK_NAME FEATURE_NAME

Finally, submit your feature branch as a pull request, and work with the DGIdb core developers to merge your code into DGIdb.

When you are ready to work on a new feature, switch back to master, pull in changes, and start a new branch for the new feature:

git checkout master
git pull origin master
git checkout -b NEW_FEATURE_NAME
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.