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
- Prerequisites
- Setting Up Your Pulumi Project
- Configuring Pulumi to Deploy on Koyeb
- Storing Your Koyeb API Token in GitHub Secrets
- Creating the GitHub Actions Workflow
- Triggering Deployment: Push and Monitor
- 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
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
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])
)
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
4. .gitignore
To keep your repo clean, add the following file to exclude compiled Python files and the virtual environment folder:
*.pyc
venv/
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
2. Install Dependencies
With the virtual environment activated, install the required Python packages from requirements.txt
:
pip install -r requirements.txt
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
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
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
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
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
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
- Get Your Koyeb API Token: Log in to your Koyeb account and navigate to your API tokens page to create or copy your token.
- Get Your Pulumi Access Token: Sign in to Pulumi (https://app.pulumi.com/), go to Settings > Access Tokens, and create a new access token.
-
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
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.
- Updates the system and installs
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
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
- Open Your GitHub Repository: Navigate to your repository on GitHub.
- Access the Actions Tab: Click on the Actions tab in the repository menu to view recent workflow runs.
-
Locate the Pulumi Deployment Workflow:
Find the latest run titled
glowberry-github-actions-docker-compose-pulumi-koyeb
triggered by your push. - Inspect the Workflow Run: Click on the workflow run to see the detailed job and step logs.
-
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)