Skip to content

Jenkins Installation and Configuration

Overview

Purpose

Jenkins is used in our infrastructure as the primary automation server for Continuous Integration and Continuous Deployment (CI/CD) pipelines.

Scope

Installation of the Jenkins automation server.

Audience

CORE, DEV

Prerequisites

VM Hardware Requirements

Component Requirement
CPU 8 cores
RAM 16 GB
Disk Space OS & Jenkins installation: 1,4 TB

Software Requirements

Component Version
Operating System Debian 12
Docker Engine 28.1.1

Access Requirements

  • User: qcuser for all installation steps.
  • Network access to internal DNS and SSL certificate authority.
  • Credentials: The current name of credentials is called qcrepository.
  • Official installation guide: https://www.jenkins.io/doc/book/installing/docker/
  • Guide to handling the docker image: https://hub.docker.com/_/jenkins

Architecture Diagram

We use a multi-container architecture via Docker Compose to ensure isolation and scalability.

Why Docker-in-Docker (DinD)? We use a separate docker service (Docker-in-Docker) to allow Jenkins to execute Docker commands (like docker build or docker run) without needing access to the host's Docker socket. This provides better isolation and security. The Jenkins container communicates with this service via the DOCKER_HOST environment variable (tcp://docker:2375).

Why the Database? The PostgreSQL database (postgres_svr) is required for the Pipeline Maven Integration plugin. It stores metadata about Maven builds, which allows Jenkins to link upstream and downstream projects effectively, tracking dependencies across different pipelines.

Configuration Details

Parameters & Endpoints

  • Hostname: e.g. jenkins.quintessence.de.
  • Jenkins Port: 8081 (mapped from 8080).
  • Docker Host: tcp://docker:2375.
  • Database: jenkins_db on port 5432.

Examples

services:
  jenkins:
    image: jenkins/jenkins-lts-docker:35
    container_name: jenkins
    environment:
      - DOCKER_HOST=tcp://docker:2375
    depends_on:
      - docker

  postgres_svr:
    image: postgres:15
    container_name: postgres
    environment:
      POSTGRES_DB: jenkins_db
      POSTGRES_USER: jenkins
      POSTGRES_PASSWORD: p@ssw0rd

  docker:
    image: docker:28.0.1-dind-rootless
    container_name: docker
    privileged: true

Step-by-Step Setup

Build the Custom Jenkins Image

The Jenkins image must be built using the provided Dockerfile to include the necessary Docker CLI tools and permissions.

docker build -t jenkins/jenkins-lts-docker:latest ./jenkins

Prepare Mount Points

Create the necessary directories for persistence:

mkdir -p /home/qcuser/apps/jenkins/jenkins-home2
mkdir -p /home/qcuser/apps/tools/postgres/postgres-data

Install Jenkins

  1. Adjust docker-compose.yml.
  2. Start and verify containers: docker-compose up -d.

Configure Jenkins as Code (JCasC) via GUI

To manage Jenkins configuration via code using the GUI:

  1. Install Plugin:
    • Navigate to Manage Jenkins > Plugins > Available plugins.
    • Search for and install Configuration as Code.
  2. Import Configuration:
    • Download the configuration file from the repository: https://gitlab.quintessence.net/net.quintessence/ci-cd.
    • Navigate to Manage Jenkins > Configuration as Code.
    • Use the Replace existing configuration section to upload the downloaded configuration file and apply it.

Validation & Testing

Open in your browser and access the GUI via the configured port (e.g., http://localhost:8081).

Troubleshooting

  • Check Docker status: docker ps -a.
  • Review logs: docker logs jenkins.
  • Fix permissions on volume mounts.
  • Check disk space.

Security Considerations

  • Change initial admin password.
  • Configure security realms.
  • Configure SMTP for notifications.
  • Set up backups for /var/jenkins_home.

Maintenance

Responsibility

Updates are managed by the Core Team.

Compatibility Considerations

Check compatibility with build tools, CI servers, scripts, and external services.

  • https://www.jenkins.io/doc/
  • Current instance: https://qcjen-qcint.quintessence.de
  • Docker image repo: https://hub.docker.com/r/jenkins/jenkins
  • Repository: https://gitlab.quintessence.net/net.quintessence/ci-cd

Changelog

Date Author Message
2026-02-25 aresnikowa Merge remote-tracking branch 'origin/master'