When you self-host Jenkins on a managed VPS, you build, test and deploy your projects from a machine of your own, which our teams keep up to date and monitor day and night. Jenkins is free software under the MIT license. This guide follows its official documentation: choosing the LTS release, installing with Docker Compose or the Linux packages, HTTPS and the Jenkins URL, agents, permissions, plugins, backups and upgrades.
By Simon Vasconcelos Lee
Published on 16 November 202615-minute read
jenkins/jenkins image and its lts tags, or with the project’s Linux packages, behind an HTTPS reverse proxy; then set that address as the Jenkins URL.JENKINS_HOME, keep secrets/master.key separately, and read the upgrade guide of each LTS before you apply it.Jenkins describes itself as the leading open source automation server. Built with Java, it offers over 2,000 plugins to automate virtually anything. Its README lists its most common uses: building projects, running tests to catch bugs as soon as they are introduced, static code analysis and deployment.
Jenkinsfile, which the documentation recommends committing to the project’s source control.Jenkins is released under the MIT license. It allows you to use, copy, modify, merge, publish, distribute, sublicense and sell the software, on one condition: keep the copyright notice and the license text in every copy. You can therefore run Jenkins in your company, for your own projects and for your clients’, with no license to buy.
The license covers the code. The name "Jenkins" is a registered trademark of LF Charities, Inc., an organization associated with the Linux Foundation, and the project follows the Linux Foundation trademark policy. That policy applies to anyone who puts the word in the name of their own product or service, and it suggests forms such as "your product for Jenkins" for that purpose: read it if you are building an offer around the software. Naming Jenkins to describe it, as this guide does, is fair use.
This publication is independent of the Jenkins project, LF Charities, Inc. and the Linux Foundation, and is not affiliated with, sponsored or approved by them.
Jenkins ships on two lines. The weekly release delivers new features and fixes every week. The LTS line, for Long-Term Support, starts from a weekly release selected every 12 weeks as its baseline, then receives backported fixes. The documentation presents the LTS tags of the Docker image as the more stable, production-ready release: that is the one this guide installs.
| Line | As of 8 November 2026 | Pace |
|---|---|---|
| LTS | 2.580.2 of 28 October 2026, after 2.580.1 of 30 September | Three releases per baseline, .1, .2 and .3, each after two weeks of backporting and two weeks of testing |
| Weekly | 2.589 | One release a week |
LTS 2.580.2 requires Java 21 or Java 25: with any other version, the controller will not run. The project plans to end support for Java 21 in September 2027, and for Java 25 in September 2029. The requirement applies to the whole system, controller, agents and command line; your projects themselves build with whichever Java version suits them.
The documentation recommends the official jenkins/jenkins image. The lts tag follows the LTS on Java 21, lts-jdk25 the same LTS on Java 25, and latest the weekly release. On a server with Docker installed, create a folder and put this compose.yaml in it, taken from the documentation’s Caddy example: Caddy receives visitors on ports 80 and 443, obtains the HTTPS certificate and forwards to Jenkins, which is reachable on the internal network only.
services:
jenkins:
image: jenkins/jenkins:lts-jdk25
container_name: jenkins
restart: unless-stopped
volumes:
- jenkins_home:/var/jenkins_home
expose:
- "8080"
networks:
- web
caddy:
image: caddy:2
container_name: caddy
restart: unless-stopped
depends_on:
- jenkins
ports:
- "80:80"
- "443:443"
volumes:
- ./Caddyfile:/etc/caddy/Caddyfile:ro
- caddy_data:/data
- caddy_config:/config
networks:
- web
networks:
web:
driver: bridge
volumes:
jenkins_home:
caddy_data:
caddy_config:
jenkins.example.com {
encode zstd gzip
reverse_proxy jenkins:8080
}
docker compose up -d
/var/jenkins_home: all data lives there, plugins and configuration included. The image’s README prefers this volume to a folder on the host, which can lead to permission issues: the jenkins user in the container has ID 1000.web network. Port 50000 is used by inbound TCP agents; WebSocket and SSH agents do without it, so it is not published here.2.580.2-lts-jdk25 fixes the version, whereas lts-jdk25 follows the current LTS.The documentation sets a minimum of 256 MB of memory and 1 GB of disk, at least 10 GB in a Docker container, and recommends 4 GB of memory or more and 50 GB of disk or more for a small team. It explains that controller memory ranges from 200 MB for a small installation to over 70 GB for the largest; each connected agent takes 2 or 3 threads there, about 2 MB or more. The bulk of the work, the builds, runs on the agents.
On a managed VPS, tell us about your projects and how often you build: we recommend the right size for the controller and for the agents.
The project also publishes packages for Debian and Ubuntu, Fedora, Red Hat Enterprise Linux and its derivatives. On Debian or Ubuntu, install Java first: the documentation strongly recommends it, since Jenkins installed before Java may fail to find a valid Java installation at startup.
sudo apt update
sudo apt install fontconfig openjdk-21-jre
java -version
Then add the LTS repository, debian-stable, with its signing key, and install Jenkins:
sudo wget -O /etc/apt/keyrings/jenkins-keyring.asc \
https://pkg.jenkins.io/debian-stable/jenkins.io-2026.key
echo "deb [signed-by=/etc/apt/keyrings/jenkins-keyring.asc]" \
https://pkg.jenkins.io/debian-stable binary/ | sudo tee \
/etc/apt/sources.list.d/jenkins.list > /dev/null
sudo apt update
sudo apt install jenkins
The package creates a systemd service and a jenkins user, sends its log to journald (journalctl -u jenkins.service), keeps its data in /var/lib/jenkins and listens on port 8080, on all interfaces. Behind a proxy on the same server, restrict it to the local address with sudo systemctl edit jenkins, then sudo systemctl restart jenkins:
[Service]
Environment="JENKINS_LISTEN_ADDRESS=127.0.0.1"
This block follows the documentation’s Nginx example, reduced to its location / block, the form it provides for when Nginx does not read Jenkins’s files itself:
upstream jenkins {
keepalive 32;
server 127.0.0.1:8080;
}
map $http_upgrade $connection_upgrade {
default upgrade;
'' '';
}
server {
listen 80;
server_name jenkins.example.com;
ignore_invalid_headers off;
location / {
sendfile off;
proxy_pass http://jenkins;
proxy_redirect default;
proxy_http_version 1.1;
proxy_set_header Connection $connection_upgrade;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Host $http_host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_max_temp_file_size 0;
client_max_body_size 10m;
client_body_buffer_size 128k;
proxy_connect_timeout 90;
proxy_send_timeout 90;
proxy_read_timeout 90;
proxy_request_buffering off;
}
}
proxy_pass without a trailing slash: the documentation warns that ending this value with a slash causes problems.Upgrade and Connection headers serve WebSocket agents, and the map keeps connections alive for the rest of the traffic.proxy_request_buffering off is required for Jenkins command line commands sent over HTTP.client_max_body_size sets the maximum upload size, 10 MB in the example.Certbot then installs the certificate and takes care of renewing it:
sudo certbot --nginx
Once Jenkins is online, set its public address, for example https://jenkins.example.com/, under Manage Jenkins, System, in the Jenkins Location section. Jenkins uses it for every address it generates, in the UI as in agent files, and for communicating with agents and external tools. Port options make no difference to it: this URL is what counts.
Jenkins monitors its own reverse proxy. If it shows "It appears that your reverse proxy setup is broken", first check that this URL matches the address you use, then that the proxy sends X-Forwarded-Proto when it receives HTTPS and talks to Jenkins over HTTP, as both examples in this guide do.
Served under a path such as /jenkins rather than its own domain name, Jenkins must know that path: --prefix=/jenkins, through JENKINS_OPTS with Docker or JENKINS_PREFIX with the packages. The documentation recommends the same path on both sides, since rewriting it in the proxy means fixing a great many addresses.
On first access, Jenkins asks for an automatically generated password, which it writes to its log and to secrets/initialAdminPassword. Open your HTTPS address, then read it:
docker exec jenkins cat /var/jenkins_home/secrets/initialAdminPassword
sudo cat /var/lib/jenkins/secrets/initialAdminPassword
admin account keeps the unlock password as its password.The wizard leaves the "Logged-in users can do anything" authorization strategy in place: every logged-in account has full rights. It suits you as long as only fully trusted people have an account. Before opening more accounts, switch to matrix-based security, described below.
A build runs commands that people other than the administrator control: build scripts, tests, the code of every commit. On the built-in node, those commands have the same access to the controller’s file system as Jenkins itself. The documentation therefore recommends running no builds on the built-in node and handing them to agents, which also keeps the controller’s CPU and memory for its own job.
| Connection | How | Network side |
|---|---|---|
| SSH | The controller connects to the agent, with the SSH Build Agents plugin | No port to open on the controller |
| WebSocket | The agent connects to the controller through its HTTPS address, since Jenkins 2.217 | No extra port: the proxy forwards WebSocket |
| Inbound TCP | The agent connects to the controller on a dedicated TCP port | A fixed port to open and publish, 50000 in the Docker image |
The documentation advises generic, interchangeable agents, prepared with a configuration management tool, a pre-baked image or a container: an agent that goes down is then replaced with no effort. With a single server, it suggests an agent running as another operating system user, with no read or write access to JENKINS_HOME and no sudo. On a managed VPS, a second VPS can also act as an agent, sized for your builds.
Agent to controller access control, which stops a compromised agent from sending commands to the controller, is always enabled since Jenkins 2.326.
Jenkins separates authentication, which establishes who you are, from authorization, which says what you may do. Its built-in user database, enabled by default, suits small teams; LDAP, Active Directory, SAML or OpenID Connect plug in through plugins. For authorization, these are the strategies the documentation describes:
| Strategy | What it grants | When to choose it |
|---|---|---|
| Anyone can do anything | Full rights, even to anonymous visitors | For a local test only |
| Logged-in users can do anything | Full rights to every logged-in account; the setting the wizard leaves | As long as only fully trusted people have an account |
| Matrix-based security | Permissions granted per user or per group | The starting point the documentation recommends for production |
| Project-based Matrix Authorization Strategy | The same matrix, extended project by project | To reserve some projects for some people |
Both matrix strategies come from the Matrix Authorization Strategy plugin, which is among the plugins the wizard suggests. In the matrix, grant little to the anonymous and authenticated rows: Overall/Administer granted to authenticated amounts to "Logged-in users can do anything". Take the same care if you open self-signup or an identity provider where anyone can create an account.
JENKINS_HOME with the keys in the secrets folder, which the backups section handles separately.Plugins are what makes Jenkins so versatile, and each one is code running inside the controller. Jenkins checks the Update Center once every 24 hours; updates appear in the Updates tab of Manage Jenkins, Plugins, and take effect after a restart. The Check now button forces a check.
With Docker, you can also build your own image from jenkins/jenkins and install your plugins in it with jenkins-plugin-cli, from a plugins.txt list that pins their versions and that the tool can update. The image’s README describes this method.
Build notifications go through the Mailer plugin: a failed build, a success after a failure or a build that becomes unstable triggers an email. The sending server is set under Manage Jenkins, System, in the E-mail Notification section.
On a Simafri VPS, mail goes out through an authenticated SMTP relay, on port 587: the address of an email account you already have, or Simafri Suite. In the advanced options, tick Use SMTP Authentication with the account’s username and password, then Use TLS: the plugin then uses port 587. The Test configuration by sending test e-mail option sends a test message.
The documentation calls controller backups critically important: they serve for disaster recovery, for recovering a configuration changed by mistake, or a file that was corrupted or deleted. Everything lives in JENKINS_HOME: /var/jenkins_home in the Docker image, /var/lib/jenkins with the packages.
| Item | What it holds | Back it up |
|---|---|---|
*.xml, including config.xml | The main configuration and the system configuration | Required |
jobs/ | Jobs and build history; in builds/archive, archived artifacts | Required; artifacts as needed, they get large |
plugins/*.jpi | Installed plugins, at their versions | Recommended, to restore identically |
secrets/ | The keys that encrypt credentials | The folder, except master.key, kept separately |
workspace/ | Files checked out from source control for builds | Optional: a fresh checkout recreates them |
war/, cache/, tools/ | The exploded WAR, downloaded and extracted tools | Optional: recreated as needed |
The documentation asks you never to put the master key in your regular backup. secrets/master.key encrypts the key that protects your credentials: whoever holds your backups and this key can read everything. Copy it once and store it separately in a very secure place, like an SSH private key; a full restore needs it.
The image’s README asks you to treat jenkins_home like a database. Stop Jenkins for the duration of the copy, then archive the volume with a temporary container, following the method in the Docker documentation:
docker compose stop jenkins
docker run --rm --volumes-from jenkins -v "$(pwd)":/backup ubuntu \
tar -czf /backup/jenkins_home-$(date +%F).tar.gz --exclude=./secrets/master.key -C /var/jenkins_home .
docker compose start jenkins
docker cp jenkins:/var/jenkins_home/secrets/master.key ./master.key
sudo systemctl stop jenkins
sudo tar -czf jenkins_home-$(date +%F).tar.gz --exclude=./secrets/master.key -C /var/lib/jenkins .
sudo systemctl start jenkins
A copy made with the service stopped is consistent. To back up without stopping, the documentation points to file system snapshots, LVM, btrfs or ZFS, which are more consistent and faster than a live copy; among open source backup plugins, it names thinBackup as the only one still maintained. Give each copy a timestamped name, avoid /tmp, which may be cleaned on reboot, and send finished copies to a remote server.
Stored on the server’s disk, these archives are also included in its nightly backups.
The documentation asks you to validate every backup, and gives the simple method: restore it to a temporary folder, put master.key back, and start a second Jenkins of the same version on it, on another port:
export JENKINS_HOME=/mnt/backup-test
java -jar jenkins.war --httpPort=9999
Before each core upgrade, read the page of the target LTS in the project’s upgrade guides: each section covers the upgrade from the previous LTS. For 2.580.2, it lists no notable changes. For 2.580.1, it notes that several plugins detached from the core are no longer bundled in the WAR: Jenkins installs them on its own when the Update Center is reachable. Then back up JENKINS_HOME and upgrade:
docker compose pull
docker compose up -d
sudo apt update
sudo apt install jenkins
Self-hosting means running the server on top of the application. On a managed VPS, our teams take charge of the server and proactively monitor your instance; Jenkins remains your software, with its pipelines, its settings and its data.
| Topic | Our teams | You |
|---|---|---|
| The server | System and security updates, server interventions included | The timing that suits your business |
| Monitoring | Server monitored 24/7, with intervention without waiting for your call | Reading your instance’s and your builds’ logs |
| Jenkins | Proactive monitoring: errors, slowdowns and disk space spotted, fix recommended | Its installation, updates, plugins and settings, which you apply, yourself or through your AI assistant |
| Pipelines and agents | The servers that carry them, monitored and backed up | Jobs, agents, accounts, permissions and credentials |
| Backups | Every night, encrypted and kept off the machine; restores included | Jenkins’s own archives, the master.key file, and the restore request, when you need one |
| Migration | Your current server migrated, free of charge | The timing of the switch |
If you would rather have our teams work inside the application itself, that service is billed by the hour or at a fixed rate, with an estimate shared before the work starts.
With a Simafri Managed VPS, our teams keep your Jenkins instance’s server up to date, monitor it day and night and step in without waiting for your call; they also proactively monitor your instance and recommend useful fixes, which you apply, yourself or through your AI assistant. Backups are encrypted every night and kept off the machine, restores are included, and migrating your current server is complimentary.
Yes. Jenkins is under the MIT license: you can use, modify and run it in your company with no license to buy, as long as you keep its copyright and license notice. What remains is the cost of the servers that carry the controller and the agents.
The LTS line, which the documentation presents as production-ready: 2.580.2 as of 28 October 2026. It requires Java 21 or Java 25. A new LTS baseline is selected every 12 weeks, and each baseline receives three fix releases.
Use the official jenkins/jenkins image with an LTS tag, such as lts-jdk25, and a named volume mounted on /var/jenkins_home. Put an HTTPS reverse proxy in front, for example Caddy in the same compose.yaml file, then set the public address as the Jenkins URL.
In the startup log, and in the secrets/initialAdminPassword file of JENKINS_HOME: /var/jenkins_home with the Docker image, /var/lib/jenkins with the packages. Paste it on the Unlock Jenkins page, then create your own administrator account.
The documentation recommends running them on agents: on the built-in node, a build has the same access to the controller’s files as Jenkins. Connect an agent, over SSH or WebSocket, then set the built-in node’s executors to 0.
Serve it over HTTPS behind a reverse proxy, switch to matrix-based security, reserve Overall/Administer for trusted people, keep CSRF protection on, run builds on agents and promptly apply the LTS releases that carry security fixes.
Archive JENKINS_HOME, with the service stopped or through a file system snapshot. Keep secrets/master.key out of that backup, stored separately in a very secure place, and validate each backup by restoring it on a test Jenkins started on another port.
A managed VPS covers the server: system, security, monitoring and backups. Our teams also proactively monitor your instance and recommend useful fixes, which you apply. Work inside the application is billed by the hour or at a fixed rate.
Simafri
Let's talk about your website
Tell us about your project in a few words: we will get back to you quickly.
Thank you! Your request has been sent. We'll get back to you shortly.
Prefer email? Write to us at support@simafri.com.