API Documentation

On this page

Prerequisites 

  1. GitHub account 

  2. Jenkins server 

  3. Docker host (EC2 or equivalent) 

  4. Hvclient server
    Note: For hvclient installation and configuration, please refer to this guide.

  5. Atlas Account

Set Up Your GitHub Account

  1. Open your web browser and go to GitHub.
  2. Click on the Sign up button.​​​​​​
  3. Enter your details.
  4. Fill in your email address, create a password, and choose a username.
  5. Decide if you want to receive updates and announcements from GitHub, then complete the CAPTCHA to verify that you are not a robot.
  6. Click on Create account. GitHub will send a verification code to your email.
  7. Enter this code to verify your email address.
  8. Personalize your experience. You may be asked a few questions about how you plan to use GitHub. You can answer them or skip this step.

Install Jenkins

Run the following commands on your server to install Jenkins: 

  1. Update your system.

    sudo apt update
    sudo apt upgrade 
  2. Install Java. Note: Jenkins requires Java to run. Install OpenJDK:

    sudo apt install openjdk-11-jdk 
  3. Add Jenkins repository.

    wget -q -O - https://pkg.jenkins.io/debian-stable/jenkins.io.key | sudo apt-key add - 

    Then, add the Jenkins repository to your sources list:

    sudo sh -c 'echo deb http://pkg.jenkins.io/debian-stable binary/ > /etc/apt/sources.list.d/jenkins.list' 
  4. Update your package list and install Jenkins.

    sudo apt update
    sudo apt install jenkins 
  5. Start and enable Jenkins

    sudo systemctl start jenkins && sudo systemctl enable jenkins 
  6. If you have a firewall enabled, allow Jenkins to communicate.

    sudo ufw allow 8080 
    sudo ufw status
  7. Open your web browser and go to http://your_server_ip_or_domain:8080. You will see the Jenkins setup screen.
  8. Unlock Jenkins and retrieve the initial admin password.

    sudo cat /var/lib/jenkins/secrets/initialAdminPassword
  9. Copy the password and paste it into the Jenkins setup screen. 
  10.  Follow the on-screen instructions to install suggested plugins and create your first admin user

Docker Host

Run the following commands on your server:

  1. Update your system.

    sudo apt update
    sudo apt upgrade 
  2. Install required packages.

    sudo apt install apt-transport-https ca-certificates curl software-properties-common
  3. Add Docker’s Official GPG Key. 

    curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
  4. Add Docker Repository.

    sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
  5. Install Docker.

    sudo apt update
    sudo apt install docker-ce
  6. Start and enable Docker.

    sudo systemctl start docker
    sudo systemctl enable docker
  7. Verify Docker installation.

    sudo docker --version
  8. Install Docker Compose

    sudo curl -L "https://github.com/docker/compose/releases/download/$(curl -s https://api.github.com/repos/docker/compose/releases/latest | grep -Po '\"tag_name\": \"\K.*\d')" -o /usr/local/bin/docker-compose
    sudo chmod +x /usr/local/bin/docker-compose
    docker-compose --version
    sudo usermod -aG docker <username>
  9. After adding the user restart the session.

Integration

Configure Jenkins Server

  1. Log in to Jenkins.
  2. Go to the Manage Jenkins > Plugins > Available plugins.

  3. Search for the below listed plugins.

    • Maven Integration
    • Publish Over SSH
    • GitHub plugin, Git plugin

  4. Click Install.

  5. Tick the "Restart Jenkins when installation is complete and no jobs are running".
    Note: Jenkins would be restarted and you would be logged out of the session.

  6. Log back in to Jenkins.

  7. Go to Dashboard > Manage Jenkins > System configuration.

  8. At the bottom of the page, look for Publish over SSH to configure the Docker server. Then, click Add and fill out the required fields. 

  9. Click on the Advanced Tab dropdown and enter the private key that you are using to access your ec2 instance (i.e., Docker). Note: The file should be in the .PEM format.

  10.  Check the Test Configuration and you should get a Success message.

Integrate GitHub with Jenkins

  1. Login to your GitHub account and navigate to your repository where the source code is published. 

  2. Configure GitHub Repository.
    Note: If you don’t have one, create a new repository on GitHub.

    1. Generate Personal Access Token.

    2. Go to Settings > Developer settings > Personal access tokens in GitHub.

    3. Generate a new token with the necessary permissions (repo, for admin:repo_hook).

  3. Configure Jenkins Job.

    1. Create a New Job

    2. Go back to the Jenkins dashboard and click on "New Item".

    3. Enter a name for your job, select "Freestyle project", and click "OK".

  4. Set up GitHub Webhook.

    1. Navigate to your repository on GitHub.

    2. Click on "Settings" > "Webhooks" > "Add webhook".

  5. Configure Webhook
    Payload URL: http://your_jenkins_url/github-webhook/
    Content type: application/json
    Select Just the push event.
    Click Add webhook.

  6. Test the Integration. Make a change in the code and push it to the GitHub.
    Jenkins should automatically trigger a build for the new commit.
    Note: You can get the your_Jenkins_url from Jenkins console, Navigate to Dashboard > Manager Jenkins > System Configuration.

