Skip to main content

​
Docker setup

Learn how to build, configure, and deploy Jenkins Job Insight using Docker.

​
Building the image

Clone the repository and build the Docker image: 
# Clone the repository
git clone https://github.com/your-org/jenkins-job-insight.git
cd jenkins-job-insight

# Build the image
docker build -t jenkins-job-insight .
The Dockerfile uses a multi-stage build:
  1. Builder stage: Installs dependencies with uv package manager
  2. Production stage: Copies the virtual environment and installs AI CLI tools (Claude, Gemini, Cursor)
The container runs as a non-root user (appuser) for security and is compatible with OpenShift’s arbitrary UID requirements.

​
Data directory setup

The /data directory is used for SQLite database persistence. You must create this directory on the host before starting the container: 
mkdir -p data
Docker creates mounted directories as root, but the container runs as a non-root user. Creating the directory beforehand ensures proper permissions.

​
Running with Docker

​
Basic usage

Run the container with minimum required configuration: 
docker run -d \
  -p 8000:8000 \
  -v ./data:/data \
  -e JENKINS_URL=https://jenkins.example.com \
  -e JENKINS_USER=your-username \
  -e JENKINS_PASSWORD=your-api-token \
  -e AI_PROVIDER=claude \
  -e AI_MODEL=claude-opus-4 \
  -e ANTHROPIC_API_KEY=your-anthropic-api-key \
  jenkins-job-insight

​
With custom prompt

Mount a custom analysis prompt file to customize AI behavior: 
docker run -d \
  -p 8000:8000 \
  -v ./data:/data \
  -v ./my-prompt.md:/app/PROMPT.md:ro \
  -e JENKINS_URL=https://jenkins.example.com \
  -e JENKINS_USER=your-username \
  -e JENKINS_PASSWORD=your-api-token \
  -e AI_PROVIDER=claude \
  -e AI_MODEL=claude-opus-4 \
  -e ANTHROPIC_API_KEY=your-anthropic-api-key \
  jenkins-job-insight
The custom prompt should include instructions for the AI on how to analyze Jenkins failures and format the JSON response.

​
Environment variables

​
Required variables

VariableDescriptionExample
JENKINS_URLJenkins server URLhttps://jenkins.example.com
JENKINS_USERJenkins usernameyour-username
JENKINS_PASSWORDJenkins password or API tokenyour-api-token
AI_PROVIDERAI provider: claude, gemini, or cursorclaude
AI_MODELModel for the AI providerclaude-opus-4

​
AI provider authentication

ANTHROPIC_API_KEY=your-anthropic-api-key
For Gemini OAuth or Cursor web login, use docker exec <container-name> gemini auth login or docker exec <container-name> agent login after starting the container.

​
Optional variables

VariableDefaultDescription
JENKINS_SSL_VERIFYtrueEnable SSL certificate verification (set to false for self-signed certs)
AI_CLI_TIMEOUT10Timeout for AI CLI calls in minutes
LOG_LEVELINFOLog verbosity: DEBUG, INFO, WARNING, ERROR
TESTS_REPO_URL-Default tests repository URL (can be overridden per-request)
CALLBACK_URL-Default callback URL for results
CALLBACK_HEADERS-Default callback headers as JSON
PROMPT_FILE/app/PROMPT.mdPath to custom analysis prompt file
HTML_REPORTtrueGenerate HTML reports
DEBUGfalseEnable debug mode with hot reload

​
Jira integration (optional)

JIRA_URL=https://your-org.atlassian.net
JIRA_EMAIL=[email protected]
JIRA_API_TOKEN=your-jira-api-token
JIRA_PROJECT_KEY=PROJ  # Optional: scope to specific project
Jira integration searches for existing bugs matching PRODUCT BUG failures. The feature is completely optional and automatically enabled when JIRA_URL and authentication are configured.

​
Docker Compose

For production deployments, use Docker Compose for easier configuration management.

​
Setup

1

Create .env file

