Jenkins Docker Deploy Example

Example repository demonstrating a Jenkins pipeline that:

1. Builds a Docker image
2. Pushes the image to a container registry (Docker Hub, etc.)
3. SSHs to a deployment machine
4. Clones (or pulls) this repo to get docker-compose.yml
5. Deploys with docker compose up -d

Repository Structure

.
├── Jenkinsfile          # Pipeline definition
├── Dockerfile           # Application image
├── docker-compose.yml   # Deployment compose (pulled by deploy host)
├── app.py               # Minimal Python web app
└── README.md

Prerequisites

Jenkins

• Docker installed and Jenkins user in docker group
• Pipeline and SSH Agent plugins
• Git for cloning

Jenkins Credentials

Create these in Manage Jenkins → Credentials:

ID	Type	Purpose
docker-registry-credentials	Username/Password	Docker Hub or registry login
deploy-ssh-key	SSH Username with private key	SSH to deploy host

Deploy Host

• Docker and Docker Compose installed
• SSH access for the deploy user
• If using a private registry: run docker login on the deploy host (or add to the pipeline)

Configuration

Edit the environment block in Jenkinsfile:

environment {
    DOCKER_REGISTRY = 'docker.io'           // or your registry (ghcr.io, etc.)
    DOCKER_IMAGE = 'myorg/myapp'            // e.g., username/repo
    DEPLOY_HOST = 'deploy-server.example.com'
    DEPLOY_USER = 'deploy'
    DEPLOY_PATH = '/opt/myapp'              // Where to clone & run compose
    GIT_REPO_URL = 'https://github.com/myorg/jenkins-docker-deploy-example.git'
}

Pipeline Stages

1. Build – docker build with tag from branch (e.g. latest for main, 123-abc1234 for others)
2. Push – docker push to registry using stored credentials
3. Deploy – SSH to host, clone/pull repo, run docker compose up -d

First-Time Deploy Host Setup

On the deploy host:

# Create deploy directory
sudo mkdir -p /opt/myapp
sudo chown deploy:deploy /opt/myapp

# Ensure deploy user can run docker (add to docker group)
sudo usermod -aG docker deploy

Manual Test

# Build and run locally
docker build -t myapp:test .
docker run -p 8080:8080 myapp:test
# Visit http://localhost:8080

Branch Behavior

• main → image tag latest
• other branches → image tag {BUILD_NUMBER}-{GIT_SHA}