demo-lz-docs

Page Contents

• Intro
• Overview
• Site Content
• Site Hosting
• Updating the Site
• GCP Project Information
• Pipeline
• Developing the Site Locally

Intro

This is the documentation repo for Landing Zone Docs Demo. Here you will find:

• Content for the site itself
• Instructions on how to modify the content
• An overview of the CI/CD pipeline that builds the site

Overview

If you're creating a GCP landing zone for an organisation, you'll probably want to supply some documentation to go with it. Here I've created a set of re-usable LZ documentation, designed to be a starter-for-10 for any documentation an organisation might use in order to:

• Describe the purpose of the LZ.
• Describe the architecture.
• Describe the onboarding process for any new tenant on the LZ. (How to request your tenancy, a sample CI/CD pipeline that might be used, etc.)
• Describe the roles and responsibilities between the platform team that maintains the LZ, and the tenants that consume the LZ.
• A ready-made set of cloud principles the org might use.
• Placeholders for a decision tree to decide when something goes on the LZ or not.
• An area for documenting patterns and decision records.

If you wanted to create your own documentation, the idea is that you fork this repo, and then modify it to suit your needs.

Repo Structure

.
├── app/                         - The template for the Google App Engine Python web applicaton
├── content/                     - Where the site source content lives. THIS IS WHAT YOU UPDATE
├── src/                         - Hugo configuration and themes
├── themes/                      - In case we want to build using GitLab Hugo project
├── .github/workflows/pages.yml  - The GitHub Action CI/CD pipeline configuration (->GitHub Pages)
├── .gitlab-ci.yml               - The GitLab CI/CD pipeline configuration (->AppEngine)
├── config.toml                  - Configuration for Hugo to build the website from the source
├── README.md                    - This file
├── functions.sh                 - Bash helper functions, used by the pipeline
├── local.Dockerfile             - Hugo container image, for local site development
└── local.docker-compose.yml     - To facilitate building and launching the local Hugo container

Site Content

The site is primarily composed of markdown (.md) files which are converted to HTML during the build step for the site. The rendering of the markdown to HTML is achieved using Hugo.

All site content sits under the content folder. Adding sub-folders under the contents folder will create sub-sections. These each require an _index.md file for their landing page (see existing examples for inspiration). Other .md files in subfolders will exist as pages within the subsection. The entire content structure is therefore made up logically of folders and .md files.

It's recommended to look at the existing content folder and its contents and compare this to the live site for an easy understanding of how to structure your content.

Site Hosting

The static site generated by the CI/CD pipeline and can be hosted in various locations, e.g.

• Using GitHub Pages.
  • Uses the GitHub "Deploy Hugo site to Pages" action, which runs a Hugo container and then deploys from the public folder.
• As a Google App Engine service. See here for an overview of how it works.

Updating the Site

To update the site, make changes to content in your forked repo. If you're using one of the runners (e.g. the GitHub Action that is part of this repo), then your site will be built and deployed when you commit.

Pipeline

The pipeline currently has two steps: Build and Deploy.

• The Build step renders the website from the source (using Hugo), and outputs the resultant site to an artifact for the next step.
• The Deploy step deploys an App Engine application, which points to the site content created in the Build step.

Developing the Site Locally

If you are planning on making frequent or substantial changes to this site, it will be preferable to download this repo, and to make your changes locally before pushing back to the remote. Why? Because testing changes using the repo-hosted CI/CD process takes a couple of minutes. This can be a painful delay if you're making a lot of changes. Whereas changes made locally will be visible to you instantly.

There are a couple of ways to run this site locally.

1. You can install Hugo on your machine.
2. You can run Hugo as a container.

Personally, I prefer the container approach, because we can use the Docker Compose in this repo to run a container with the same version of Hugo that the CI/CD runner uses.

Below are instructions for how to run Huge in a container locally, in order to render the site on localhost.

Pre-Reqs

On your machine you will need:

• Docker.
  • E.g. by installing Docker Desktop or Rancher Desktop. (On Windows, both of these require WSL.)
• Git.
• Access to the repo.

Steps For Dynamic Build and Serve

Here the build output is never exposed. It is simply rendered in real time and made available through the service.

• Clone demo-lz-docs to your machine.
• Run the Docker compose, which will build and run the Hugo image from the local.Dockerfile:
  docker compose -f ./local.docker-compose.yml up
• You will see Hugo start up, and the console will show the localhost URL for your site.

To Run Container Interactively

If you want to interactively work with the container (e.g. for debugging):
docker run --rm -it --entrypoint /bin/sh -v $(pwd):/src -p 1313:1313 hugo-engine:0.1

(Use ${pwd} in Powershell.)

To Run a Build

We can perform a one-off build to generate the output:

docker run --rm -it -v $(pwd):/src hugo-engine:0.1

By default, the data in the mapped volume (/src) is used to build the output in a folder called public.

Alternatively, from the interactive container, we can simply run the following, in order to build from the current directory:

hugo -s .