How to Deploy a Full Stack Application to Koyeb Using Docker Compose, Terraform, and GitLab CI/CD

Deploying a full stack application efficiently requires combining reliable infrastructure management with automated deployment pipelines. In this article, we’ll walk through how to deploy a Docker Compose-based full stack app to Koyeb using Terraform for infrastructure as code and GitLab CI/CD for continuous integration and deployment.

If you haven’t already, please refer to our detailed guide on deploying with Docker Compose, Terraform, and GitHub Actions, which covers the Terraform configuration and Docker setup (in a linked article) in depth. This article focuses specifically on adapting that setup to GitLab’s CI/CD platform, so you can leverage GitLab pipelines to automate your deployments seamlessly.

By the end, you’ll have a clear understanding of configuring GitLab CI/CD to work hand-in-hand with Terraform to deploy and manage your application on Koyeb, enabling a modern, scalable, and maintainable deployment workflow.

Table of Contents

1. Prerequisites
2. Setting Up Koyeb API Token in GitLab CI/CD
3. GitLab CI/CD Pipeline Configuration
4. Deploying to Koyeb with GitLab CI/CD
5. Conclusion

Prerequisites

Before proceeding, ensure you have completed the following:

• Familiarity with the Docker Compose setup: This article builds upon the Docker Compose configuration explained in How to Deploy a Full Stack App to Koyeb Using Docker Compose and GitHub Actions. Please review that article if you haven’t already.
• A Koyeb account: Sign up at https://www.koyeb.com and verify your account.
• GitLab repository access: Ensure your full stack application code is hosted on a GitLab repository.
• Basic knowledge of GitLab CI/CD: If you’re new to GitLab CI/CD, familiarize yourself with GitLab’s pipeline concepts and how to add CI/CD variables. The official documentation is a good starting point: GitLab CI/CD Basics
• Koyeb API Token: You will need your Koyeb API token to allow GitLab to deploy your app. Instructions on obtaining and adding this token to your GitLab project’s CI/CD variables will be covered in the next section.

Obtaining Your Koyeb API Token and Adding It to GitLab

1. Get your Koyeb API token:
   • Log in to your Koyeb dashboard.
   • Navigate to Account Settings > API Tokens.
   • Generate a new token if you don’t have one already.
   • Copy the token securely.
2. Add the token to GitLab:
   • Go to your GitLab project.
   • Navigate to Settings > CI/CD > Variables.
   • Click Add Variable and enter:
     • Key: KOYEB_API_TOKEN
     • Value: (paste your Koyeb API token)
     • Enable Masked and Protected options for security.
   • Save the variable.

GitLab CI/CD Configuration Explained

To get started with GitLab CI/CD, create a file named .gitlab-ci.yml in the root directory of your repository. This file will define the pipeline stages and the necessary steps to build and deploy your application using Terraform on Koyeb. Paste the following configuration into the file to automate the deployment process.

stages:
  - terraform_build_and_deploy

.standard-rules:
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

koyeb-deploy:
  stage: terraform_build_and_deploy
  image: registry.gitlab.com/gitlab-org/terraform-images/stable:latest
  script:
    - cd terraform
    - gitlab-terraform init
    - gitlab-terraform fmt
    - gitlab-terraform validate
    - gitlab-terraform plan
    - gitlab-terraform apply
  variables:
    KOYEB_TOKEN: $KOYEB_API_TOKEN

Breakdown

• stages: Defines the pipeline stages; here, there’s a single stage called terraform_build_and_deploy.
• .standard-rules: This reusable rule ensures the pipeline runs only when the commit is pushed to the default branch (usually main).
• koyeb-deploy job:
  • stage: Specifies which stage this job belongs to.
  • image: Uses an official Terraform Docker image optimized for GitLab CI to run the Terraform commands.
  • script: Runs the following Terraform commands inside the terraform directory:
  • gitlab-terraform init: Initializes Terraform.
  • gitlab-terraform fmt: Checks Terraform code formatting.
  • gitlab-terraform validate: Validates Terraform configuration files.
  • gitlab-terraform plan: Creates and shows an execution plan.
  • gitlab-terraform apply: Applies the Terraform plan automatically, deploying your infrastructure on Koyeb.
  • variables:
  • KOYEB_TOKEN: Passes the Koyeb API token securely from the GitLab CI variable KOYEB_API_TOKEN to authenticate Terraform with Koyeb.

Pushing Code and Monitoring Your Terraform Deployment

Triggering Deployment by Pushing Code

After committing and pushing your updated Terraform configuration along with the .gitlab-ci.yml pipeline file to the default branch (usually main), GitLab CI/CD will automatically trigger the deployment pipeline.

To push your changes, use:

git add .
git commit -m "Add Terraform deployment pipeline for Koyeb"
git push origin main

This push initiates the CI/CD pipeline, which runs the configured jobs to deploy or update your application on Koyeb.

Monitoring the Deployment Process

1. Navigate to Your GitLab Project: Open your project on the GitLab web interface.
2. Go to the Build Pipelines Section: Click on Build in the left sidebar, then select Pipelines. This shows all pipeline runs for your project.
3. Find the Latest Pipeline Run: Locate the most recent pipeline triggered by your push to the main branch, and click on its status to view details.
4. Review Job Logs: Inside the pipeline view, click on the koyeb-deploy job to see step-by-step logs. Look for:
   • Successful checkout of your code repository.
   • Terraform initialization and formatting checks completing without errors.
   • Validation of Terraform configuration.
   • Execution of the plan showing infrastructure changes.
   • Application of the changes with terraform apply completing successfully, confirming your app is deployed or updated on Koyeb.

Conclusion

Deploying your full-stack application to Koyeb using Terraform and GitLab CI/CD streamlines infrastructure management and deployment into an automated, reliable process. By leveraging Terraform’s declarative configuration and GitLab’s powerful pipeline capabilities, you can confidently provision, update, and maintain your deployment environment with minimal manual intervention.

With the setup covered in this guide, every push to your main branch will trigger an automated workflow that handles infrastructure provisioning and application deployment seamlessly. This approach not only boosts development productivity but also ensures consistent, repeatable deployments.

If you’re new to Terraform or GitLab pipelines, consider exploring additional resources to deepen your understanding. Once comfortable, you can extend this setup with advanced Terraform modules, multi-environment deployments, or integration with other tools.

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.