Create Jenkins Pipeline Job

  1. From the Dashboard > New Item > Pipeline.
  2. Enter the name of the job of your choice and select pipeline.
  3. From the General section of the job configuration, enable the GitHub hook trigger for GITScm polling.
  4. Next from the Pipeline option enter the below script.
      
    pipeline {
    agent any
    environment {
        SSH_CREDENTIALS = '4aec1a7f-4e38-415b-a275-3128e2b478e6'
        HVCLIENT_SERVER = 'ip-172-31-86-201.ec2.internal'
    }
    stages {
        stage('SSH into HVCLIENT Server') {
            steps {
                script {
                    sshagent(['4aec1a7f-4e38-415b-a275-3128e2b478e6']) {
                        sh """
                            ssh -o StrictHostKeyChecking=no ubuntu@${HVCLIENT_SERVER} << EOF
                            # Generate a new private key
                            openssl genrsa 2048 > test.key
                            # Generate a new CSR using the private key
                            hvclient -privatekey test.key -commonname pki.atlasqa.co.uk -csrout > csr.pem
                            rm certificate.pem
                            # Fetch a new certificate
                            hvclient -commonname pki.atlasqa.co.uk -dnsnames pki.atlasqa.co.uk -sighash SHA-256 -csr csr.pem | openssl x509 -outform PEM > certificate.pem
                            # Rename test.key to privatek.pem
                            mv test.key privatek.pem
                            # Fetch the trust chain or ch_chain
                            hvclient -trustchain > ca_chain.pem
                            exit
                            EOF
                        """
                        sh 'scp ubuntu@${HVCLIENT_SERVER}:certificate.pem .'
                        sh 'scp ubuntu@${HVCLIENT_SERVER}:privatek.pem .'
                        sh 'scp ubuntu@${HVCLIENT_SERVER}:ca_chain.pem .'
                    }
                }
            }
        }
        stage('Archive Certificate and Private Key') {
            steps {
                archiveArtifacts artifacts: 'certificate.pem, privatek.pem, ca_chain.pem', allowEmptyArchive: false
            }
        }
    }
    post {
        success {
            echo 'Certificate and private key fetched, renamed, and archived successfully!'
        }
        failure {
            echo 'Failed to fetch, rename, or archive certificate and private key!'
        }
    }
}


  5. For the deployment, create a new job following the steps above and paste the code below in the Pipeline option.

pipeline {
    agent any
    tools {
        maven 'localMaven'
        jdk 'localJDK'
    }
    environment {
        GITHUB_CREDENTIALS = credentials('github-pat')
        SSH_CREDENTIALS = '4aec1a7f-4e38-415b-a275-3128e2b478e6'
        REMOTE_SERVER = 'ip-172-31-33-186.ec2.internal'
    }
    stages {
        stage('Fetch Certificates from hvclient Job') {
            steps {
                script {
                    def hvclientBuild = build job: 'hvclient', propagate: true
                    if (hvclientBuild.result == 'SUCCESS') {
                        copyArtifacts projectName: 'hvclient', filter: 'certificate.pem, privatek.pem, ca_chain.pem', target: 'workspace'
                    } else {
                        error "hvclient job failed. Aborting pipeline."
                    }
                }
            }
        }
        stage('Checkout') {
            steps {
                git url: 'https://github.com/iamantil/SampleRegistratonForm.git', credentialsId: "${GITHUB_CREDENTIALS}"
            }
        }
        stage('Build') {
            steps {
                sh 'mvn clean install'
            }
        }
        stage('Test') {
            steps {
                sh 'mvn test'
            }
        }
        stage('Package') {
            steps {
                sh 'mvn package'
            }
        }
        stage('Rename WAR File') {
            steps {
                sh 'mv target/CollegeForm.war ROOT.war'
            }
        }
        stage('Build Docker Images') {
            steps {
                script {
                    // Ensure the necessary files are in the Docker build context
                    sh 'cp workspace/certificate.pem .'
                    sh 'cp workspace/privatek.pem .'
                    sh 'cp workspace/ca_chain.pem .'
                    sh 'docker-compose build'
                }
            }
        }
        stage('Copy Workspace to Remote Server') {
            steps {
                script {
                    sshagent(['4aec1a7f-4e38-415b-a275-3128e2b478e6']) {
                        sh """
                            echo 'Copying files for building the containers'
                            scp -r ${WORKSPACE}/* ubuntu@${REMOTE_SERVER}:/home/ubuntu/
                        """
                    }
                }
            }
        }
        stage('Deploy to Remote Server') {
            steps {
                script {
                    sshagent(['4aec1a7f-4e38-415b-a275-3128e2b478e6']) {
                        sh """
                            ssh -o StrictHostKeyChecking=no ubuntu@${REMOTE_SERVER} << EOF
                            cd /home/ubuntu/
                            docker-compose down
                            docker-compose rm -f
                            docker-compose up -d --build
                            exit
                            EOF
                        """
                    }
                }
            }
        }
    }
    post {
        success {
            echo 'Build and deployment completed successfully!'
        }
        failure {
            echo 'Build or deployment failed!'
        }
    }
}
  6. Bind the ec2 instance public IP address with A record of the your hosted zone. It could be AWS route53 or any other domain registrar.
  7. After setting up the pipeline, you would be able to get the GlobalSign TLS certificates and the container would be secured. When you hit the https://your_domain:8443 you would find the GlobalSign TLS certificate installed.