Self-host Jenkins® on a managed VPS: your builds on your own server

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.

Simon Vasconcelos Lee By Published on 16 November 202615 minute read

All guides

In short

  1. The MIT license lets you use Jenkins freely in your company, as long as you keep its license notice. The name falls separately under the trademark policy the project has adopted, that of the Linux Foundation.
  2. Choose the LTS line: 2.580.2 as of 28 October 2026, which runs on Java 21 or Java 25. A new LTS baseline is selected every 12 weeks.
  3. Install it with the official 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.
  4. Run builds on agents and set the controller’s executors to 0. Grant permissions with matrix-based security and keep CSRF protection on.
  5. Back up JENKINS_HOME, keep secrets/master.key separately, and read the upgrade guide of each LTS before you apply it.

What Jenkins does

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.

The MIT license and the trademark

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.

LTS or weekly: which release to install

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.

LineAs of 8 November 2026Pace
LTS2.580.2 of 28 October 2026, after 2.580.1 of 30 SeptemberThree releases per baseline, .1, .2 and .3, each after two weeks of backporting and two weeks of testing
Weekly2.589One 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.

Installing with Docker Compose

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.

compose.yaml
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:
Caddyfile
jenkins.example.com {
  encode zstd gzip
  reverse_proxy jenkins:8080
}
Terminal
docker compose up -d

Sizing the server

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.

With the Debian or Ubuntu packages

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.

Terminal
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:

Terminal
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 override
[Service]
Environment="JENKINS_LISTEN_ADDRESS=127.0.0.1"

With Nginx and Certbot

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:

Nginx block
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;
  }
}

Certbot then installs the certificate and takes care of renewing it:

Terminal
sudo certbot --nginx

The Jenkins URL and the reverse proxy

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.

First start: the initial password and the setup wizard

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:

Terminal, with Docker Compose
docker exec jenkins cat /var/jenkins_home/secrets/initialAdminPassword
Terminal, with the packages
sudo cat /var/lib/jenkins/secrets/initialAdminPassword
  1. Paste this password on the Unlock Jenkins page.
  2. Choose Install suggested plugins, the set the documentation advises when you are not yet sure which plugins you need; others are added later under Manage Jenkins, Plugins.
  3. Create the first administrator, with a strong password. If you skip this step, the admin account keeps the unlock password as its password.
  4. Set the Jenkins URL, as in the previous section.

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.

Builds on agents, the controller to orchestrate

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.

  1. Connect at least one agent: another machine, a container or a cloud. The agent needs Java and a network connection to the controller.
  2. Under Manage Jenkins, Nodes, open Built-In Node, then Configure, and set the number of executors to 0. Do this once an agent is in place, since builds then wait for an agent to start. The Docker image sets 2 by default.
ConnectionHowNetwork side
SSHThe controller connects to the agent, with the SSH Build Agents pluginNo port to open on the controller
WebSocketThe agent connects to the controller through its HTTPS address, since Jenkins 2.217No extra port: the proxy forwards WebSocket
Inbound TCPThe agent connects to the controller on a dedicated TCP portA 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.

Accounts and permissions

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:

StrategyWhat it grantsWhen to choose it
Anyone can do anythingFull rights, even to anonymous visitorsFor a local test only
Logged-in users can do anythingFull rights to every logged-in account; the setting the wizard leavesAs long as only fully trusted people have an account
Matrix-based securityPermissions granted per user or per groupThe starting point the documentation recommends for production
Project-based Matrix Authorization StrategyThe same matrix, extended project by projectTo 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.

Plugins and their updates

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.

Email notifications

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.

Backing up JENKINS_HOME

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.

ItemWhat it holdsBack it up
*.xml, including config.xmlThe main configuration and the system configurationRequired
jobs/Jobs and build history; in builds/archive, archived artifactsRequired; artifacts as needed, they get large
plugins/*.jpiInstalled plugins, at their versionsRecommended, to restore identically
secrets/The keys that encrypt credentialsThe folder, except master.key, kept separately
workspace/Files checked out from source control for buildsOptional: a fresh checkout recreates them
war/, cache/, tools/The exploded WAR, downloaded and extracted toolsOptional: 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.

With Docker Compose

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:

Terminal, in the compose.yaml folder
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
Terminal, once: the master key
docker cp jenkins:/var/jenkins_home/secrets/master.key ./master.key

With the packages

Terminal
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.

Validating a backup

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:

Terminal
export JENKINS_HOME=/mnt/backup-test
java -jar jenkins.war --httpPort=9999

Upgrades

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:

Terminal, with Docker Compose
docker compose pull
docker compose up -d
Terminal, with the packages
sudo apt update
sudo apt install jenkins

Who does what on a managed VPS

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.

TopicOur teamsYou
The serverSystem and security updates, server interventions includedThe timing that suits your business
MonitoringServer monitored 24/7, with intervention without waiting for your callReading your instance’s and your builds’ logs
JenkinsProactive monitoring: errors, slowdowns and disk space spotted, fix recommendedIts installation, updates, plugins and settings, which you apply, yourself or through your AI assistant
Pipelines and agentsThe servers that carry them, monitored and backed upJobs, agents, accounts, permissions and credentials
BackupsEvery night, encrypted and kept off the machine; restores includedJenkins’s own archives, the master.key file, and the restore request, when you need one
MigrationYour current server migrated, free of chargeThe 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.

Jenkins, on a server run for you

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 free.

Explore Managed VPS

Frequently asked questions

Is Jenkins free for a business?

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.

Which Jenkins version should I install?

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.

How do I install Jenkins with Docker?

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.

Where do I find the Jenkins initial admin password?

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.

Should builds run on the Jenkins controller?

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.

How do I secure a Jenkins instance?

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.

How do I back up Jenkins?

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.

Does a managed VPS cover Jenkins?

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.

Contact us