Jenkins Shared Library for Docker CI/CD

This shared library provides reusable components for automating CI/CD processes with Docker and Portainer/Komodo.

🏗️ Structure

├── src/
│   ├── org/dockerutils/
│   │   └── DockerUtils.groovy    # Docker utilities
│   ├── org/portainer/
│   │   └── PortainerUtils.groovy # Portainer API utilities
│   └── org/komodo/
│       └── KomodoUtils.groovy    # Komodo API utilities
└── vars/
    └── multiEnvPipeline.groovy   # Main multi-environment pipeline

📦 Components

DockerUtils

Utility class for working with Docker images.

Methods

buildAndPush(ctx, repo, tags, user, pass)

Builds and pushes a Docker image with multiple tags.

Parameters:

• ctx - Reference to CpsScript (Pipeline context)
• repo - Full repository path without tag (registry/namespace/app)
• tags - List of tags for the image
• user - Login for registry
• pass - Password/token for registry

Example:

@Library('docker-lib') _
import org.dockerutils.DockerUtils

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                script {
                    DockerUtils.buildAndPush(
                        this,
                        'registry.example.com/myapp',
                        ['v1.0.0', 'latest'],
                        'username',
                        'password'
                    )
                }
            }
        }
    }
}

cleanup(ctx, repo, tags)

Removes local Docker images after building.

isRegistryAvailable(ctx, registry)

Checks the availability of a Docker registry.

PortainerUtils

Utility class for working with the Portainer API.

Methods

authenticate(ctx, url, username, password)

Authenticates with Portainer and obtains a JWT token.

deployByBranch(ctx, config)

Complete deployment cycle by Git branch name.

Example:

@Library('docker-lib') _
import org.portainer.PortainerUtils

PortainerUtils.deployByBranch(this, [
    url: 'http://portainer.example.com',
    username: 'admin',
    password: 'password',
    branchName: 'main'
])

deployByStackName(ctx, config)

Complete deployment cycle by stack name.

findStackByBranch(ctx, url, token, branchName)

Finds a stack by Git branch name.

findStackByName(ctx, url, token, stackName)

Finds a stack by name.

redeployStack(ctx, url, token, stackId, endpointId, referenceName)

Redeploys a specific stack.

isApiAvailable(ctx, url)

Checks the availability of the Portainer API.

deployStack(ctx, config)

Universal method for creating or updating a stack from a compose file.

KomodoUtils

Utility class for working with the Komodo API.

Methods

authenticate(ctx, url, username, password)

Authenticates with Komodo and obtains a JWT token.

deployByBranch(ctx, config)

Complete deployment cycle by Git branch name.

Example:

@Library('docker-lib') _
import org.komodo.KomodoUtils

KomodoUtils.deployByBranch(this, [
    url: 'http://komodo.example.com',
    username: 'admin',
    password: 'password',
    branchName: 'main'
])

findStackByBranch(ctx, url, token, branchName)

Finds a stack by Git branch name.

findStackByName(ctx, url, token, stackName)

Finds a stack by name.

redeployStack(ctx, url, token, stackId, endpointId, referenceName)

Redeploys a specific stack.

isApiAvailable(ctx, url)

Checks the availability of the Komodo API.

deployStack(ctx, config)

Universal method for creating or updating a stack from a compose file.

multiEnvPipeline

Main pipeline for deployment across multiple environments.

Supported Branches

• dev - Build image (no deployment)
• staging - Build + automatic deployment to staging
• main - Build + deployment to production

Configuration

@Library('docker-lib') _

multiEnvPipeline([
    registry: 'registry.example.com',             // Docker registry URL
    credentials: 'docker-reg-creds',              // Jenkins credentials ID for Docker
    imageRepo: 'myapp/service',                   // Image name
    deployPlatform: 'portainer',                  // Deployment platform: 'portainer' or 'komodo'
    portainerUrl: 'http://portainer.example.com', // Portainer API URL (if deployPlatform = 'portainer')
    komodoUrl: 'http://komodo.example.com',       // Komodo API URL (if deployPlatform = 'komodo')
    deployBranches: ['main', 'staging'],          // Branches for deployment
    gitCredentials: 'jenkins_gitlab',             // Credentials for Git
    portainerCreds: 'portainer-creds',            // Credentials for Portainer
    komodoCreds: 'komodo-creds'                   // Credentials for Komodo
])

Usage Example

// Jenkinsfile
@Library('docker-lib') _

multiEnvPipeline([
    imageRepo: 'acme/order-service',
    portainerUrl: 'https://portainer.company.com'
])

🔧 Setup

1. Connecting the Library

In Jenkins, configure Global Pipeline Libraries:

• Name: docker-lib
• Default version: master
• Retrieval method: Modern SCM → Git
• Project Repository: https://github.com/your-organization/docker-lib.git

2. Credentials

Create the following credentials in Jenkins:

• docker-reg-creds - Username/Password for Docker registry
• jenkins_gitlab - Username/Password for GitLab
• portainer-creds - Username/Password for Portainer
• komodo-creds - Username/Password for Komodo

3. Docker Agent

Ensure you have a Docker agent configured with the label docker-agent-label.

🌟 Features

• ✅ Multi-environment - Automatic strategy determination by branch
• ✅ Security - Using Jenkins credentials
• ✅ Optimization - Buildkit, tagging without rebuilding
• ✅ Monitoring - Detailed logging and error handling
• ✅ Integration - Automatic deployment via Portainer/Komodo API
• ✅ Cleanup - Automatic removal of local images
• ✅ Modularity - Separate utility classes for Docker, Portainer and Komodo
• ✅ Reusability - Flexible methods for different deployment scenarios
• ✅ Platform choice - Support for Portainer and Komodo

🚀 Workflow

graph TD
    A[Push to Git] --> B{Branch?}
    B -->|dev| C[Build Only]
    B -->|staging| D[Build + Deploy Staging]
    B -->|main| E[Build + Deploy Production]
    
    C --> F[Docker Build]
    D --> F
    E --> F
    
    F --> G[Docker Push]
    G --> H{Deploy?}
    H -->|Yes| I[API Auth]
    H -->|No| J[End]
    
    I --> K[Find Stack]
    K --> L{Platform?}
    L -->|Portainer| M[Portainer Deploy]
    L -->|Komodo| N[Komodo Deploy]
    M --> J
    N --> J

Loading

📋 Requirements

• Jenkins 2.190+
• Docker Pipeline Plugin
• Credentials Plugin
• Git Plugin
• Pipeline: Stage View Plugin

🔍 Troubleshooting

Docker authentication errors

docker login failed

Solution: Check the docker-reg-creds credentials

Portainer/Komodo is unavailable

Failed to authenticate with Portainer
Failed to authenticate with Komodo

Solution: Check the URL and credentials for the respective platform

Stack not found

Stack for branch main not found!

Solution: Create a stack in Portainer/Komodo with the appropriate branch name

🤝 Contribution

1. Create a feature branch
2. Make changes
3. Test in the dev environment
4. Create a Merge Request

📝 Changelog

• v1.4.0 - Added Komodo support as an alternative to Portainer
• v1.2.0 - Added PortainerUtils class with full Portainer API
• v1.1.0 - Added cleanup and isRegistryAvailable utilities to DockerUtils
• v1.0.0 - Initial version with basic functionality