Getting Started with CIViC Development on AWS

Developers interested in contributing to the CIViC 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 CIViC AMI

1. Log into the shared AWS account

• User: civic.dev

2. Go to the AWS EC2 management console

3. Ensure you are on the us-west-2 (Oregon) subdomain

4. Search for the civic_dev_v2 AMI (ami-1715bb77)

5. Right-click on the civic_dev_v2 AMI and select Launch

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

   Configuration

   Type	Tag	Security Group
   t2.micro	Name=civic_[username]	See Security table
   Security

   Type	Protocol	Port Range	Source
   SSH	TCP	22	0.0.0.0/0
   Custom TCP Rule	TCP	3000-3001	0.0.0.0/0
   Custom TCP Rule	TCP	35729	0.0.0.0/0

NOTE: This security configuration has been pre-configured for you as civic-dev 6. Select the civic_aws_all SSH key. 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

4. Select the instance and copy the Public IP listed in the instance description at the bottom of the page

5. 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](#log-into-your-aws-ec2-instance), launch `byobu` (more [about byobu](http://byobu.co/)):  

byobu new -s civic-server

2. Change to the `civic-server` directory, update the server, and launch it

cd civic-server git pull origin master rails s -b 0.0.0.0

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

4. Detach from the current `byobu` session by pressing `ctrl-a`, `ctrl-d`, and start a new `byobu` session for the client:

byobu new -s civic-client

5. Change to the `civic-client` directory, update the client, and launch it

cd civic-client git pull origin master gulp serve

6. Verify that the client has started correctly (the following text is displayed):

[TIMESTAMP] Server started http://0.0.0.0:3001 [TIMESTAMP] LiveReload started on port 35729

7. Test that the client is accessible over the web, by opening a web browser and navigating to `http://INSTANCE_PUBLIC_IP:3001`

8. Detach from the `byobu` session by pressing `ctrl-a`, `ctrl-d`

###Contributing code
####Configuring git and GitHub forks
1. Fork the civic-server (https://github.com/genome/civic-server) and civic-client (https://github.com/genome/civic-client) GitHub repositories (see [how to fork a GitHub repository](https://help.github.com/articles/fork-a-repo/))
2. In your [ssh session](#log-into-your-aws-ec2-instance), configure git to use your credentials:

git config --global user.name "Your Name" git config --global user.email [email protected]

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](#configuring-git-remotes-for-github-over-ssh-advanced-users) instead._

1. Add your forks as remotes using your GitHub username

cd civic-server git remote add FORK_NAME https://github.com/YOUR_USERNAME/civic-server.git cd ../civic-client git remote add FORK_NAME https://github.com/YOUR_USERNAME/civic-client.git

2. Create a personal access token (only if using GitHub [2-factor authentication](https://help.github.com/articles/securing-your-account-with-two-factor-authentication-2fa/))

  For instructions on creating a personal access token, go [here](https://help.github.com/articles/creating-an-access-token-for-command-line-use/#creating-a-token). 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 civic-server git remote add FORK_NAME [email protected]:YOUR_USERNAME/civic-server.git cd ../civic-client git remote add FORK_NAME [email protected]:YOUR_USERNAME/civic-client.git

2. Add SSH keys from your AWS instance to your GitHub account using the [GitHub instructions](https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/#platform-linux).

####Making changes
Changes to the codebases for the server (in the `civic-server` directory) and the client (in the `civic-client` directory) are reflected live on `http://INSTANCE_PUBLIC_IP:3001`. 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](https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging).

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](https://help.github.com/articles/resolving-a-merge-conflict-from-the-command-line/) 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](https://help.github.com/articles/creating-a-pull-request/), and work with the CIViC core developers to merge your code into CIViC.

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