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

Deploying a full-stack application to a cloud platform can be complex, but by leveraging containerization, Infrastructure as Code (IaC), and automated CI/CD pipelines, the process becomes more manageable and reliable.

In this guide, you’ll learn how to:

• Use Docker Compose to define and manage your application's containers.
• Employ Terraform to provision and maintain the deployment infrastructure on Koyeb.
• Automate the build and deployment process with GitHub Actions.

This combination provides a powerful, repeatable, and scalable workflow that enhances deployment consistency and efficiency.

Whether you are new to Terraform or looking to integrate IaC with Docker workflows, this article will walk you step-by-step to get your full-stack application running seamlessly on Koyeb.

Table of Contents

• Prerequisites
• Terraform Setup and Configuration
• GitHub Actions CI/CD Workflow
• Deploying to Koyeb
• Monitoring Your Deployment
• Conclusion

Prerequisites

Before you begin, ensure you have completed the foundational setup for your full stack application with Docker Compose as detailed in the previous article: How to Deploy a Full Stack App to Koyeb Using Docker Compose and GitHub Actions. This will provide you with the necessary understanding and files such as the Dockerfile and docker-compose.yml used in this deployment.

Additionally, make sure you have the following ready:

• A Koyeb account. If you don’t have one yet, create your Koyeb account here.
• Your Koyeb API token, which you will use to authenticate Terraform and GitHub Actions with Koyeb. (We will cover how to generate this token later.)
• A GitHub repository containing your application’s code and Docker Compose files.
• Basic familiarity with Terraform and GitHub Actions. If you are new to these tools, official documentation and tutorials are excellent starting points:
  • Terraform Documentation
  • GitHub Actions Documentation

Terraform Setup and Configuration

In this section, we will set up Terraform to provision and manage your full-stack application deployment on Koyeb. Terraform acts as the Infrastructure as Code (IaC) tool, defining your Koyeb app and service configurations declaratively. This means you describe what your infrastructure should look like in code, and Terraform handles the creation and updates.

How Terraform Integrates with Koyeb

• Provider: Terraform uses a Koyeb provider plugin that enables it to interact with the Koyeb platform.
• Resources: You define resources such as koyeb_app and koyeb_service to represent your application and its service.
• Git-based Deployment: Your service is configured to deploy code directly from your GitHub repository, using the Docker Compose image described previously.

main.tf Explained

terraform {
  required_providers {
    koyeb = {
      source  = "koyeb/koyeb"
      version = "0.1.11"
    }
  }
}

resource "koyeb_app" "glowberry-application" {
  name = var.app_name
}

resource "koyeb_service" "glowberry-application-service" {
  app_name = koyeb_app.glowberry-application.name

  definition {
    name = var.service_name

    instance_types {
      type = var.instance_type
    }

    ports {
      port     = var.port
      protocol = "http"
    }

    scalings {
      min = 1
      max = 1
    }

    routes {
      path = "/"
      port = var.port
    }

    health_checks {
      http {
        port = var.port
        path = "/"
      }
    }

    regions = ["fra"]

    git {
      branch     = "main"
      repository = "github.com/EphraimX/glowberry-global-tax-structure-simulator-gha-docker-compose-terraform-koyeb"
      dockerfile {
        dockerfile = "Dockerfile.koyeb"
        privileged = true
      }
    }
  }

  depends_on = [
    koyeb_app.glowberry-application
  ]
}

• Terraform Block: Defines the required provider for Koyeb, specifying the source and version to ensure compatibility and reproducibility.
• koyeb_app Resource: Creates a new Koyeb application with a name sourced from the app_name variable.
• koyeb_service Resource: Configures the service linked to the app with:
  • App association: Links the service to the previously created Koyeb app.
  • Instance type: Uses a variable to specify the size/type of the service instance (e.g., nano).
  • Ports: Opens the specified port for HTTP traffic.
  • Scaling: Fixes the service to run one instance.
  • Routing: Defines the root path / to route traffic to the specified port.
  • Health checks: Configures HTTP health checks on the root path to monitor service availability.
  • Region: Sets the deployment region to Frankfurt (fra).
  • Git Integration: Points to the GitHub repository and branch to use for deployment, specifying the Dockerfile to build with privileged mode enabled.
• depends_on: Ensures the service is created only after the app resource exists.

variables.tf Explained

variable "app_name" {
  description = "Koyeb App Name"
  default     = "gtaxsim-gha-dkr-tfkb"
}

variable "service_name" {
  description = "Koyeb Service Name"
  default     = "gtaxsim-gha-dkr-tfkb"
}

variable "instance_type" {
  description = "Koyeb Instance Type"
  default     = "nano"
}

variable "port" {
  description = "Koyeb Port"
  default     = 3000
}

This file defines the variables used in main.tf, providing flexibility and easier configuration without hardcoding values.

• app_name: Name of the Koyeb application.
• service_name: Name of the Koyeb service within the app.
• instance_type: Specifies the compute instance size/type. Defaults to nano for a lightweight, cost-effective deployment.
• port: The network port exposed by the service, set to 3000 to match the frontend application's port.