Copy the example environment file and configure your values:
cp .env.example .env
Edit .env with your Jenkins and AI provider credentials:
.env
# Jenkins Configuration
JENKINS_URL=https://jenkins.example.com
JENKINS_USER=your-username
JENKINS_PASSWORD=your-api-token

# AI Provider
AI_PROVIDER=claude
AI_MODEL=claude-opus-4
ANTHROPIC_API_KEY=your-anthropic-api-key

# Optional: Jira Integration
JIRA_URL=https://your-org.atlassian.net
JIRA_EMAIL=[email protected]
JIRA_API_TOKEN=your-jira-api-token
2

Review docker-compose.yaml

The provided docker-compose.yaml includes:
docker-compose.yaml
services:
  jenkins-job-insight:
    build:
      context: .
      dockerfile: Dockerfile
    
    container_name: jenkins-job-insight
    
    ports:
      - "8000:8000"
    
    volumes:
      - ./data:/data
      # Optional: mount custom prompt
      # - ./PROMPT.md:/app/PROMPT.md:ro
    
    restart: unless-stopped
    
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s
    
    env_file:
      - .env
3

Start the service

# Create data directory
mkdir -p data

# Start in background
docker compose up -d

# View logs
docker compose logs -f

# Stop the service
docker compose down

​
Custom prompt with Docker Compose

To use a custom analysis prompt:
  1. Create your prompt file (e.g., PROMPT.md)
  2. Uncomment the volume mount in docker-compose.yaml:
volumes:
  - ./data:/data
  - ./PROMPT.md:/app/PROMPT.md:ro  # Uncomment this line
  1. Restart the service:
docker compose down
docker compose up -d

​
Vertex AI authentication

For Claude with Vertex AI, mount your gcloud credentials:
docker-compose.yaml
volumes:
  - ./data:/data
  - ~/.config/gcloud:/home/appuser/.config/gcloud:ro
Set the environment variables:
.env
AI_PROVIDER=claude
CLAUDE_CODE_USE_VERTEX=1
CLOUD_ML_REGION=us-east5
ANTHROPIC_VERTEX_PROJECT_ID=your-project-id

​
SSL certificate verification

For Jenkins servers with self-signed SSL certificates, disable certificate verification: 
-e JENKINS_SSL_VERIFY=false
In production, use properly signed certificates and keep JENKINS_SSL_VERIFY=true (the default).
Same option is available for Jira: 
-e JIRA_SSL_VERIFY=false

​
Health checks

The Docker image includes a health check endpoint at /health: 
curl http://localhost:8000/health
Docker Compose automatically configures health checks:
  • Interval: 30 seconds
  • Timeout: 10 seconds
  • Retries: 3
  • Start period: 10 seconds

​
Container management

​
View logs

# Docker run
docker logs -f <container-id>

# Docker Compose
docker compose logs -f

​
Execute commands inside container

# Docker run
docker exec -it <container-id> bash

# Docker Compose
docker compose exec jenkins-job-insight bash

​
Authenticate AI CLI tools

# Gemini OAuth
docker exec <container-name> gemini auth login

# Cursor web login
docker exec <container-name> agent login

​
Restart container

# Docker run
docker restart <container-id>

# Docker Compose
docker compose restart

​
Troubleshooting

​
Permission denied on /data

Create the data directory before starting the container: 
mkdir -p data

​
AI CLI not found

Ensure the CLI tools are in the PATH. Check the Dockerfile installation: 
# Claude CLI
RUN /bin/bash -o pipefail -c "curl -fsSL https://claude.ai/install.sh | bash"

# Cursor Agent CLI
RUN /bin/bash -o pipefail -c "curl -fsSL https://cursor.com/install | bash"

# Gemini CLI
RUN npm install -g @google/gemini-cli

​
SSL certificate errors

Disable SSL verification for Jenkins or Jira: 
-e JENKINS_SSL_VERIFY=false
-e JIRA_SSL_VERIFY=false

​
Next steps

Environment variables

Complete reference for all configuration options

API reference

Explore all available endpoints

Custom prompts

Customize AI analysis behavior

Jira integration

Set up Jira bug search

Build docs developers (and LLMs) love

Get started for freeTalk to us