DEV Community

Cover image for How to Deploy a Full Stack Application to Koyeb Using Pulumi, Docker Compose and GitHub Actions
EphraimX
EphraimX

Posted on

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

In modern DevOps workflows, Infrastructure as Code (IaC) tools like Pulumi offer powerful, flexible, and developer-friendly ways to define and manage infrastructure using general-purpose programming languages. When paired with CI/CD tools like GitHub Actions, you can fully automate the provisioning and deployment of cloud infrastructure — from code to production — using code you already understand.

In this guide, you'll learn how to deploy a full stack Docker Compose application to Koyeb using Pulumi for infrastructure configuration and GitHub Actions for continuous deployment.

We’ll assume you’ve already containerized your app and understand basic Docker Compose and CI/CD concepts. If you’re new to those, check out our earlier guide: Deploying a Full Stack App to Koyeb with Docker Compose and GitHub Actions

Table of Contents

  1. Prerequisites
  2. Setting Up Your Pulumi Project
  3. Configuring Pulumi to Deploy on Koyeb
  4. Storing Your Koyeb API Token in GitHub Secrets
  5. Creating the GitHub Actions Workflow
  6. Triggering Deployment: Push and Monitor
  7. Conclusion

Prerequisites

Before proceeding, ensure you have the following ready:

  • Read the Docker Compose Deployment Article: This article builds on deploying the Glowberry full-stack app with Docker Compose. Please review that article if you haven’t already.
  • GitHub Repository: Your Glowberry project should be pushed to a GitHub repository with the Docker Compose setup completed.
  • Pulumi CLI Installed: Install Pulumi on your local machine. See Pulumi Installation for detailed steps.
  • GitHub Account: Access to your repository with permissions to create GitHub Actions workflows and add secrets.
  • Koyeb Account and API Token: Create a Koyeb account if you don’t have one, and generate an API token. You’ll add this token as a secret in GitHub.
  • Basic familiarity with Infrastructure as Code (IaC): Prior experience with Pulumi or similar IaC tools will be helpful but not required.

Setting Up Pulumi Infrastructure for Glowberry on Koyeb

To begin managing your Glowberry deployment with Pulumi, create a dedicated directory for your Pulumi infrastructure files:

mkdir pulumi-koyeb
cd pulumi-koyeb
Enter fullscreen mode Exit fullscreen mode

Inside this folder, you’ll create the following essential files:

1. Pulumi.yaml

This file configures the Pulumi project, specifying its name, runtime, and Python virtual environment settings:

name: pulumi-koyeb
description: Infrastructure for Glowberry Tax Simulator
runtime:
  name: python
  options:
    toolchain: pip
    virtualenv: venv
config:
  pulumi:tags:
    value:
      pulumi:template: python
Enter fullscreen mode Exit fullscreen mode

2. __main__.py

This Python script defines the infrastructure as code, using the Pulumi Koyeb provider to create the app and service resources:

"""Pulumi Infrastructure for Glowberry Tax Simulator"""

import pulumi
import pulumi_koyeb as koyeb


glowberry_application = koyeb.App("gtaxsim-gha-dkr-plkb", name="gtaxsim-gha-dkr-plkb")

glowberry_application_service = koyeb.Service("gtaxsim-gha-dkr-plkb-service",

    app_name=glowberry_application.name,
    definition={
        "name": "gtaxsim-gha-dkr-plkb",
        "instance_types": [{
            "type": "nano",
        }],
        "ports": [{
            "port": 3000,
            "protocol": "http",
        }],
        "scalings": [{
            "min": 1,
            "max": 1,
        }],
        "envs": [
            {
                "key": "PORT",
                "value": "3000",
            },
        ],
        "routes": [{
            "path": "/",
            "port": 3000,
        }],
        "regions": ["fra"],
        "git": {
            "branch": "main",
            "repository": "github.com/EphraimX/glowberry-global-tax-structure-simulator-gha-docker-compose-pulumi-koyeb",
            "dockerfile": {
                "dockerfile": "Dockerfile.koyeb",
                "privileged": True,
            },
        },
    },
  opts = pulumi.ResourceOptions(depends_on=[glowberry_application])
)
Enter fullscreen mode Exit fullscreen mode

