How to Deploy a Full Stack App to Koyeb Using Docker Compose and Jenkins

Jenkins remains one of the most powerful and flexible tools in the CI/CD space—widely adopted for its extensibility and tight control over build pipelines. In this article, we’ll explore how to deploy a full-stack Docker Compose application to Koyeb using a Jenkins pipeline.

Unlike managed CI/CD platforms like GitHub Actions or GitLab CI/CD, Jenkins gives you complete control over the environment and pipeline steps. This makes it a great choice when you need custom configurations, self-hosted agents, or integration with complex systems.

We’ll skip the broader details of the application setup itself. If you haven’t already, you should read the foundational GitHub Actions article for insights into the Dockerfiles, Docker Compose configuration, and the overall structure of the Glowberry Global Tax Structure Simulator app. This guide will focus entirely on the Jenkins pipeline configuration and how to automate the deployment to Koyeb from there.

Let’s get started.

Table of Contents

• Prerequisites
• Configuring Koyeb API Token in Jenkins
• Jenkins Pipeline Setup
• Understanding the Deployment Steps
• Executing the Pipeline
• Conclusion

Prerequisites

Before proceeding with this Jenkins-specific guide, ensure the following prerequisites are met:

• Read the Supporting Article: This article builds on concepts covered in How to Deploy a Full Stack App to Koyeb Using Docker Compose and GitHub Actions. That guide explains the structure of the application, Docker setup, and how Docker Compose and Dockerfile.koyeb drive the deployment. Please review it first to understand the foundational components.
• Jenkins Installed and Running: You should have Jenkins installed and accessible on your system or through a server (such as localhost or a cloud VM).
• Jenkins User with Required Permissions: Ensure your Jenkins user has the necessary permissions to manage credentials and execute pipelines.
• Install Required Jenkins Plugins:
  • Pipeline
  • GitHub Integration
  • Git Plugin
  • Docker Pipeline
  • Environment Injector (for managing environment variables)
• Koyeb Account: If you haven’t already, create a Koyeb account. This guide assumes you have access to it and can generate an API token.
• Koyeb API Token: You’ll need a valid Koyeb API token for deployment. We'll walk through storing it securely in Jenkins shortly.
• GitHub Repository: Your application should be stored in a GitHub repository accessible to Jenkins.

Absolutely. Here’s a concise section explaining how to retrieve your Koyeb API key before using it in Jenkins:

Retrieving Your Koyeb API Token

To interact with Koyeb from CI/CD tools like Jenkins, you'll need a Koyeb API token. Here's how to get it:

How to Generate a Koyeb API Token

1. Log In to Your Koyeb Account Visit https://app.koyeb.com and sign in
2. Go to Account Settings Click on your profile icon at the top-right corner and select Account Settings.
3. Navigate to the API Tab In the settings sidebar, click on API.
4. Generate a New API Token
   • Click the Generate API Token button.
   • Give your token a descriptive name (e.g., jenkins-deployment-token).
   • Choose the appropriate scope (typically full access for CI/CD).
   • Click Create Token and copy the token immediately—this is the only time it will be fully visible.

Once retrieved, you can securely store the token in Jenkins as described in the next section.

Configuring Koyeb API Token in Jenkins

To allow Jenkins to securely deploy your application to Koyeb, you'll need to store your Koyeb API token as a Secret Text credential in Jenkins. Follow these steps carefully:

Step-by-Step: Store Koyeb API Token in Jenkins

1. Access Jenkins Dashboard Log into your Jenkins instance.
2. Navigate to Credentials From the sidebar, go to: Manage Jenkins → Credentials → (select a domain or Global) → Add Credentials
3. Select Credential Type
   • Kind: Choose Secret text
   • Secret: Paste your Koyeb API token here
   • ID: Use a simple identifier like KOYEB_API_TOKEN
   • Description: Optional, e.g., “Koyeb token for CI/CD deployment”
4. Save Click OK to save the credential.

Jenkins will now securely reference this token using the ID KOYEB_API_TOKEN in your pipeline.

New to Jenkins Pipelines?

If you're unfamiliar with how to create or run a Jenkins pipeline, I’ve written a companion article to guide you through the process. It covers creating a Jenkinsfile, setting up a pipeline job, and connecting it to a GitHub repository. Refer to the Jenkins Pipeline Setup Guide

Creating the Jenkinsfile for Your Pipeline

