spiffe.io

This repository contains the source for the SPIFFE website, currently hosted at https://spiffe.netlify.com. That website also contains the documentation for SPIRE, the SPIFFE Runtime Environment.

Toolchain

The site is built using:

• Hugo
• The Bulma CSS framework

Develop the site locally

To develop the locally, you'll first need to install some assets (mostly Sass assets) using npm:

make setup

With those assets in place, you can run the site locally using Hugo or Docker.

Hugo

To run the site using Hugo, make sure it's installed and then run:

make serve

Check the HUGO_VERSION environment variable in the netlify.toml configuration file to see which Hugo version is deemed canonical for the SPIFFE website. Any Hugo version at or after that version should work fine. If you plan on working on the Sass/CSS, make sure to install the "extended" version of Hugo with support for Hugo Pipes, which processes the Sass in realtime.

Docker

If you have Docker installed, a convenient alternative to installing Hugo itself is to simply run:

make docker-serve

Publishing the site

The site is published automatically by Netlify. Whenever you merge pull requests to master, the site is automatically built and published in about a minute. There's no need to handle this manually.

Updating the site

The assets used to build the site are in a variety of directories and formats.

The "Who uses SPIFFE?" section

The list of issuers and consumers in the "Who uses SPIFFE?" section of the home page is generated using the data/users.yaml file. Make sure to add name, description (supports Markdown), logo file (all logos should be added to static/img/logos), and a link to an external page.

Documentation

Markdown sources for the documentation are in the content directory.

Latest SPIRE version

Hugo can automatically infer the latest version of SPIRE using the GitHub Releases API. To insert that version into text, use the spire-latest shortcode. This shortcode has a mandatory parameter that can be either version, tag or tarball.

Here's an example:

The most recent version of SPIRE is "{{< spire-latest "version" >}}", that is tagged as "{{< spire-latest "tag" >}}" and packed in the file "{{< spire-latest "tarball" >}}"

that will generate the following output:

The most recent version of SPIRE is "0.9.3", that is tagged as "v0.9.3" and packed in the file "spire-0.9.3-linux-x86_64-glibc.tar.gz"

The Downloads page

The Downloads page is built automatically using information from the GitHub Releases API. You can alter the text of the Downloads page in content/downloads/_index.md.

The SPIFFE specification

The Specification section of the main SPIFFE page is generated using a YAML list in data/spec.yaml.

Shortcodes

Hugo has a feature called shortcodes that enables you to embed custom logic in Markdown files. The shortcodes for the site are in layouts/shortcodes.

Acknowledgments

The shortcode for the "Acknowledgments" section of the Community page is in the acknowledgments.html shortcode. To alter the contents of this section, update the data/acknowledgments.yaml file.

Admonition blocks

There are four admonition blocks available for the site: info, danger, success, and warning. Here's an example:

{{< info >}}
Here's some important info regarding the SPIFFE project.
{{< /info >}}

Admonition blocks support Markdown.