Repository files navigation

This repo houses the assets used to build the Flux project's landing page athttps://fluxcd.io.

Note: The sources for some of Flux's documentation are housed in other repositories withinhttps://github.com/fluxcd. Documentation issues and pull requests should be made against those repos.

Project	Docs Site	GitHub Source
Flux	https://fluxcd.io/flux	https://github.com/fluxcd/website
Flagger	https://fluxcd.io/flagger	https://github.com/fluxcd/website

The main landing page of this website can be modified inhugo.yaml.

Almost all of the content lives in thecontent/en/<project> directories. Here are some special cases.

• ./content/en/blog contains all blog posts - make sure you update the front-matter for posts to show up correctly.
• ./external-sources/ defines how files from other repositories are pulled in. We currently do this for Markdown files from the/fluxcd/community and/fluxcd/.github repositories. (make gen-content pulls these in.)
• Flux CLI docs (cmd) andcomponents docs: under./content/en/flux but pulled in through inmake gen-content as well.
• /static/_redirects defines redirects onhttps://fluxcd.io. Check outhttps://docs.netlify.com/routing/redirects/ for the syntax definition and how to test if things work.

In order to run the Flux site locally, you need to install:

• Node.js
• TheHugo static site generator. Make sure toinstall the "extended" variant of Hugo with support for theHugo Pipes feature and to check thenetlify.toml configuration file for which version of Hugo you should install.
• jq

Once those tools are installed, fetch the assets necessary to run the site:

Then run the site in "server" mode:

make serve

Navigate tohttp://localhost:1313 to see the site running in your browser. As you make updates to the site, the browser will immediately update to reflect those changes.

Note: Sometimes you need to clear the output of previous builds, e.g. when the structure of imported documentation has changed. If you see duplicate pages being served, run

git clean -fx -- content/

and then runmake serve again. The duplicates will then be gone.

The Flux website is published automatically byNetlify when changes are pushed to themain branch. The site does not need to be published manually.

When you submit a pull request to this repository, Netlify builds a "deploy preview" of your changes. You can see that preview by clicking on theDetails link of thenetlify/fluxcd/deploy-preview check at the bottom of the pull request page.

Runmake docker-preview and wait until the following output appears:

Environment: "development"Serving pages from memoryWeb Server is available at //localhost:1313/ (bind address 0.0.0.0)Press Ctrl+C to stop

Visithttp://localhost:1313, where any changes will be visible from inside of the running container. Markdown files updated incontent/ should trigger a browser refresh as they are saved.

Thedocker-preview target builds the theme, which takes a while and doesn't need to be repeated unless you are making changes to the theme. On subsequent runs, runningmake docker-serve instead will skip building the theme.

This depends on the Docker imagefluxcd/website:hugo-support which should be kept updated when the website's build-time dependencies have changed; this image contains everything needed to run the docs locally.

If this doesn't work, the image may be stale. The instructions to update it are below.

This works the same as local development above, but with the Okteto CLI you do not need to run a Linux machine or virtual machine on your local development environment.

First, make sure you are permitted to deploy pods on any local or remote Kubernetes cluster. Download theOkteto CLI for Windows, Mac, or Linux.

Okteto CLI is a light-weight client-side tool that replaces Docker with a remote cluster. You can runhugo server remotely in this way; any changes to the local clone are synchronized to the cluster. The experience is basically the same as local development, (except that you won't need to install Docker.)

Instead ofmake docker-serve, typeokteto up.

You can change the behavior inokteto.yml according to theOkteto Manifest Reference, for example adding a persistent volume can speed up the synchronization of the working directory files to the remote pod on repeated runs.

(For maintainers) Using a machine withdocker and logged in with an account that has permission to push todocker.io/fluxcd/website repo, runmake docker-push.

The dependencies ofdocker-push are explained below. If the above worked then you are done, and should not need to read any further. Rebuildinghugo takes a long time and should be avoided when the version hasn't changed or it isn't needed; runmake docker-push-support instead to skip buildinghugo.

Update thedocker-support image tag whenever build-time (or "serve"-time) dependencies have changed.

These targets as explained below are run in the appropriate order as dependencies ofmake docker-push.

• TODO: add a system/integration test forwebsite that verifies any changes have not brokenmake docker-serve, for example by adding new dependencies without mentioning them in the./Dockerfile.

The Flux website has some build-time dependencies including Python3, PyYAML,rsync,grep,nodejs,npm,curl,jq, (and potentially others that may be added in the future.) Flux-specific dependencies are prepared in an image that gets tagged asdocker.io/fluxcd/website:hugo-support.

This image is built from theDockerfile in./; runmake docker-build-support to rebuild it locally, (or run asmake docker-push-support to build and also push.)

The Flux website also depends on a specific version of Hugo, which unfortunately does not provide docker images for each version. So we build it from source, with theHUGO_BUILD_TAGS=extended build arg enabled.

Runmake docker-push-hugo to build and also push this image target.

This will runmake hugo to get a shallow clone of thegohugoio/hugo repository at the rightHUGO_VERSION andmake docker-build-hugo to build a hugo container base image. (This target compilesgolibsass which is very large, and may take a while.)

These are all the dependencies ofmake docker-push.