How to Deploy a Full Stack Application to Koyeb Using Docker Compose, Terraform, and Jenkins

In this article, we will walk you through the process of automating the deployment of a full-stack application on Koyeb using Terraform for infrastructure as code, combined with Jenkins as the continuous integration and continuous deployment (CI/CD) tool. Jenkins offers a flexible and widely adopted platform for orchestrating pipelines, enabling teams to build, test, and deploy applications efficiently.

Before proceeding, it is recommended to review the previous article on deploying with Docker Compose and Terraform using GitHub Actions to understand the Terraform configuration and Docker setup. This article will build upon that foundation by focusing on Jenkins for managing the CI/CD pipeline.

We will cover how to configure Jenkins to execute Terraform commands that provision and manage your Koyeb infrastructure, ensuring your application environment is consistent and up-to-date. Whether you’re new to Jenkins or Terraform, this guide provides a clear, step-by-step approach to integrating these powerful tools for seamless cloud deployments.

Table of Contents

1. Prerequisites
2. Obtaining Your Koyeb API Token and Setting Up Jenkins Credentials
3. Creating the Jenkins Pipeline (Jenkinsfile)
4. Pushing Code and Monitoring Deployment
5. Conclusion

Prerequisites

Before proceeding with this guide, ensure you have the following:

• Familiarity with Jenkins pipelines and how to create and manage Jenkins jobs. If you are new to Jenkins pipelines, please refer to this comprehensive Jenkins pipeline tutorial for step-by-step guidance.
• Access to a Jenkins server with permission to create pipelines and manage credentials.
• A Koyeb account with a valid API token. This token is necessary to authenticate Jenkins with Koyeb for deployment. Instructions for obtaining this token are provided in the next section.
• The repository containing the Terraform configuration files for deploying the application to Koyeb. If you haven’t set this up yet, see the supporting article on deploying with Terraform and GitHub Actions for detailed configuration.
• A basic understanding of Terraform and Docker Compose is helpful, though the Terraform configuration is covered in the referenced article above.

Obtaining Your Koyeb API Token and Configuring Jenkins Credentials

To enable Jenkins to deploy your application to Koyeb, you need to generate a Koyeb API token and securely store it in Jenkins as a credential.

How to Get Your Koyeb API Token

1. Log in to your Koyeb dashboard at https://app.koyeb.com.
2. Navigate to Account Settings (usually accessible from the user profile menu).
3. Select the API Tokens section.
4. Click Create New Token.
5. Give your token a descriptive name (e.g., Jenkins Deployment Token) and set appropriate permissions.
6. Generate the token and copy it immediately — you won’t be able to view it again.

Adding the API Token to Jenkins Credentials

1. Log in to your Jenkins server.
2. Go to Manage Jenkins > Manage Credentials.
3. Select the appropriate domain (usually Global).
4. Click Add Credentials.
5. For Kind, select Secret text.
6. In the Secret field, paste your copied Koyeb API token.
7. Give it an ID (for example, KOYEB_API_TOKEN) and optionally a description.
8. Save the credential.

Creating the Jenkinsfile for Terraform Deployment

To automate the deployment of your full-stack application to Koyeb using Terraform and Jenkins, you need to create a Jenkinsfile in the root directory of your repository.

Steps:

1. In your project’s root directory, create a file named Jenkinsfile.
2. Paste the following pipeline script into the Jenkinsfile:

pipeline {
  agent any

  environment {
    KOYEB_TOKEN = credentials('KOYEB_API_TOKEN')
  }

  stages {
    stage('Install Terraform & Deploy') {
      steps {
        dir('terraform') {
          sh '''
            #!/bin/bash
            set -e
            if [ ! -f terraform ]; then
              echo "Downloading Terraform binary..."
              curl -fsSL https://releases.hashicorp.com/terraform/1.11.4/terraform_1.11.4_linux_amd64.zip -o terraform.zip
              unzip terraform.zip
              chmod +x terraform
              rm terraform.zip
            fi

            ./terraform version
            ./terraform init
            ./terraform fmt
            ./terraform validate
            ./terraform plan
            ./terraform apply --auto-approve
          '''
        }
      }
    }
  }
}

Explanation:

• agent any: Runs the pipeline on any available Jenkins agent.
• environment: The KOYEB_TOKEN environment variable is set using the Jenkins credential ID KOYEB_API_TOKEN. Make sure this matches the ID you configured in Jenkins credentials.
• stage ‘Install Terraform & Deploy’:
  • The script moves into the terraform directory where your Terraform configuration files reside.
  • Checks if Terraform binary exists; if not, downloads and extracts Terraform 1.11.4.
  • Runs Terraform commands in sequence:
  • terraform version to confirm the version,
  • terraform init to initialize the working directory,
  • terraform fmt to check formatting,
  • terraform validate to validate the configuration,
  • terraform plan to preview changes,
  • terraform apply to apply infrastructure changes automatically.

Pushing Code and Monitoring Jenkins Pipeline Deployment

Pushing Your Code to Prepare for Deployment

After creating and committing the Jenkinsfile along with your Terraform configuration files in the terraform directory, push the changes to your remote Git repository:

git add Jenkinsfile terraform/
git commit -m "Add Jenkins pipeline for Terraform deployment to Koyeb"
git push origin main

Note: Depending on your Jenkins setup, pushing your code may not automatically trigger the pipeline. You might need to manually start the build by navigating to your Jenkins job and clicking Build Now.

Monitoring the Jenkins Pipeline

1. Access Jenkins Dashboard: Log in to your Jenkins instance and go to the dashboard.
2. Locate Your Pipeline Job: Find the pipeline job configured for this repository (e.g., glowberry-terraform-deploy).
3. Start the Build (If Needed): If the pipeline doesn’t start automatically, click Build Now to initiate the deployment.
4. View Build History: Once started, your build will appear in the build history list.
5. Open Build Details: Click on the latest build number for detailed information.
6. Follow Console Output: Click Console Output to monitor the pipeline logs in real time, including:
   • Terraform download and setup
   • Terraform init, fmt, validate
   • Terraform plan and apply
   • Deployment progress and errors (if any)
7. Confirm Deployment Success: The build is successful if all steps complete without error, and Terraform apply confirms resource creation or updates.

Conclusion

In this article, you learned how to automate the deployment of a full-stack application to Koyeb using Terraform within a Jenkins pipeline. By integrating Infrastructure as Code with your CI/CD process, you achieve consistent, repeatable, and manageable deployments.

With the provided Jenkinsfile and Terraform configuration, you can efficiently provision and update your cloud resources while maintaining full control through Jenkins. This approach enhances deployment reliability and streamlines your development workflow.

For a deeper understanding of the Terraform configuration used here, refer to the supporting article linked in the prerequisites section.

Feel free to explore additional enhancements such as pipeline notifications, environment-specific deployments, or secret management integrations to optimize your deployment process further.

Found this guide helpful? Follow EphraimX for more hands-on DevOps walkthroughs. You can also connect with me on LinkedIn or explore more of my work on my portfolio.