DEV Community

Cover image for How to Deploy a Python Backend to Fly.io Using Jenkins
EphraimX
EphraimX

Posted on • Edited on

How to Deploy a Python Backend to Fly.io Using Jenkins

#backend #jenkins #python #devops

Jenkins is one of the most trusted CI/CD tools for developers who want full control over their automation workflows. In this guide, you’ll learn how to set up a Jenkins pipeline that automatically deploys a Python backend application to Fly.io anytime there’s a change in your main branch.

This process is ideal if you want to maintain complete control—no hidden processes, no magic buttons—just a clear, auditable, and customizable CI/CD pipeline.

In this guide, you’ll walk through the exact setup, from creating your Jenkinsfile to storing sensitive tokens securely, and finally testing your deployment live on Fly.io.

Table of Contents

Prerequisites

To follow along with this tutorial, make sure you have the following:

  • A Fly.io account.
  • A Jenkins instance up and running (locally, on a server, or via a CI service).
  • A valid Fly.io API token. You can create one from your Fly.io dashboard under Access Tokens.
  • Basic understanding of your application's structure.

This article uses the same Python backend from our How to Set Up CI/CD for a Python Backend Application on Fly.io Using GitHub Actions. If you haven’t already, go through that article to understand how the application works and how the Dockerfile is structured. That knowledge will be important when setting up Jenkins correctly.

Setting Up Jenkins for CI/CD

Before we can deploy anything with Jenkins, we need to make sure it's up and running correctly. Below is a guide on how to install Jenkins, configure your admin account, and create a pipeline that polls a Git repository.

Option 1: Installing Jenkins via Docker (Recommended)

If you’re comfortable with Docker, this is the fastest way to get started:

docker run -p 8080:8080 -p 50000:50000 \
  -v jenkins_home:/var/jenkins_home \
  jenkins/jenkins:lts
Enter fullscreen mode Exit fullscreen mode

Once running, open http://localhost:8080 in your browser.

Option 2: Installing Jenkins via Script (Linux)

If you're installing Jenkins natively:

# Add Jenkins repository and key
curl -fsSL https://pkg.jenkins.io/debian/jenkins.io-2023.key | sudo tee \
  /usr/share/keyrings/jenkins-keyring.asc > /dev/null

echo deb [signed-by=/usr/share/keyrings/jenkins-keyring.asc] \
  https://pkg.jenkins.io/debian binary/ | sudo tee \
  /etc/apt/sources.list.d/jenkins.list > /dev/null

# Update and install
sudo apt update
sudo apt install jenkins -y

# Start Jenkins
sudo systemctl start jenkins
Enter fullscreen mode Exit fullscreen mode

Jenkins will be accessible at http://localhost:8080.

N.B.: You have to have Java installed on your machine.

First Time Setup

After installation:

  1. Unlock Jenkins: Visit http://localhost:8080. You’ll see a screen asking for an admin password. Run: 
   sudo cat /var/lib/jenkins/secrets/initialAdminPassword
Enter fullscreen mode Exit fullscreen mode
  1. Install Plugins: Choose Install Suggested Plugins.
  2. Create Admin User: Set up your Jenkins username, password, and full name.
  3. Confirm URL: You can leave the Jenkins URL as http://localhost:8080 unless you’re using a custom domain.

Creating a Jenkins Pipeline with Git Polling

  1. Create a New Jenkins Pipeline Job:
    • From your Jenkins dashboard, click New Item.*
    • Enter a name for your job (e.g., backend-deploy-flyio) and select Pipeline.
    • Click OK
  2. Configure the Pipeline:
    • In the Pipeline job config, scroll to Pipeline → Definition, and set it to Pipeline script from SCM
    • Set SCM to Git
    • Paste your repository URL (GitHub or GitLab)
    • (Optional but recommended) Add credentials if the repo is private
  3. Polling the Repository:
    • Scroll down to Build Triggers
    • Tick Poll SCM
    • Use the schedule H/5 * * * * to check for changes every 5 minutes (You can adjust this later for performance)

Once this setup is complete, Jenkins will automatically poll your repo and run the defined pipeline when changes are pushed to the main branch.

Creating the Jenkinsfile for Fly.io Deployment

To configure Jenkins to deploy your Python backend service to Fly.io, you need to create a file named Jenkinsfile in the root directory of your repository. This file defines the steps Jenkins will execute as part of the pipeline.

Paste the following content into your Jenkinsfile:

