Getting Started with CIViC Development on AWS - griffithlab/civic-server GitHub Wiki

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 AWS EC2 management console

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

  3. Navigate to Images->AMIs and search 'Public images' for the civic dev instance (ami-0d6dc9d8df9221279)

  4. Right-click on the civic AMI and select 'Launch'

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

  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 civic-server
  1. 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
  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

Optional: If you are not doing client development, you may skip steps 4-8, and instead direct your browser to http://INSTANCE_PUBLIC_IP:3000 to test that the instance is working properly.

  1. Detach from screen by pressing ctrl-a, ctrl-d, and start a new screen for the client:
screen -S civic-client
  1. Change to the civic-client directory, update the client, and launch it
cd civic-client
git pull origin master
gulp serve
  1. 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

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

  2. Detach from screen 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)
  2. In your ssh session, 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 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
  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 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
  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 (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.

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

Configuring the CIViC dev instance to allow a generic login

In your instance, go to http://INSTANCE_PUBLIC_IP:3001/api/auth/developer. You should then be presented with a login form, where you can login as any generic user. Enter a username and email address and submit. Once done return to http://INSTANCE_PUBLIC_IP:3001.

If you want admin privileges, you’ll need to use the rails console. To set that up you can do the following:

cd civic-server
rails c

Then, on the console prompt:

user = User.last
user.make_admin!
exit