Website for Apache Solr

This repository contains the "source code" of the Solr website at solr.apache.org.

Building the site

The site is written in Markdown syntax and built into a static site using Pelican.

On each Pull Request we do a simple pelican build. The staging site is re-built automatically by Github Actions on every push to main branch, and the result can be previewed at solr.staged.apache.org. Build success/failure emails are sent to commits@solr.apache.org mailing list.

If the staged site looks good, simply merge the changes to branch production and the site will be deployed in a minute or two. Note that simple edits can also be done directly in the GitHub UI rather than clone -> edit -> commit -> push.

IMPORTANT: Please never commit directly to production branch. All commits should go to main, and then merge maintoproduction. Note that it **is** possible to make a Pull Request for the merge from main-->production`. If you do so, please merge using a merge commit rather than a squash merge.

For larger edits it is recommended to build and preview the site locally. This lets you see the result of your changes instantly without committing anything. The bundled script uses a docker image to build and serve the site locally. Please make sure you have docker installed.

./build.sh -l       # live-reload on http://localhost:8000
./build.sh --help   # show all options

Now go to http://localhost:8000 to view the beautiful Solr web page served from your laptop with live-preview of updates :)

Updating the dependency lockfile

requirements.in is the human-editable list of direct dependencies. requirements.txt is the fully pinned, hash-verified lockfile generated from it. Dependabot updates both files automatically when it opens a pip bump PR. To regenerate manually after editing requirements.in:

./build.sh --lock

This runs pip-compile inside the Docker image (no local pip-tools install needed) and updates requirements.txt. Afterwards, rebuild the Docker image to pick up the changes:

./build.sh -b

Or combine both steps in one command:

./build.sh --lock -b

Commit both requirements.in and the updated requirements.txt together. The lockfile is used by build.sh (via pip install --require-hashes) and by the GitHub Actions workflows.

VEX (dependency CVE assessments)

The site publishes machine-readable VEX documents that state whether CVEs in Solr's bundled dependencies are actually exploitable in Solr. Each assessment is a Markdown file under content/solr/vex/ with YAML front matter (CVE id(s), affected versions range, vulnerable jars, and a CycloneDX analysis block); the front-matter shape is validated against plugins/vex/schema/vex_article.schema.yaml. To add or amend an assessment, edit these Markdown files — nothing else is required.

On every build the vex plugin turns those files into two documents in output/, so they are regenerated automatically and should not be hand-edited:

• solr.vex.json — CycloneDX 1.6
• solr.openvex.json — OpenVEX 0.2.0

To make a single statement match a dependency across every Solr release (each ships a different pinned version of it), the plugin expands each entry's affected versions range into one purl per concrete dependency version Solr actually shipped, using two data files in plugins/vex/:

• solr-versions.txt — the authoritative list of released Solr versions.
• solr-dependency-versions.json — a map of which version of each tracked dependency every Solr release shipped, built from a real syft SBOM scan of each release's binary distribution.

Both are committed. Regenerate them after a new Solr release, or after starting to track a new dependency, with:

./build.sh --vex-dependency-mappings

This first refreshes solr-versions.txt by discovering 9.0+ releases from archive.apache.org (union-only — it never drops existing entries), then downloads and syft-scans each release's binary distribution to fill in solr-dependency-versions.json. It requires python3 on the host (in addition to Docker, which runs syft) and is slow and bandwidth-heavy on a full run. Useful flags, passed after --:

./build.sh --vex-dependency-mappings -- 10.1.0         # only (re)scan specific versions
./build.sh --vex-dependency-mappings -- --no-discover  # skip the archive version-list refresh

See python3 plugins/vex/regenerate_dependency_mappings.py --help for the full list. Commit any changes to solr-versions.txt and solr-dependency-versions.json together with your VEX edits.

Other options

If you want to build the site without the docker image, you can install Python 3 and Pelican, see manual install for details.

On Windows, you can use the Windows Subsystem for Linux (WSL) to run the build script. Or you can run the docker command directly in a Terminal:

docker run --rm -ti -w /work -p 8000:8000 -v $(pwd):/work python:3-alpine sh -c "pip3 install -r requirements.txt; pelican content -r -l -b 0.0.0.0"

Updating site during a Solr release

The release manager documentation will contain detailed instructions on how to update the site during a release. Some of the boring version number update and download link generation is handled by Pelican, see below.

JavaDoc publishing and Solr RefGuide publishing is not done through this repo, but in SVN as detailed in Release Manager instructions, and will then appear in respective sections of the website automatically, see .htaccess for how.

Bump Solr latest version after the release

There are variables in pelicanconf.py to modify the latest 2 supported release versions. This will affect all references to release version in the theme, but not in pages or articles. Pelican views pages and articles as static write-once, like a blog post, whereas the theme can be more dynamic and change with every build.

Modify SOLR_LATEST_RELEASE and SOLR_PREVIOUS_MAJOR_RELEASE, and SOLR_LATEST_RELEASE_DATE to affect

• Full patch release versions in html such as "6.3.0".
• Minor release versions in html such as "6.3.x".
• References to unsupported versions such as "<6" in Solr downloads.
• References to upcoming unreleased versions such as "7" in Solr downloads which is a +1 increment of the SOLR_LATEST_RELEASE setting.
• Links to source, javadocs, PGP, and SHA512 which use underscores to separate version parts such as 6_3_0
• References to the release date of the latest version which can be dynamically formatted for different pages.