pipeline {
  agent any

  environment {
    FLY_API_TOKEN = credentials('FLY_API_TOKEN')
  }

  stages {
    stage('Build and Deploy Backend Service') {
      steps {
        dir('backend') {
          sh 'flyctl deploy --remote-only'
        }
      }
    }
  }

  post {
    success {
      echo 'Backend deployed successfully to Fly.io.'
    }
    failure {
      echo 'Backend deployment failed.'
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Explaining the Jenkinsfile

  • pipeline { ... }: This is a declarative Jenkins pipeline. It provides a clear structure for defining the build, test, and deployment lifecycle of your application.
  • agent any: Specifies that the pipeline can run on any available Jenkins agent. This is the default setting and is appropriate unless you are working with a customized or restricted build environment.
  • environment { FLY_API_TOKEN = credentials('FLY_API_TOKEN') }: This section declares environment variables required during the pipeline execution. The credentials() function pulls the FLY_API_TOKEN from Jenkins' credentials store, ensuring that your deployment token is not exposed in plain text. You will need to configure this credential in Jenkins, which we will cover later.
  • stages { ... }: Defines the sequential stages that Jenkins will execute.
  • stage('Build and Deploy Backend Service'): This stage handles the core deployment process.
    • dir('backend'): Navigates into the backend directory of your repository, where the backend application code resides.
    • sh 'flyctl deploy --remote-only': Executes the Fly.io deployment command using the flyctl CLI. The --remote-only flag ensures that the application is packaged locally but built and deployed on Fly.io’s infrastructure, reducing dependencies on your local build environment.
  • post { ... }: This block defines actions that should be executed after the pipeline has finished.
    • success: Prints a message to the console when the deployment succeeds.
    • failure: Prints a message when the deployment fails, which can assist in diagnosing issues during execution.

With this setup in place, Jenkins will be able to automate the process of deploying your backend application to Fly.io whenever a new change is pushed to your repository. In the next section, we will walk you through the secure process of adding the FLY_API_TOKEN to Jenkins.

Setting Up the Fly.io API Token in Jenkins

To enable automated deployments to Fly.io from Jenkins, you need to securely add your Fly.io API token to the Jenkins credentials system. Follow these steps:

Step 1: Access the Credentials Manager

  1. Open your Jenkins dashboard.
  2. Navigate to Manage Jenkins → Credentials → (global) → Add Credentials.

Step 2: Add the Fly.io Token

  1. In the Add Credentials form:
    • Kind: Select Secret text.
    • Secret: Paste your Fly.io API token.
    • ID: Enter FLY_API_TOKEN (make sure it matches the ID used in your Jenkinsfile).
    • Description: (Optional) Add something like Fly.io API Token.
  2. Click OK to save the token.

You can retrieve your Fly.io token by running fly auth token in your terminal after authenticating via fly auth login, or you can generate one from your Fly.io dashboard under Account Settings → Access Tokens.

This credential will be securely accessed in the Jenkins pipeline using the credentials('FLY_API_TOKEN') directive inside the environment block.

Deploying and Testing the Backend Application

Once you’ve created your Jenkinsfile at the root of your repository and configured your Fly.io token, you’re ready to trigger the deployment.

Step 1: Run the Pipeline

  • Click Build Now to trigger your first run.
  • Navigate to the Build History and click the build number to view logs.
  • If configured correctly, you’ll see Jenkins:
    1. Install Fly CLI
    2. Enter the backend/ directory
    3. Deploy your backend service to Fly.io using flyctl deploy --remote-only

Step 2: Verify Deployment

Fly.io Dashboard

  • Visit your Fly.io dashboard and confirm the deployment under the targeted app.
  • You can also run fly status locally to inspect the deployment.

Conclusion

Integrating Jenkins into your Fly.io deployment pipeline gives you more than just automation—it offers control. By managing your own CI/CD infrastructure, you can introduce custom build logic, stage-specific testing, and gated deploy conditions, all without compromising flexibility.

In this guide, you learned how to install Jenkins, connect your Git repository, and configure a Jenkinsfile that handles your backend deployment with Fly.io. You also saw how to monitor builds directly from the Jenkins dashboard and verify successful deployments via the Fly.io console.

With this foundation in place, you're better equipped to scale your CI/CD setup, customize build stages, and adopt a more production-grade engineering workflow.

If this helped you, consider following EphraimX on GitHub for more articles and open-source automation projects. You can also follow me on LinkedIn and explore more of my work on my portfolio.

Top comments (0)