CHANGEME Training Description
The training content resides within the content directory.
The main part are the labs, which can be found at content/en/docs.
This site is built using the static page generator Hugo.
The page uses the docsy theme which is included as a Hugo Module. Docsy is being enhanced using docsy-plus as well as docsy-acend and docsy-puzzle for brand specific settings.
After cloning the main repo, you need to initialize the Hugo Module like this:
hugo mod get
The default configuration uses the acend setup from config/_default.
Alternatively you can use the Puzzle setup from config/puzzle, which is enabled with
--environment puzzle
.
Run the following command to update all submodules with their newest upstream version:
hugo mod get -u
The onlyWhen
and onlyWhenNot
shortcodes allow text to be rendered if certain conditions apply.
{{% onlyWhen variant1 %}}
: This is only rendered whenenabledModule
inconfig.toml
containsvariant1
{{% onlyWhen variant1 variant2 %}}
: This is only rendered whenenabledModule
inconfig.toml
containsvariant1
orvariant2
{{% onlyWhenNot variant1 %}}
: This is only rendered whenenabledModule
inconfig.toml
does not containvariant1
{{% onlyWhenNot variant1 variant2 %}}
: This is only rendered whenenabledModule
inconfig.toml
does not containvariant1
orvariant2
In order to only render text if all of multiple conditions do not apply simply chain several onlyWhenNot
shortcodes:
{{% onlyWhenNot variant1 %}}
{{% onlyWhenNot variant2 %}}
This is only rendered when `enabledModule` in `config.toml` **does not** contain `variant1` **nor** `variant2`.
{{% /onlyWhen %}}
{{% /onlyWhen %}}
Build the image:
docker build [--build-arg TRAINING_HUGO_ENV=...] -t acend/changeme-training .
Run it locally:
docker run --rm -p 8080:8080 acend/changeme-training
Build the image:
buildah build-using-dockerfile [--build-arg TRAINING_HUGO_ENV=...] -t acend/changeme-training .
Run it locally:
podman run --rm --rmi --publish 8080:8080 localhost/acend/changeme-training
Note: Beware that --rmi
automatically removes the built image when the container stops, so you either have to rebuild it or remove the parameter from the command.
You can use docker-compose
. If you prefer Podman check out podman-compose.
docker-compose up
Use the following command to set the hugo environment
HUGO_ENVIRONMENT="something" docker-compose up
To rebuild the image if something changed in the Dockerfile
:
docker-compose up --build
The website is available at localhost:8080
Tip: Set the following environment variables for faster builds: DOCKER_BUILDKIT=1 COMPOSE_DOCKER_CLI_BUILD=1
To develop locally we don't want to rebuild the entire container image every time something changed, and it is also important to use the same hugo versions like in production. We simply mount the working directory into a running container, where hugo is started in the server mode.
export HUGO_VERSION=$(grep "FROM docker.io/klakegg/hugo" Dockerfile | sed 's/FROM docker.io\/klakegg\/hugo://g' | sed 's/ AS builder//g')
docker run --rm --publish 8080:8080 -v $(pwd):/src docker.io/klakegg/hugo:${HUGO_VERSION} server -p 8080
Use the following command to set the hugo environment
export HUGO_VERSION=$(grep "FROM docker.io/klakegg/hugo" Dockerfile | sed 's/FROM docker.io\/klakegg\/hugo://g' | sed 's/ AS builder//g')
docker run --rm --publish 8080:8080 -v $(pwd):/src docker.io/klakegg/hugo:${HUGO_VERSION} server --environment=<environment> -p 8080
Markdown files are linted with https://github.com/DavidAnson/markdownlint.
Custom rules are in .markdownlint.json
.
There's a GitHub Action .github/workflows/markdownlint.yaml
for CI.
For local checks, you can either use Visual Studio Code with the corresponding extension, or the command line like this:
npm install
npm run mdlint
Npm not installed? no problem
export HUGO_VERSION=$(grep "FROM docker.io/klakegg/hugo" Dockerfile | sed 's/FROM docker.io\/klakegg\/hugo://g' | sed 's/ AS builder//g')
docker run --rm -v $(pwd):/src docker.io/klakegg/hugo:${HUGO_VERSION}-ci /bin/bash -c "npm install && npm run mdlint"
Automatically fix errors if possible:
npm run mdlint-fix
- create an empty git repo
- Copy the contents of this repo to it
- Install latest hugo binary
- Init the site as Hugo Module
hugo mod init github.com/acend/<training>
- Add the Hugo Modules Dependencies
hugo mod get github.com/google/docsy
hugo mod get github.com/google/docsy/dependencies
hugo mod get github.com/acend/docsy-plus
hugo mod get github.com/acend/docsy-acend
hugo mod get github.com/puzzle/docsy-puzzle
- replace all CHANGEME
https://github.com/changeme/changeme-training
to your repo urlquay.io/acend/hugo-training-template
to your image registry urlacend/changeme-training
to your org and trainingchangeme/changeme-training
to your org and trainingacend-hugo-training-template-prod
to your prod deployment namespaceacend-hugo-training-template-test
to your test deployment namespacehugo-training-template
to your trainingchangeme-training
to your trainingchangeme Training
to your training name, eg.Hugo Training
acend-hugo-template
to your org and training- check remaining
changeme
's
- Configure all names, URLs and so on in the build actions and values.yaml
- remove
How to setup an entire new Training
chapter from README.md - adapt or remove not needed variants in the config folder
- Create a container image Repo and make sure the secrets configured in the Github actions have access to the repo
- Create two namespaces on your k8s cluster, make sure the secrets configured in the Github actions have access to the k8s Cluster and namespace or project in case of rancher
- Test namespace: used to deploy PR Environments
- Prod namespace: prod deployment
Add the quota to the test namespace:
kubectl apply -f object-count-quota.yaml -n <namespace>
The build action is fired on Pull Requests does the following
- builds all PR Versions (Linting and Docker build)
- deploys the built container images to the container registry
- Deploys a PR environment in a k8s test namespace with helm
- Triggers a redeployment
- Comments in the PR where the PR Environments can be found
The pr-cleanup action is fired when Pull Requests are closed and does the following
- Uninstalls PR Helm Release
The push main action is fired when a commit is pushed to the main branch (eg. a PR is merged) and does the following, it's very similar to the Build Action
- builds main Versions (Linting and Docker build)
- deploys the built container images to the container registry
- Deploys the main Version on k8s using helm
- Triggers a redeployment
Manually deploy the training Release using the following command:
helm install --repo https://acend.github.io/helm-charts/ <release> acend-training-chart --values helm-chart/values.yaml -n <namespace>
For debugging purposes use the --dry-run
parameter
helm install --dry-run --repo https://acend.github.io/helm-charts/ <release> acend-training-chart --values helm-chart/values.yaml -n <namespace>
- Install the latest version of the hugo extended version binary: https://github.com/gohugoio/hugo/releases
- Init the site as Hugo Module
hugo mod init github.com/acend/<training>
- Add the Hugo Modules Dependencies
hugo mod get github.com/google/docsy
hugo mod get github.com/google/docsy/dependencies
hugo mod get github.com/acend/docsy-plus
hugo mod get github.com/acend/docsy-acend
hugo mod get github.com/puzzle/docsy-puzzle
- Remove
themes
definition from config.toml files - Add Hugo module definitions in config.toml files
# acend design
[module]
[module.hugoVersion]
extended = true
min = "0.100.0"
[[module.imports]]
path = "github.com/acend/docsy-acend"
disable = false
[[module.imports]]
path = "github.com/acend/docsy-plus"
disable = false
[[module.imports]]
path = "github.com/google/docsy"
disable = false
[[module.imports]]
path = "github.com/google/docsy/dependencies"
disable = false
# puzzle design
[module]
[module.hugoVersion]
extended = true
min = "0.100.0"
[[module.imports]]
path = "github.com/puzzle/docsy-puzzle"
disable = false
[[module.imports]]
path = "github.com/acend/docsy-plus"
disable = false
[[module.imports]]
path = "github.com/google/docsy"
disable = false
[[module.imports]]
path = "github.com/google/docsy/dependencies"
disable = false
- remove all Submodules
git rm themes/docsy themes/docsy-plus themes/docsy-acend themes/docsy-puzzle
- Add the changes and commit them
Update the dependencies:
hugo mod get -u
Remove the imports for the github.com/google/docsy
and github.com/google/docsy/dependencies
from config.toml
Add and commit the changes
If you find errors, bugs or missing information please help us improve and have a look at the Contribution Guide.