3. requirements.txt

This file lists all the Python dependencies required for Pulumi and the Koyeb provider:

Arpeggio==2.0.2
attrs==25.3.0
debugpy==1.8.14
dill==0.4.0
grpcio==1.66.2
parver==0.5
protobuf==4.25.7
pulumi==3.167.0
pulumi_koyeb==0.1.11
PyYAML==6.0.2
semver==3.0.4
setuptools==80.1.0
wheel==0.45.1
Enter fullscreen mode Exit fullscreen mode

4. .gitignore

To keep your repo clean, add the following file to exclude compiled Python files and the virtual environment folder:

*.pyc
venv/
Enter fullscreen mode Exit fullscreen mode

This setup forms the foundation of your Pulumi infrastructure project to deploy the Glowberry application on Koyeb. Next, you’ll learn how to initialize and configure Pulumi locally before integrating it with GitHub Actions for automated deployment.

Initializing and Running Pulumi Locally

Before integrating Pulumi with GitHub Actions, you should first test and deploy your infrastructure locally to ensure everything works as expected.

1. Set Up a Python Virtual Environment

In your pulumi-koyeb directory, create and activate a virtual environment to isolate your Python dependencies:

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
Enter fullscreen mode Exit fullscreen mode

2. Install Dependencies

With the virtual environment activated, install the required Python packages from requirements.txt:

pip install -r requirements.txt
Enter fullscreen mode Exit fullscreen mode

3. Install the Pulumi CLI

Make sure you have the Pulumi CLI installed on your system. You can download it from the official site: https://www.pulumi.com/docs/get-started/install/

Confirm installation by running:

pulumi version
Enter fullscreen mode Exit fullscreen mode

4. Login to Pulumi

Pulumi requires you to be logged in to manage your stacks. For local testing, use the local backend:

pulumi login --local
Enter fullscreen mode Exit fullscreen mode

5. Configure Koyeb API Token

Pulumi needs your Koyeb API token to authenticate and deploy resources. Set it as a Pulumi config secret:

pulumi config set koyeb:token <YOUR_KOYEB_API_TOKEN> --secret
Enter fullscreen mode Exit fullscreen mode

Replace <YOUR_KOYEB_API_TOKEN> with your actual Koyeb API token.

6. Preview the Infrastructure

Run the following command to see what Pulumi will create or update without making changes:

pulumi preview
Enter fullscreen mode Exit fullscreen mode

This gives you a detailed plan of the infrastructure changes.

7. Deploy the Infrastructure

If the preview looks good, apply the changes to deploy your Glowberry app on Koyeb:

pulumi up --yes
Enter fullscreen mode Exit fullscreen mode

Pulumi will provision the app and service defined in your __main__.py.

With these steps, you can confidently manage and test your infrastructure locally before automating deployments. Next, we’ll integrate this setup with GitHub Actions for continuous deployment.

Setting Up GitHub Actions for Pulumi Deployment

Before creating the GitHub Actions workflow, you need to securely store the required credentials in your GitHub repository settings.

