Configuration

This section covers essential settings for Jenkins master, agents, registries, credentials, and storage used by Friendly Jenkins.

Core Files

  • jenkins-master/.env — main configuration for Jenkins container and integrations.

  • jenkins-master/docker-compose.yml — master runtime; adjust ports/networks for production.

  • jenkins-master/casc.yaml — Jenkins Configuration as Code (JCasC) for folders, jobs, credentials, libraries.

  • shared-library/resources/templates/<service>/ — per-service Docker Compose templates, defaults, and configs.

Environment File (jenkins-master/.env)

Recommended keys:

# Jenkins admin + endpoints
JENKINS_ADMIN_USER=admin
JENKINS_ADMIN_PASS=ChangeMe!SecurePassword123
JENKINS_URL=https://jenkins.example.com
JENKINS_PORT=8080
JENKINS_AGENT_PORT=50000

# Registries (Harbor example)
HARBOR_USER=robot$jenkins-qa
HARBOR_PASS=robot-token

# Git for shared library sync
GIT_USER=git-username
GIT_PASS=git-token

# Optional SMTP
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=jenkins@example.com
SMTP_PASS=app-password

# Optional webhook secret for GitLab
WEBHOOK_SECRET_EXPECTED=SHLIB_WEBHOOK_SECRET

Security tips

  • Do not commit .env files.

  • Use strong admin credentials and secrets.

  • Prefer HTTPS behind a reverse proxy for production.

Docker Compose (Master)

  • Development: network_mode: host (default) keeps ports simple.

  • Production: disable host mode; expose explicit ports and attach to a dedicated network:

    • ports: ["${JENKINS_PORT}:8080", "${JENKINS_AGENT_PORT}:50000"]

    • networks: [jenkins_network]

  • Mount volumes persistently for /var/jenkins_home/ and backup paths.

Jenkins Configuration as Code (JCasC)

Key items to tune in casc.yaml:

  • Executors: set numExecutors to enable master to run jobs (0 by default for controller-only).

  • Global Library: ensure qa-shared points to your Git URL and credentials ID.

  • Credentials: Git, registry, SMTP, and webhook tokens.

  • Folders/Jobs: seed jobs provisioned via Job DSL will create the QA folders on first boot.

Storage Layout

On master (/var/jenkins_home/qa-data/):

  • envs/<env-name>/ — rendered compose files, .env, per-service env files, metadata, backups.

  • shared-lib/ — optional synced copy of the shared library.

On agents (/opt/qa-envs/<env-name>/):

  • docker-compose.yml, .env, <service>.env, service config dirs, and docker-compose.yml.backup-*.

Agents

  • Labels (e.g., qa-agent, qa-perf) control targeting; auto-detection reads meta.json when deploying.

  • Ensure agents can reach registries and master; JNLP inbound on port 50000.

  • Each agent should have Docker, Compose, and git installed.

Registries

  • Harbor, Docker Hub, or private registries are supported.

  • Provide credentials through Jenkins credentials or .env variables consumed by pipelines.

  • Push/pull performed in pipelines running on agents; validate access with docker login on each agent.

Webhook Integration (GitLab)

  • Configure Generic Webhook Trigger in Jenkins.

  • Webhook URL example: http(s)://<jenkins>/generic-webhook-trigger/invoke?token=SYNC-SHARED-LIB

  • Header: X-Gitlab-Token should match WEBHOOK_SECRET_EXPECTED.

  • Regex for branches/tags can be restricted (e.g., ^(refs/heads/main|refs/tags/v\\d+\\.\\d+\\.\\d+)).