Absolutely! Here’s the next section, starting with a refresher on how to get and add your Koyeb API token to GitHub Secrets, followed by a detailed explanation of the GitHub Actions workflow file.

Setting Up Your Koyeb API Token in GitHub Secrets

Before running the Terraform deployment via GitHub Actions, you need to securely store your Koyeb API token in your GitHub repository’s secrets. This token allows Terraform (running in the GitHub Actions environment) to authenticate and interact with your Koyeb account.

How to Get Your Koyeb API Token

1. Login to your Koyeb account at https://app.koyeb.com.
2. Navigate to Settings → API Tokens.
3. Click Create API Token.
4. Name your token meaningfully (e.g., GitHub Actions Token).
5. Copy the generated token — you won’t be able to see it again later.

If you are new to Koyeb or cannot find the API token section, check Koyeb’s official docs or support for the latest instructions.

Adding the API Token to GitHub Secrets

1. In your GitHub repository, go to Settings → Secrets and variables → Actions → New repository secret.
2. Set the Name to KOYEB_TOKEN.
3. Paste the API token you copied from Koyeb into the Value field.
4. Save the secret.

This secret will be referenced securely during the GitHub Actions workflow execution without exposing your token publicly.

GitHub Actions Workflow: Terraform Deployment

Now, let’s explore the GitHub Actions workflow file that automates the deployment of your full-stack application on Koyeb using Terraform.

name: glowberry-github-actions-docker-compose-terraform-koyeb

on:
  push:
    branches:
      - main

env:
  TF_LOG: INFO
  TF_INPUT: false

jobs:
  terraform-deploy:
    runs-on: ubuntu-latest
    defaults:
      run:
        shell: bash
        working-directory: ./terraform

    steps:
      - name: Checkout Repository Code
        uses: actions/checkout@v4

      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v2
        with:
          terraform_version: "1.11.4"

      - name: Terraform Deploy
        id: init
        run: |
          export KOYEB_TOKEN=${{secrets.KOYEB_TOKEN}}
          terraform init -backend=false
          terraform fmt -check
          terraform validate -no-color || true 
          terraform plan -no-color
          terraform apply -auto-approve

Workflow Explanation (Step-by-Step)

• Workflow Name and Trigger: The workflow is named glowberry-github-actions-docker-compose-terraform-koyeb and triggers on any push to the main branch. This ensures deployments happen only when code changes are merged or pushed to the main production branch.
• Environment Variables:
  • TF_LOG=INFO enables Terraform’s logging output for better visibility during runs.
  • TF_INPUT=false disables interactive prompts during Terraform runs, necessary for CI environments.
• Job: terraform-deploy: This job runs on the latest Ubuntu runner and executes all commands in the ./terraform directory, where your Terraform files (main.tf, variables.tf) reside.
• Steps:
  1. Checkout Repository Code: Uses the official GitHub Action to fetch your repository code so the workflow can access your Terraform configurations.
  2. Setup Terraform: Installs Terraform version 1.11.4 on the runner using the HashiCorp official action.
  3. Terraform Deploy:
     • Exports the KOYEB_TOKEN environment variable from the GitHub Secrets to authenticate Terraform with Koyeb.
     • Runs terraform init without backend initialization because this setup does not use remote state.
     • Checks Terraform code formatting (terraform fmt -check).
     • Validates the Terraform configuration (terraform validate), ignoring validation errors gracefully to prevent failed runs for minor issues.
     • Executes terraform plan to preview changes that will be applied.
     • Applies the planned changes automatically with terraform apply -auto-approve, deploying your application and infrastructure to Koyeb.

Pushing Code and Monitoring Your Terraform Deployment

Pushing Code to Trigger Deployment

Once you have committed and pushed your updated Terraform configuration files and GitHub Actions workflow (.github/workflows/glowberry-github-actions-docker-compose-terraform-koyeb.yml) to the main branch, GitHub Actions will automatically trigger the workflow.

To push your changes:

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

This push initiates the CI/CD pipeline, which will run the steps defined in the workflow to deploy or update your application on Koyeb.

Monitoring Deployment Progress

1. Navigate to the GitHub Repository: Go to your repository on GitHub.
2. Access the Actions Tab: Click on the Actions tab at the top menu. This displays all workflow runs.
3. View the Workflow Run: You should see a new run for the glowberry-github-actions-docker-compose-terraform-koyeb workflow triggered by your recent push. Click on this run to see details.
4. Check Job Logs: Inside the workflow run, select the terraform-deploy job. Here you can monitor each step’s output live or after completion.
   • Look for successful checkout of the code.
   • Confirm Terraform initialization completes without errors.
   • Review formatting and validation results.
   • Watch the Terraform plan output to verify what infrastructure changes will occur.
   • Finally, confirm that terraform apply completes successfully, indicating your app is deployed or updated on Koyeb.

Conclusion

In this article, you learned how to deploy a full-stack application to Koyeb using Terraform for infrastructure provisioning and GitHub Actions for continuous deployment. This approach leverages Infrastructure as Code, giving you a reliable, repeatable way to manage your deployment environment.

If you haven’t already, check out the earlier Docker Compose deployment article for details on building and containerizing the application.

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.