With your Koyeb API token securely stored in Jenkins credentials (as KOYEB_API_TOKEN), you’re ready to define your CI/CD pipeline.

Follow these steps:

1. Create the Jenkinsfile

In the root directory of your project repository, create a file named Jenkinsfile with no extension.

2. Paste the Following Code into the Jenkinsfile

pipeline {

  agent any

  environment {
    KOYEB_API_TOKEN = credentials('KOYEB_API_TOKEN')
  }

  stages {

    stage('Koyeb Setup and Deploy Job') {
      steps {
        // sh 'apt install curl' // Uncomment if curl is not installed on your Jenkins agent
        sh 'curl -fsSL https://raw.githubusercontent.com/koyeb/koyeb-cli/master/install.sh | sh'
        sh '''
          export PATH="/var/jenkins_home/.koyeb/bin:$PATH"
          export KOYEB_TOKEN=$KOYEB_API_TOKEN
          koyeb app create glowberry-tax-structure-simulator-glabcicd-docker-compose-koyeb
          koyeb service create glowberry-tax-structure-simulator-glabcicd-docker-compose-koyeb \
            --app glowberry-tax-structure-simulator-glabcicd-docker-compose-koyeb \
            --git github.com/EphraimX/glowberry-global-tax-structure-simulator-gha-docker-compose-koyeb \
            --instance-type free \
            --git-builder docker \
            --git-docker-dockerfile Dockerfile.koyeb \
            --port 3000:http \
            --route /:3000 \
            --privileged
        '''
      }
    }

  }
}

• pipeline: Declares a declarative Jenkins pipeline.
• agent any: Runs the pipeline on any available agent.
• environment: Injects the stored Koyeb API token from Jenkins credentials into the environment.
• stage('Koyeb Setup and Deploy Job'): This stage does the heavy lifting:
  • Installs the Koyeb CLI via curl.
  • Updates the PATH so the CLI is accessible.
  • Sets the KOYEB_TOKEN environment variable.
  • Uses the Koyeb CLI to:
    • Create the app (if it doesn’t already exist).
    • Deploy the service using:
    • Dockerfile.koyeb as the deployment entry point.
    • The docker Git builder.
    • Port 3000 exposed publicly.
    • Route all root requests to port 3000.
    • The --privileged flag (important for some internal service behavior).

If curl is not installed on your Jenkins agent, simply uncomment the apt install curl line near the top.

Deploying to Koyeb with Jenkins

Once your Jenkinsfile is in place and committed to your repository, deploying your application becomes a matter of triggering a Jenkins pipeline build. Here's how to proceed:

1. Push Your Code to the Repository

Commit and push your updated project — including the new Jenkinsfile — to the main branch (or the branch your Jenkins job is configured to track).

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

Make sure your Jenkins job is configured to monitor the correct repository and branch.

2. Trigger the Jenkins Job

• If your Jenkins project is configured for polling SCM or webhook-based triggers, Jenkins will automatically detect the new commit and run the job.
• If not, you can manually trigger the job from the Jenkins dashboard by clicking "Build Now".

3. Monitor the Build

• Navigate to your Jenkins dashboard.
• Click on your project, then click on the build under the "Build History" section.
• Use the "Console Output" tab to monitor the step-by-step progress of your pipeline.

If everything is configured correctly:

• The pipeline will install the Koyeb CLI.
• Authenticate with the Koyeb API using your secret token.
• Create the app and service.
• Deploy your application using the Dockerfile.koyeb and the docker-compose.yml file.

4. Verify the Deployment

After a successful build:

• Visit your Koyeb dashboard.
• Locate the app and service by name.
• Open the service URL to access your deployed frontend application running on port 3000.

Conclusion

Integrating Jenkins into your CI/CD workflow to deploy a full-stack Docker Compose application to Koyeb gives you fine-grained control over your build and release processes. By leveraging the Dockerfile.koyeb, automating deployment through the Koyeb CLI, and managing secrets securely within Jenkins, you can achieve repeatable and consistent deployments across environments.

If you're already maintaining infrastructure with Jenkins, this method fits seamlessly into your pipeline architecture. For developers transitioning from other CI/CD systems, Jenkins remains a powerful and flexible alternative, especially when paired with a platform like Koyeb that abstracts infrastructure complexity.

With this foundation in place, you can now iterate faster, maintain confidence in your deployments, and explore more advanced Jenkins features such as parallel builds, test automation, and staged rollouts.

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.