Skip to content
Klutch.sh Docs

Deploying a Jenkins App

Introduction

Jenkins is an open-source automation server for CI/CD pipelines. Deploying Jenkins with a Dockerfile on Klutch.sh gives you reproducible builds, managed secrets, and persistent storage for jobs and plugins—all managed from klutch.sh/app. This guide covers installation, repository prep, a production-ready Dockerfile, deployment steps, Nixpacks overrides, and best practices for secure automation.

Prerequisites

  • A Klutch.sh account (create one)
  • A GitHub repository containing your Jenkins configuration (GitHub is the only supported git source)
  • Docker familiarity and basic Jenkins admin knowledge
  • Storage for JENKINS_HOME (jobs, plugins, secrets)

For platform onboarding, see the Quick Start.

Architecture and ports

  • Jenkins serves HTTP on port 8080 by default. Set the internal container port to 8080 in Klutch.sh.
  • If you expose inbound agents via TCP (JNLP), consider a separate Klutch.sh TCP app with port 8000 externally and 50000 internally (optional).
  • Persistent storage is required for /var/jenkins_home.

Repository layout

jenkins/
├── Dockerfile              # Must be at repo root for auto-detection
├── casc/                   # Optional JCasC config
├── plugins.txt             # Plugin list (if using install-plugins.sh)
├── README.md
└── .env.example            # Template only; no secrets

Keep secrets out of Git; store them in Klutch.sh environment variables.

Installation (local) and starter commands

Quick local test run:

Terminal window
docker run --rm -p 8080:8080 -p 50000:50000 \
  -v $(pwd)/jenkins_home:/var/jenkins_home \
  jenkins/jenkins:lts-jdk17

Optional helper start.sh for portability and Nixpacks fallback:

#!/usr/bin/env bash
set -euo pipefail
exec /usr/bin/tini -- /usr/local/bin/jenkins.sh

Make it executable with chmod +x start.sh.

Dockerfile for Jenkins (production-ready)

Place this Dockerfile at the repo root; Klutch.sh auto-detects it (no Docker selection in the UI):

FROM jenkins/jenkins:lts-jdk17


USER root
# Install any extra tools you need (e.g., git, docker-cli if building inside Jenkins)
RUN apt-get update && apt-get install -y git curl && rm -rf /var/lib/apt/lists/*
USER jenkins


# Optional: preload plugins
COPY plugins.txt /usr/share/jenkins/ref/plugins.txt
RUN install-plugins.sh < /usr/share/jenkins/ref/plugins.txt || true


EXPOSE 8080
CMD ["/usr/bin/tini", "--", "/usr/local/bin/jenkins.sh"]

Notes:

  • Pin the Jenkins image tag for reproducible builds.
  • If you need Docker-in-Docker or buildx, ensure the host runtime supports it and install tooling carefully.

Environment variables (Klutch.sh)

Set these in the Klutch.sh app settings (Secrets tab) before deploying:

  • JENKINS_OPTS=--prefix=/ (adjust if you want a sub-path)
  • JAVA_OPTS=-Djenkins.install.runSetupWizard=false (if pre-configured)
  • PORT=8080
  • CASC_JENKINS_CONFIG=/var/jenkins_home/casc/jenkins.yaml (if using JCasC)

If you deploy without the Dockerfile and need Nixpacks overrides:

  • NIXPACKS_BUILD_CMD="echo Jenkins packaged image" (usually not needed)
  • NIXPACKS_START_CMD="/usr/bin/tini -- /usr/local/bin/jenkins.sh"
  • NIXPACKS_JDK_VERSION=17

These keep Jenkins compatible with Nixpacks defaults when a Dockerfile is absent.

Attach persistent volumes

In Klutch.sh storage settings, add mount paths and sizes (no names required):

  • /var/jenkins_home — required for jobs, plugins, secrets, and build history.
  • /var/jenkins_home/casc — optional if you store JCasC configs.

Ensure these paths are writable by the jenkins user inside the container.

Deploy Jenkins on Klutch.sh (Dockerfile workflow)

  1. Push your repository (with the Dockerfile at the root) to GitHub.
  2. Open klutch.sh/app, create a project, and add an app.
  1. Connect the GitHub repository; Klutch.sh automatically detects the Dockerfile.
  2. Choose HTTP traffic for Jenkins.
  3. Set the internal port to 8080.
  4. Add the environment variables above (Jenkins opts, Java opts, and any NIXPACKS_* overrides if you temporarily deploy without the Dockerfile).
  5. Attach persistent volumes for /var/jenkins_home (and /var/jenkins_home/casc if used), selecting sizes that fit your job history and artifacts.
  6. Deploy. Your Jenkins server will be reachable at https://example-app.klutch.sh; attach a custom domain if desired.

If you expose inbound agents over TCP, create a separate Klutch.sh TCP app with internal port 50000 and connect agents to example-app.klutch.sh:8000.

Health checks and production tips

  • Add a /login or /whoAmI probe via your reverse proxy for uptime monitoring.
  • Enforce HTTPS at the edge; forward HTTP to port 8080 internally.
  • Keep the Jenkins image pinned; update plugins in controlled batches.
  • Monitor disk usage on /var/jenkins_home and resize before it fills.
  • Back up jenkins_home regularly; it contains jobs, credentials, and build history.

Jenkins on Klutch.sh combines reproducible Docker builds with managed secrets, persistent volumes for jobs and plugins, and flexible HTTP/TCP routing. With the Dockerfile at the repo root and ports set to 8080 for the app (8000 externally for TCP agents if used), you can run a stable CI/CD hub without extra YAML or workflow overhead.