Add Required Secrets to GitHub

  1. Get Your Koyeb API Token: Log in to your Koyeb account and navigate to your API tokens page to create or copy your token.
  2. Get Your Pulumi Access Token: Sign in to Pulumi (https://app.pulumi.com/), go to Settings > Access Tokens, and create a new access token.
  3. Add Secrets in GitHub: In your GitHub repository, go to Settings > Secrets and variables > Actions > New repository secret, then add:
    • KOYEB_TOKEN — your Koyeb API token
    • PULUMI_ACCESS_TOKEN — your Pulumi access token

Create the Workflow File

In your repository, create a folder called .github/workflows (if it doesn’t exist), and inside that folder create a file named glowberry-github-actions-docker-compose-pulumi-koyeb.yml. Paste the following workflow code into that file:

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

on:
  push:
    branches:
      - main

jobs:
  pulumi-deploy:
    runs-on: ubuntu-latest

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

      - name: Koyeb Setup and Deploy
        working-directory: ./pulumi-koyeb
        run: |
          sudo apt-get update
          sudo apt-get install -y curl
          export KOYEB_TOKEN=${{secrets.KOYEB_TOKEN}}
          export PULUMI_ACCESS_TOKEN=${{secrets.PULUMI_ACCESS_TOKEN}}
          curl -fsSL https://get.pulumi.com | sh
          mkdir -p ~/.pulumi/plugins/resource-koyeb-v0.1.11
          curl -L https://github.com/koyeb/pulumi-koyeb/releases/download/v0.1.11/pulumi-resource-koyeb-v0.1.11-linux-amd64.tar.gz | tar -xz -C ~/.pulumi/plugins/resource-koyeb-v0.1.11
          export PATH=$HOME/.pulumi/bin:$PATH
          pulumi login
          pulumi stack select glowberry-dev-gha-stack || pulumi stack init glowberry-dev-gha-stack
          pulumi preview
          pulumi up -y
Enter fullscreen mode Exit fullscreen mode

Workflow Explanation

  • Trigger: This workflow runs on every push to the main branch.
  • Checkout Step: Pulls your repository code to the runner.
  • Setup and Deploy Step:
    • Updates the system and installs curl.
    • Exports your Koyeb and Pulumi tokens from GitHub Secrets as environment variables.
    • Installs the Pulumi CLI.
    • Downloads and installs the Koyeb Pulumi resource plugin (version 0.1.11).
    • Adds Pulumi to the PATH.
    • Logs into Pulumi using the CLI.
    • Selects or creates a Pulumi stack named glowberry-dev-gha-stack.
    • Runs pulumi preview to show what will be deployed.
    • Runs pulumi up -y to deploy the infrastructure automatically. This CI/CD pipeline automates deploying your Glowberry full-stack app on Koyeb using Pulumi, triggered by code pushes.

Pushing Code and Monitoring Your Pulumi Deployment

Pushing Code to Trigger Deployment

After creating the Pulumi setup and the GitHub Actions workflow file, committing and pushing your changes to the main branch will automatically trigger the deployment pipeline.

To push your changes, run:

git add .
git commit -m "Add Pulumi deployment workflow for Koyeb"
git push origin main
Enter fullscreen mode Exit fullscreen mode

This push activates the GitHub Actions workflow glowberry-github-actions-docker-compose-pulumi-koyeb.yml, initiating the deployment of your infrastructure via Pulumi.

Monitoring Deployment Progress

  1. Open Your GitHub Repository: Navigate to your repository on GitHub.
  2. Access the Actions Tab: Click on the Actions tab in the repository menu to view recent workflow runs.
  3. Locate the Pulumi Deployment Workflow: Find the latest run titled glowberry-github-actions-docker-compose-pulumi-koyeb triggered by your push.
  4. Inspect the Workflow Run: Click on the workflow run to see the detailed job and step logs.
  5. Review the Logs for Deployment Status:
    • Confirm the checkout step succeeded.
    • Verify installation of Pulumi CLI and Koyeb Pulumi plugin without errors.
    • Check the output of pulumi preview to understand the infrastructure changes planned.
    • Monitor the pulumi up step to ensure successful deployment or updates to your application on Koyeb.

If any step fails, the logs provide detailed error messages to help you troubleshoot.

Conclusion

In this guide, you’ve learned how to deploy a full-stack application on Koyeb using Pulumi for infrastructure as code and GitHub Actions to automate your CI/CD pipeline. This approach offers powerful infrastructure management with Pulumi’s flexible Python SDK, combined with the automation and integration capabilities of GitHub Actions.

By setting up Pulumi locally and configuring the GitHub workflow to run your deployment, you gain a streamlined, repeatable process to provision and update your cloud resources efficiently. You can easily extend this foundation to support more complex infrastructure needs or integrate with other tools in your development workflow.

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.

Top comments (0)