https://geoserver.org

This repository contains the source for the GitHub generated GeoServer home page.

Reporting issues

If you stumble into any issue with the GeoServer web site please report it in our Jira issue tracker using the website component.

Developing

The site is built with Jekyll:

#. Before you start:

gem install bundler 

Install from Gemfile list:

bundle install

On macOS with apple silicon:

bundle update ffi

#. Jekyll can be run in "watch" mode for development:

bundle exec jekyll serve --watch

The site contents will be served at http://localhost:4000.

See TEST.md for more details.

#. Commit to main branch and the result is published to https://geoserver.org

Blog

Blog posts are managed as part of the website.

To create a new blog post:

1. Create a new markdown page in _posts following the filename convention for sort order:

   _posts/2021-05-04-may-the-fork-be-with-you.md

2. The post is published using the metadata included at the top of your file.

   ---
   author: Andrea Aime
   date: 2021-05-04
   layout: post
   title: May the fork be with you!
   categories:
   - Developer notes
   ---
   

3. Popular categories include:

   • Developer notes
   • Announcements -- used for project team and release announcements
   • Tips and Tricks
   • Tutorials
   • User perspectives

Releases

When a release is performed, the site contents are updated to reflect the new release. Below is the process of updating site contents for a stable release.

1. Manually (in the GUI) search JIRA for issues with level = Vulnerability that are hidden from the JQL API:

   If there is a fix version which includes the current release, but is scheduled for a later release, then include the --security command line argument, which will simply add a generic placeholder text

   Sample JQL: (level = Vulnerability AND fixVersion = 2.26.4 AND Disclosure > 2.26.4)

2. Write a blog post announcing the new release:

   cd bin
   python3 announcement.py username password 2.23.2 --geotools  29.2 --geowebcache 1.23.2  [--security]
   

   username and password are your JIRA credentials.

   A post is generated to stdout for your review.

   If everything looks good generate a post using (the date for the generated post is supplied by Jira):

   python3 announcement.py username password 2.23.2 --geotools  29.2 --geowebcache 1.23.2 --post
   

   Security Vulnerability Options:

   • Use --security to force a security section (automatically added if vulnerabilities are detected)
   • Use --urgency normal|important|urgent to set security urgency level (default: important)
   • Use --concurrent "2.25.3,2.26.1" to mention concurrent security releases
   • Use --disclosure 2.27.0 to generate updates for prior blog posts when vulnerabilities are disclosed

   See script instructions for more information, python3 announcement.py --help for more options.

   note: At the start of a new series (when making a milestone or release candidate) a new bin/templates/about22?.md template will be required for the script to work.

3. Release posts have the following format

   ---
   author: Jody Garnett
   date: 2024-09-18
   layout: post
   title: GeoServer 2.26.0 Release
   categories:
   - Announcements
   - Vulnerability
   tags:
   - Release
   release: release_226
   version: 2.26.0
   jira_version: 16916
   doi:13827176
   --- 
   

   The following information is used to generate a release/<version>/index.html page:

   • release: This is the _layout used for the generated release page

   • Tags are used to indicate Release, Release Candidate, Milestone.

     The Vulnerability tag is used to highlight blog posts and release announcements covering a security topic.

   • version: The GeoServer version being announced

   • jira_version: Used to track the latest release for each branch displayed on the home page.

     The value for jira_version can be found by navigating to that version on Jira and examining the URL. For example, for example, 2.7.2 links to https://osgeo-org.atlassian.net/projects/GEOS/versions/10601, giving a jira_version of 10601. For a maintenance or development release, instead modify release/maintain/index.html or release/dev/index.html respectively.

   • doi: Is generated by zendo processing the tag and can be found on zendo

4. Check one of the previous blog posts so we end up with a consistent format.

   • GeoTools and GeoWebCache version numbers will need to be supplied on the command line
   • Check the "about section" at end of post with links to documentation / proposals / presentations

5. Update _config.yml (this change will be reflected in index.html and download/index.html):

   • Update stable_nightly to be the same as the next release, this is used for the Nightly build page.

     stable_nightly:      16821
     

   • For a maintenance instead change maintain_nightly.

     maintain_nightly:    16819
     

Dev Releases and Main branch

When publishing the first milestone, beta or release candidate for a series:

1. Check _layout/release_main.html for any extensions that need to be added (or removed) for the new release.

2. Create a new _layouts/release_<version>.html template by copying the _layout/release_main.html template.

   This is the value used for release when making your announcement blog posts.

   Create bin/templates/about_XXX.md highlighting new features, GSIP proposals, key presentations.

