Skip to content

Latest commit

 

History

History
236 lines (154 loc) · 11.6 KB

LAYOUT.md

File metadata and controls

236 lines (154 loc) · 11.6 KB
Raw

Site layout

The update center server at updates.jenkins.io contains the following pieces.

Many of these depend on how the configurable update-center2 is invoked, so this information is based on the presets provided by ./site/publish.sh and ./site/generate.sh.

General update site contents

This section describes the general content of update sites. This is a combination of files required to support the tiered update site system, as well as additional files specific to update sites for secondary purposes.

  • updates/ contains is a copy of/link to tool installer metadata.

Users configuring specific versioned update sites, or still using the stable/ update site will need this directory to ensure tool installer metadata can be downloaded.

For details, see DownloadService.Downloadable. crawler is populating this directory.

The following sections describe the files (sometimes) present in an update site that are generated by this tool.

Update center JSON(ish) files

These files contain update site metadata. These variants exist for historical purposes.

  • update-center.json contains JSONP (with callback wrapper) on the first and last lines. This is the file actually downloaded by Jenkins 2.200+.
  • update-center.json.html contains HTML with JSON wrapped in JS. This used to be downloaded using browser-based metadata download (deprecated in 2015, removed in 2.200)
  • update-center.actual.json (actual JSON for programmatic clients)

Latest releases directory

latest/ is a directory with two files:

  • a virtual directory listing (index.html) linking to the latest releases of core and all plugins in the update site
  • a .htaccess file with redirects making the directory look as if this directory contained those files.

Latest core file

latestCore.txt is a text file with core version offered by the update site. This file is used by jenkins-infra/jenkins.io to determine the latest version offered.

Plugin documentation URLs JSON file

plugin-documentation-urls.json is a JSON file mapping plugin IDs to documentation URLs. This exists to support plugins.jenkins.io, as update-center.* files only link to plugins.jenkins.io.

Plugin versions JSON file

plugin-versions.json only exists in the current/ update site and exists to support the top-level directory file. This file supports programmatic plugin installation scenarios (e.g. Configuration-as-Code, Docker) and only contains the content necessary to support those use cases.

Release history JSON file

release-history.json only exists in the current/ update site and exists to support the top-level directory file. This file powers the file https://jenkins.io/releases.rss which is used by https://twitter.com/jenkins_release

Top-level update site

Jenkins is distributed with the update site https://updates.jenkins.io/update-center.json preconfigured. The top level directory provides that file and several others.

The top level update site will forward requests to the best matching tiered update site, or the current update site based on the version query parameter sent by Jenkins.

The files in this directory are usually copies of/symlinks to current to create clickable links. Actual requests are redirected to tiered sites, or the current site (with no query parameters). This way, at least the file properties shown in the directory listing match the eventually served file after clicking the link.

Tier List

The file tiers.json is generated as part of update-center2 execution and published in the root directory.

It allows programmatically determining which versions of Jenkins get served which update site.

Regular tiered update sites (LTS and weekly)

Directories with names containing Jenkins LTS baselines like 2.204 are version specific update sites.

  • 2.204/ contains the tiered update site for Jenkins 2.204 and similar weekly releases not matching an LTS baseline.
  • stable-2.204/ contains the tiered update site for Jenkins 2.204.x.

Each of these update sites only offer plugins compatible with the respective baseline, as well as the newest weekly or LTS release, depending on the variant (LTS or weekly). This increases the usefulness of the update sites to users of slightly older releases of Jenkins, as they won't regularly be offered incompatible releases of plugins.

The Jenkins project publishes a limited, fixed number of tiered update sites to encourage users to regularly update Jenkins.

2.204/
├── latestCore.txt                   (Unused, may be removed)
├── update-center.actual.json
├── update-center.json
├── update-center.json.html
└── updates  ->  ../updates
stable-2.204/
├── latestCore.txt                   (Unused, may be removed)
├── update-center.actual.json
├── update-center.json
├── update-center.json.html
└── updates  ->  ../updates

