Connecting your Digital Garage project to any Github repository

Overview

This getting started tutorial walks you through the easiest way to configure your Quickstart template to build source from a private Github repository. We will be using the MEAN Stack Quickstart template in this example.

The following sections guide you through creating a project that contains a sample MEAN Stack (MongoDB, Express.js, AngularJS and Node.js) application that will serve as a welcome page. This example will require two pods.

  • one to host the Node.js/Express.js server and AngularJS application
  • one to host the MongoDB database

Prerequisites

The tutorial assumes that you have:

Setup

In this section, you will fork the Digital Garage MEAN sample
application on GitHub and clone the repository to your local machine so
that you can deploy and edit the application.

NOTE: You can skip this step if you already forked the thedigitalgarage/mean-ex repository.

  1. On GitHub, navigate to the thedigitalgarage/mean-ex repository. In the top-right corner of the page, click "Fork". Fork the project

  2. Next, execute the following commands on your local machine to clone the sample application and change to the new directory:

$ git clone https://github.com/<your_github_username>/mean-ex 
$ cd mean-ex

That's it! Now, you have a fork of the original thedigitalgarage/mean-ex example application Git repository and a copy on your local machine.

Note: If you have not downloaded and installed the Digital Garage Command-line-interface (CLI), now is a good time to do so. You can find a quick "how-to" on the Digital Garage documentation site here.

Building an Application from Source Code in a public Github repository.

Building an application from source code located in a public Github repository is very simple. You can either use a builder image purpose-built for the programming language in which the source code is written, or you can use a template such as a Quickstart template that may combine the source code with other containers or applications in a full stack. In our case we are going to use a Quickstart template for the MEAN Stack. This template will combine AngularJS (javascript) source code with the Node.js builder template and a MongoDB to deploy a full stack application in one click.

Note: During the remainder of this example, I am going to move back an forth from the Digital Garage Web Console (our web GUI) and the CLI. You can perform all of the steps in either interface. Follow along or feel free to use the interface that feels the most comfortable.

  1. First, if you have multiple projects, verify that you are in the correct project. Replace <project_name> below with a unique name for your project, such as <your_github_username>-example.
   $ oc get projects
   $ oc project <project_name> 
Creating an Application from a Quickstart template.

In this section you will follow the steps outlined in my earlier post Bootstrapping your MEAN Stack application with Openshift, Kubernetes and Docker. In that post we used the Digital Garage Web Console to create our application from the the qs-mean template. In this post, we will use the CLI for the same steps.

Build the app

We can create the the new app from the qs-mean.json template by using the -f flag and pointing the tool at a path to the template file:

   $ oc new-app -f /path/to/qs-mean.json

oc new-app will kick off a build once all required dependencies are confirmed.

Check the status of your new nodejs app with the command:

   $ oc status

Which should return something like:

    In project my-project on server https://10.2.2.2:8443

    svc/mean-ex - 172.30.108.183:8080
      dc/mean-ex deploys istag/nodejs-ex:latest <-
        bc/mean-ex builds https://github.com/thedigitalgarage/mean-ex with openshift/nodejs:0.10
          build #1 running for 7 seconds
        deployment #1 waiting on image or update

If the build is not yet started (you can check by running oc get builds), start one and stream the logs with:

    $ oc start-build mean-ex --follow

You can alternatively leave off --follow and use oc logs build/mean-ex-n where n is the number of the build to track the output of the build.

Note: You can follow along with the web console to see what new resources have been created and watch the progress of builds and deployments.

Building an Application from Source Code in a private Github repository.

The process for building an application from a private Github repository are exactly the same as a public repository with the exception of providing credentials. A private Github repository requires credentials before it will allow the builder image running on Digital Garage to clone the source files. In this example we will create a set of credentials that can be passed to Github in the form of a secret and then modify our template to use that secret when a build is requested.

  • First, we will create a secret that will be passed to Github during the build process.
   $ oc secrets new-basicauth SECRETNAME --username=USERNAME --password=PASSWORD

Note: In this example we will be using a Secret with Basic Authentication. You can use other Authentication methods with Github. See the Developer Guide on Secrets for more information.

  • Next, we are will modify the qs-mean template to include the build secret we just created. A copy of the MEAN Quickstart template is located in the openshift/templates folder of the mean-ex repository you forked earlier. You can also get a copy here: thedigitalgarage/mean-ex/openshift/templates/qs-mean.json

  • Open the qs-mean.json Quickstart template in your favorite editor, locate the "spec" section for the Build configuration at approximately line 74.

 { 
  "kind": "BuildConfig", 
  "apiVersion": "v1", 
  "metadata": {
     "name": "${NAME}",  
     "annotations": {  
        "description": "Defines how to build the application"  
         }  
      },  
     "spec": {  
        "source": {  
           "type": "Git",  
           "git": {  
              "uri": "${SOURCE\_REPOSITORY\_URL}",
              "ref": "${SOURCE_REPOSITORY_REF}"  
            },  
           "contextDir": "${CONTEXT\_DIR}"
     },
...
  • Before the "contextDir" key, add the following:
    "sourceSecret": { "name": "SECRETNAME" }, 

Note: Replace SECRETNAME with the name you used for the secret.

The resulting change should look like this:

{
  "kind": "BuildConfig",
  "apiVersion": "v1",
  "metadata": {
    "name": "${NAME}",
    "annotations": {
      "description": "Defines how to build the application"
   }
  },
  "spec": {
    "source": {
      "type": "Git",
      "git": {
        "uri": "${SOURCE_REPOSITORY_URL}",
        "ref": "${SOURCE_REPOSITORY_REF}"
      },
      "sourceSecret": {
        "name": "my-secret"
      },
      "contextDir": "${CONTEXT_DIR}"
    },
...
  • Save the template file to your local working directory.

  • Next, we will add the modified MEAN Quickstart template to your project/workspace. In the "Overview" screen of your project, click the Add to Project link on the top of the screen. This will take you to the Add to Project screen with a catalog of Quickstart templates, Instant Applications, DataBase templates and Builders for different languages.

  • Choose "Import YAML/JSON" tab at the top of the page.
    Import YAML/JSON

  • On the "Import YAML/JSON" screen, you will have the option to either paste the text from you edited Quickstart template or browse your local file system to choose the template that you saved in the previous step. Upload the saved template and click the [ Create ] button at the bottom of the page.

  • If your template is well formed, a pop-up screen will ask some additional questions. Check both the "Process the template" and "Save template" checkboxes. Click the "Continue" button.
    Save template Popup

  • You will again see the qs-mean configuration screen. Complete the configuration with your parameters. Pay special attention to the "Git Repository URL" by adding the URL of your private GitHub repository.

Note: If you would like to configure a Github webhook as a simple, effective automated build process, you can read Configuring Automated Builds on the Digital Garage documentation site.