3. Update _config.yml update dev_branch and dev_nightly the matching release announcement post will be used to generate release/dev/index.html page.

   dev_branch:       2.27.x
   dev_nightly:         16884
   

   When dev_branch is not main the build process scan for the latest development release for public testing.

4. Update the main_series, and main_nightly to reflect the new version number for main branch, this will be used to generate a placeholder for release/main/index.html page.

   main_series       2.28.x
   main_nightly:        16829
   

   As the main branch always has the same name main_series is used to provide the name to use for generating links.

Final Release

When creating the final release:

1. Update the _config.yml properties:

   • Update the maintain_branch using the values from stable.
   • Update the stable_branch.

2. Update the main_series and main_nightly information. For example, when starting the series 2.22.x:

   main_series:      2.29.x
   main_nightly:        16829
   

   As the main branch always has the same name main_series is used to provide the name to use for generating links.

3. Restore dev_branch property in _config.yml to main.

   dev_branch:       main
   dev_nightly:         16829
   

   When dev_branch is main the build process will no longer match any posts as the development period is over.

Security Vulnerability Disclosure

The announcement script includes enhanced support for security vulnerability disclosure management (GEOS-11928).

Vulnerability Detection

The script automatically detects and categorizes vulnerabilities:

• Disclosed vulnerabilities - Issues scheduled for public disclosure (Disclosure field set with released version)
• Undisclosed vulnerabilities - Issues not yet scheduled for disclosure or with future disclosure dates
• Legacy vulnerabilities - Issues using the component-based approach (component = "Vulnerability")

Security Urgency Levels

Security releases can be marked with different urgency levels using the --urgency option:

• normal - Standard security update
• important - Recommended security update (default)
• urgent - Critical security update requiring immediate attention

Prior Blog Post Updates

When vulnerabilities are publicly disclosed, the --disclosure option generates update instructions for prior release announcements:

python3 announcement.py username password 2.26.4 --disclosure 2.27.0

This produces:

• List of vulnerabilities scheduled for disclosure in version 2.27.0
• Identification of earlier blog posts that need security sections added
• Ready-to-use markdown text for updating prior announcements

JIRA Security Model

Security vulnerabilities with level = "Vulnerability" have restricted visibility in JIRA and won't appear in standard queries until scheduled for disclosure. This is intentional security-by-design behavior. The announcement script handles this by:

1. Using the Disclosure field (customfield_11057) to detect scheduled disclosures
2. Supporting backward compatibility with component-based detection
3. Providing appropriate messaging when no vulnerabilities are detected

Technical Details

Jekyll Build

The Jekyll build process goes through several steps:

1. The file _config.yml is parsed into Jekyll::Site

   • site.data

2. Makes an inventory of existing content:

   • site.pages contains instances of Jekyll::Page for each page (and post) defined.

   • site.static_files contains Jekyll::StaticFile

3. Our custom plugin _plugins/release.rb generator is run:

   • Processes the posts in site.pages, add additional Jekyll::PageWithoutAFile entries to site.pages
   • Creates a site.data.releases data structure listing all the releases found for use by the download/index.html page.

4. Additional plugins are run:

   • jekyll-feed: generates an Atom feed of all the posts
   • jekyll-sitemap: generates a sitemap of all the pages
   • jekyll-paginate: uses _blog/index.html as a template to generate page2.html, page3.html, ... page80.html

5. At this point all the site.pages are created each containing:

   • page.title
   • page.content
   • page.url
   • page.date
   • page.id
   • page.dir
   • page.name
   • page.data provided by front-matter at the top of the file

   Release pages have:

   • page.data.version
   • page.data.jira_version
   • page.data.release_date
   • page.data.announce

6. Jekyll process any pages with Liquid into static files in the _site folder.

   • Variable reference use {{ and }}:

     Download the latest [GeoServer {{site.stable_version}}](/release/stable/index.html) release.
     

   • Variable filters use | pipe character to define a processing chain:

     Released {{ page.date | date_to_long_string }}.
     

   • Tags used to define control flow:

     {% for release in site.data.releases | where: "series", "2.19"  %}
       {{ release.version }}
     {% endfor %}
     

   Here is a decent cheatsheet for reference.

Publishing

Commit to main and the result is published.

Technical details:

1. Commit to the main branch.

2. Workflow .github/workflows/build-jekyll.yml action is triggered.

   • Uses ubuntu-latest environment

   • Uses JEKYLL DEPLOY ACTION

     • Runs Jekyll build to generate static files (just like normal)

     • Commits the resulting static files to the gh-pages branch

3. GitHub pages settings is configured to publish the gh-pages branch to https://geoserver.github.io.

   • The CNAME geoserver.org managed by OSGeo System Admin Committee

   The content is available as the https:/geoserver.org website