Redirect rules will forward requests to the top-level update site files to the most appropriate tiered update site, or current/:

  • Releases older than the oldest supported baseline will be served the oldest update site (LTS or weekly).
  • Weekly releases between two supported LTS baselines will be served the next lower weekly update site. For example, if the newest supported LTS baseline is 2.222, then Jenkins 2.210 will get the 2.204 weekly update site.
  • Weekly releases newer than the most recent LTS baseline will be served the current/ update site.

As a side effect, only the exact weekly matching the most recent LTS baseline will be served that update site, any older version will be downgraded to the previous baseline, any newer version will be updated to current/

Symlinks to the top level updates/ directory exist in all tiered update sites in case of bad configurations, e.g. when administrators manually select a specific update site, unaware of the version redirect.

Current update site

The directory current contains an update site without Jenkins version restrictions, offering the newest releases of Jenkins (weekly) and plugins.

current/
├── latest                           (supports top-level directory, may be moved)
│   ├── .htaccess                    (supports top-level directory, may be moved)
│   └── index.html                   (supports top-level directory, may be moved)
├── latestCore.txt
├── plugin-documentation-urls.json   (supports top-level file, may be moved)
├── plugin-versions.json             (supports top-level file, may be moved)
├── release-history.json             (supports top-level file, may be moved)
├── update-center.actual.json
├── update-center.json
├── update-center.json.html
└── updates  ->  ../updates

Stable update site

stable/
├── latestCore.txt
├── update-center.actual.json
├── update-center.json
├── update-center.json.html
└── updates  ->  ../updates

This is a copy of/symlink to the LTS update site for the most recent LTS baseline. The top-level .htaccess file forwards requests to the latest stable-x.xxx update site.

It exists for compatibility with older LTS controllers that explicitly configure this URL as their update center and is also used by the jenkins-infra/jenkins.io build to determine the current LTS release (latestCore.txt).

Experimental update site

Regular update site filter out version numbers containing alpha and beta. This is an update site that users can use to download those release. Otherwise, this is similar to current/ in that no version caps exist.

experimental/
├── update-center.actual.json
├── update-center.json
├── update-center.json.html
└── updates  ->  ../updates

See also: https://jenkins.io/doc/developer/publishing/releasing-experimental-updates/

Downloads directory

This directory contains a directory tree:

download/
├── plugins/
│   └── (pluginName)/
│       └── index.html
└── war/
    └── index.html

Each index.html file contains a list of links to .war (for core) and .hpi (for plugins) files. Notably, all links apparently go to the same directory and take e.g. the form /download/war/2.2.204.6/jenkins.war. This is handled through the top-level .htaccess file which redirects such download requests to the mirrors site.

Top-level .htaccess file

The top-level .htaccess file is created by generate-htaccess.sh and implements the following redirects:

  • Redirects from top-level update center files to tiered update sites (or current).
  • Redirects from stable/ to the latest LTS update site.
  • Redirects from top-level release history and plugin versions JSON files to the real files in current
  • Redirects for any other .json / .json.html files (i.e. tool downloader metadata in updates/) to the mirrors network.
  • Redirects for .war and .hpi files in the download/ directory tree to the mirrors network.

Known consumers

The following is a list of known references to specific files or directories in the Jenkins project (besides Jenkins itself). It is intended to ensure that Jenkins to update-center2 will not break other parts of project infrastructure.

This list is current as of June 2020, but may not be complete.

jenkins-infra/jenkins.io

jenkins-infra/plugin-site-api

  • /current/plugin-documentation-urls.json in WikiPluginDataParser.java
  • https://updates.jenkins.io/download/plugin/<ID>/ is linked to from every individual plugin's page ("Archives") and mentioned on https://www.jenkins.io/download/verify/

jenkinsci/plugin-installation-manager-tool

jenkinsci/docker