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

CircleCI offers a developer-friendly and efficient CI/CD experience, making it an excellent choice for automating deployment workflows for containerized applications. In this guide, you'll learn how to deploy a full-stack Docker Compose application to Koyeb using CircleCI.

We’ll configure a custom pipeline that uses the Koyeb CLI and leverages the Dockerfile-based deployment mechanism. This approach mirrors our previous GitHub Actions, GitLab CI/CD, and Jenkins guides but focuses specifically on CircleCI's environment and capabilities.

If you haven’t yet reviewed the foundational article that walks through the project setup, Dockerfiles, and Docker Compose configuration, please start there: Deploying a Full Stack App to Koyeb Using Docker Compose and GitHub Actions

Once you're familiar with the application structure and build context, proceed with this article to integrate CircleCI into your workflow.

Prerequisites
Obtaining Your Koyeb API Token
Configuring CircleCI Environment Variables
CircleCI Pipeline Configuration
Deploying to Koyeb Using CircleCI
Conclusion

Prerequisites

Before diving into the CircleCI setup and deployment process, make sure you have the following:

Familiarity with the Full Stack Application Setup: This article builds on the foundation laid in the previous article, How to Deploy a Full Stack App to Koyeb Using Docker Compose and GitHub Actions. It’s recommended to review that article first for context on the application structure and Docker setup.
CircleCI Account: You need an active CircleCI account connected to your GitHub repository where the application code resides. If you don’t have one, sign up at circleci.com.
Koyeb Account: A Koyeb account is required to deploy your application. Simply create an account at koyeb.com if you don’t have one.
Koyeb API Token: You will need a Koyeb API token for authentication when deploying via CircleCI. Instructions for obtaining this token will be covered in the next section.
Basic Understanding of CircleCI Pipelines: If you are new to CircleCI pipelines or configuration, consider reviewing the official CircleCI documentation or refer to my article on setting up CI/CD pipelines with CircleCI.

Obtaining Your Koyeb API Token

To deploy your application to Koyeb using CircleCI, you'll need a Koyeb API token for authentication. Follow these steps to generate one:

Log in to your Koyeb account: Visit app.koyeb.com and sign in.
Access Account Settings: Click on your profile icon in the top-right corner and select "Account Settings".
Navigate to API Access Tokens: In the left sidebar, click on "API Access Tokens".
Create a New Token:
- Click the "Create API Access Token" button.
- Provide a name and description for the token to help identify its purpose.
- Click "Create".
Save the Token: Once generated, copy the token immediately. For security reasons, you won't be able to view it again.

Adding the Koyeb API Token to CircleCI

To securely store and use your Koyeb API token in your CircleCI pipeline, add it as an environment variable:

Log in to CircleCI: Go to circleci.com and sign in.
Navigate to Your Project: From the dashboard, select the project where your application resides.
Access Project Settings:
- Click on the gear icon next to your project name.
- Select "Project Settings".
Add an Environment Variable:
- In the left sidebar, click on "Environment Variables".
- Click the "Add Variable" button.
- In the "Name" field, enter KOYEB_API_TOKEN.
- In the "Value" field, paste the API token you copied earlier.
- Click "Add Variable" to save.

This environment variable will now be accessible in your CircleCI jobs and can be used to authenticate with the Koyeb API.

Setting Up CircleCI Configuration

First, create a .circleci directory at the root of your project if it doesn't already exist:

mkdir -p .circleci

Next, inside this directory, create a file named config.yml and paste the following code:

version: 2.1
jobs:
  deploy:
    docker:
      - image: ubuntu:24.04
    steps:
      - checkout
      - run:
          name: Install Curl and Koyeb CLI
          command: |
            apt-get update
            apt-get install -y curl
            curl -fsSL https://raw.githubusercontent.com/koyeb/koyeb-cli/master/install.sh | sh
            export PATH=$HOME/.koyeb/bin:$PATH
            export KOYEB_TOKEN=${KOYEB_API_TOKEN}
            koyeb app create glowberry-tax-structure-simulator-glabcicd-docker-compose-koyeb || echo "App already exists"
            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

workflows:
  build-and-deploy-to-koyeb:
    jobs:
      - deploy

Explanation of the CircleCI Configuration

version: 2.1 Specifies the CircleCI configuration version used.
jobs: Defines a set of jobs CircleCI will run. Here, we have a single job named deploy.
deploy job:
- docker: Runs the job inside an Ubuntu 24.04 Docker container.
- steps:
- checkout: Checks out your repository code so the job can use it.
- run step named Install Curl and Koyeb CLI:
  - Updates package lists and installs curl.
  - Downloads and installs the Koyeb CLI tool.
  - Updates the PATH to include the Koyeb CLI.
  - Sets the environment variable KOYEB_TOKEN from the CircleCI environment variable ${KOYEB_API_TOKEN}.
  - Runs koyeb app create to create the app if it doesn't already exist (ignores error if it does).
  - Runs koyeb service create with detailed parameters to deploy the app and service to Koyeb.
workflows: Defines the workflow that triggers jobs. Here, it runs the deploy job under the name build-and-deploy-to-koyeb.

Pushing to GitHub and Monitoring Your Deployment

Once your .circleci/config.yml file is ready and committed to your project repository, you can trigger the deployment process by pushing your code to GitHub.

Steps to Trigger Deployment

Commit your changes:

   git add .circleci/config.yml
   git commit -m "Add CircleCI config for Koyeb deployment"

Push to your repository:

   git push origin main

Replace main with your default branch if different.

Monitoring the Deployment on CircleCI

After pushing, CircleCI will automatically detect the changes and start the pipeline based on your config file.
To monitor the deployment progress:
1. Log in to your CircleCI dashboard at https://app.circleci.com/.
2. Navigate to your project’s pipeline page.
3. Click on the running job (usually labeled deploy under the workflow name build-and-deploy-to-koyeb).
4. View detailed logs of each step in the job, including:
  - Checkout your repo code.
  - Installation of curl and the Koyeb CLI.
  - Koyeb app and service creation commands.
Any errors during the deployment will appear here, allowing you to troubleshoot quickly.

Conclusion

In this guide, you’ve learned how to automate the deployment of a full-stack application to Koyeb using CircleCI and Docker Compose. By configuring your CircleCI pipeline with the Koyeb CLI, you ensure that every push to your repository triggers a seamless build and deployment process.

This approach eliminates manual deployment steps, reducing errors and accelerating your development workflow. With the environment variables securely stored in CircleCI and the deployment status easily monitored via the CircleCI dashboard, managing your application lifecycle becomes efficient and transparent.

If you want to explore other CI/CD tools, consider our articles on GitHub Actions, GitLab CI/CD, and Jenkins integrations with Koyeb.

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.