/ocl_build_pipeline

GoCD build pipeline configuration for oclapi and ocl_web

Overview

This repository contains the documentation and infrastructure settings for OCL's GoCD setup.

GoCD is an open-source Continous Delivery tool.

Current setup is triggered by commits on oclapi and ocl_web repositories, deploys to Showcase, Staging and Production environments on demand once the quality checks are completed.

Currently, GoCD build server is running on the showcase server. The document below contains information on how the pipeline could be carried, i.e GoCD could be installed on a different server easily.

It is crucial that this README and the configuration files are kept up to date in case the pipeline is updated in any way.

The two sections below will help a contirbuter understand how a contribution gets deployed to an environment and how GoCD could be moved to a new location.

  1. Current build pipeline * API * WEB
  2. How to setup GoCD on a new server * Setting up the go-server * Setting up the go-agent(s)

For more help on GoCD, please visit GoCD documentation

Current build pipeline

Current pipeline is on https://gocd.openconceptlab.org

It has two pipelines:

  1. API
  2. WEB

API

API pipeline has the following stages and corresponding jobs under them which contain specific tasks that carry out the stage's goal

  1. Unit Test
  2. Integration Test
  3. Showcase Deploy
  4. E2E tests
  5. Staging Deploy
  6. Importer Perf
  7. Production Deploy

IMPORTANT_NOTE: Environment variables that start with OCL are meant to be passed on the ocl_api container. Without the OCL prefix, they will not be effective.

Unit Test

This stage runs Django unit tests.

Integration Test

This stage runs api endpoint tests written in Django

Showcase Deploy

This stage is triggered manually after the integration tests pass. And has the following environment variables:

  • IP: Showcase box's IP (showcase.openconceptlab.org)
  • SETTINGS: Django settings module
  • OCL_CONFIG: Django settings class name
  • OCL_SETTINGS: Django settings
  • OCL_DATA_ROOT: Must be left empty so that MongoDB and Solr data is mounted
  • OCL_AWS_ACCESS_KEY_ID: This and other AWS variables are used to connect to S3 in order to store exported csv files.
  • OCL_AWS_SECRET_ACCESS_KEY
  • OCL_AWS_STORAGE_BUCKET_NAME:
  • OCL_ROOT_PWD: API admin user's (root) password.

E2E Tests

This stage is triggered automatically once the Showcase Deploy stage is completed successfully. It runs UI tests specified under ocl_web repo. It has the following environment variable:

  • IP: Showcase box's IP

Staging Deploy

This stage is triggered manually after the integration tests pass. And has the following environment variables:

  • IP: Staging box's IP (staging.openconceptlab.org)
  • SETTINGS: Django settings module
  • OCL_CONFIG: Django settings class name
  • OCL_SETTINGS: Django settings
  • OCL_DATA_ROOT: Must be left empty so that MongoDB and Solr data is mounted
  • OCL_AWS_ACCESS_KEY_ID: This and other AWS variables are used to connect to S3 in order to store exported csv files.
  • OCL_AWS_SECRET_ACCESS_KEY
  • OCL_AWS_STORAGE_BUCKET_NAME:
  • OCL_ROOT_PWD: API admin user's (root) password.
  • OCL_NEW_RELIC_API_KEY: New relic API key, must be updated if NewRelic API key changes.

Importer Perf

This stage is manually triggered, staging deployment stage must be successful as a prerequisite. It runs a few import jobs on the go-agent container and expects them to complete under 120 seconds. Has two environment variables:

  • SOLR_ROOT
  • SOLR_HOME

Production Deploy

This stage is triggered manually. It deploys a given version of the codebase to the production server. Could be done by anybody who has admin access to the pipeline. It has the following environment variables:

  • IP: Production box's IP (www.openconceptlab.org)
  • SETTINGS: Django settings module
  • OCL_CONFIG: Django settings class name
  • OCL_SETTINGS: Django settings
  • OCL_DATA_ROOT: Must be left empty so that MongoDB and Solr data is mounted
  • OCL_AWS_ACCESS_KEY_ID: This and other AWS variables are used to connect to S3 in order to store exported csv files.
  • OCL_AWS_SECRET_ACCESS_KEY
  • OCL_AWS_STORAGE_BUCKET_NAME:
  • OCL_ROOT_PWD: API admin user's (root) password.
  • OCL_NEW_RELIC_API_KEY: New relic API key, must be updated if NewRelic API key changes.
  • DISABLE_VALIDATION: Disable any custom schema validation (should be False)

WEB

WEB pipeline is fed by the ocl_web repository and deploys the UI to various environments. It has the following stages:

  1. Unit Test
  2. Showcase Deploy
  3. E2E Tests
  4. Staging Deploy
  5. Production Deploy

Unit Test

This stage run WEB's unit tests

Showcase Deploy

This stage is triggered manually. It has the following environment variables:

  • IP: Showcase box's IP
  • ENV: Showcase
  • PORT: Port where UI server will be run
  • TOKEN: API admin user's API key

E2E Tests

This stage runs UI acceptance tests once the code is deployed to the Showcase environment. It has the following environment variables:

  • IP: Showcase box's IP

Staging Deploy

This stage is triggered manually, it deploys UI to the Staging environment. It has the following environment variables:

  • IP: Staging box's IP
  • ENV: Staging
  • PORT: Port where UI server will be run
  • TOKEN: API admin user's API key

Production Deploy

This stage is triggered manually, it deploys UI to the Production environment. Could be done by anybody who has admin access to the pipeline. Has the following environment variables:

  • IP: Production box's IP
  • ENV: Production
  • PORT: Port where UI server will be run
  • TOKEN: API admin user's API key

How to setup GoCD on a new server

GoCD consists of a GoCD server and one or more GoCD agents. More agents mean more workpower and that many pipelines or stages could be run in parallel.

How to build the GoCD Server

GoCD server could be install using the latest official docker image for the go-server and running the container as below:

  1. Install docker-engine
  2. docker pull gocd/gocd-server:17.2.0
  3. docker run -d -p 8153:8153 -p 8154:8154 --name go-server --hostname go-server go-server
  4. Once the container is up, please go to https://gocd.openconceptlab.org and follow instructions on how to a backup of the current system on https://docs.gocd.io/current/advanced_usage/one_click_backup.html
  5. Follow the instructions on the same document to restore from the GoCD backup.
  6. Visit https://<SERVER>:8153 to see whether everything is in place

How to build the GoCD Agent

This repository includes a Dockerfile that is prepared specifically for OCL, which includes necessary applications and libraries needed for deployment and unit testing. We recommend that you use at least two instances of go-agent:

  1. git clone git@github.com:OpenConceptLab/go-cd.git
  2. docker build -f Dockerfile.go-agent -t go-agent .
  3. docker run -d --name go-agent --hostname go-agent -e GO_SERVER_URL=https://$IP:8154/go go-agent

Once these steps are completed, SSH connection between the go agent and destination environments (e.g staging, showcase) must be established:

  1. Initiate a bash session within the go-agent container:
 docker exec -it go-agent bash
  1. Once in the container, switch from root user to go user:
su go
  1. Still in the container, generate an SSH key for go user:
ssh-keygen -t rsa
  1. Still in the container, copy your key over to the deployment environment:
ssh-copy-id -i $USER@$IP
  1. Exit the container: type exit and hit ENTER
  2. Visit AGENTS tab on your new GoCD server to see the agents connected successfully to the server.
  3. Should be good to go!