Quickstart

We will assume a Ubuntu 24.04LTS host system and bash shell throughout this documentation.

Build and runtime dependencies

Install docker, kubectl, kind, helm, and screen. For Docker, follow the instructions for installing Docker using apt. For the other software packages:

sudo snap install kubectl --classic
sudo snap install helm --classic
sudo snap install go --classic
go install sigs.k8s.io/kind@latest
sudo apt install screen

$ which docker kubectl kind helm screen
/usr/bin/docker
/snap/bin/kubectl
/home/yinchi/go/bin/kind
/snap/bin/helm
/usr/bin/screen

Development dependences

For development, we recommend Visual Studio Code (VSCode). Poetry is used for Python package management, install this as follows:

sudo apt install pipx
pipx install poetry

# Optional plugins
poetry self add poetry-dockerize-plugin
poetry self add poetry-plugin-export

# Show plugins
poetry self show plugins

Next, cd into each subdirectory of src/ and run poetry install.

You will probably also want to install the following VSCode extensions:

• isort

• pylint

• Go Template Support

• Helm Intellisense

• Kubernetes

• Poetry Monorepo

Bash scripts

Copy the files in copy_this_to_local_bin to a directory on your $PATH, e.g. $HOME/.local/bin. Currently, this is just prepend_path, which is used to add our scripts directory to the $PATH environment variable.

Secret files

Find the files containing secret.example in their filenames and copy them.

$ find . -path './mnt/*' -prune -o -name '*secret.example*' -print | \
  xargs -I {} echo cp {} {} | sed 's/secret.example/secret/2' | tee >(bash)
cp ./helm/values/postgres0/secret.example.yaml ./helm/values/postgres0/secret.yaml
cp ./src/test-module/.env.secret.example ./src/test-module/.env.secret

Note

The above script searches for files with secret.example in their paths, omitting mnt/, then uses xargs and sed to create a bash script to cp the relevant files.

It is assumed that secret.example occurs only once in each file’s path.

Edit the newly created files to set up the necessary secrets for the app.

Launching the Kubernetes stack

The file kind.yaml defines the configuration for our kind cluster, including extra mounts for database persistence.

Start the kind cluster with:

kind create cluster --config kind.yaml

Finally, source the init.sh script:

. init.sh

This script will:

• Build all containers in the Docker Compose file (compose.yml)

• Create an myapp namespace in Kubernetes

• Create all the myapp resources (services, secrets, persistent volumes, etc.)

• Forward ports for the frontend (8000) and Traefik dashboard (9000), using screen.

The stack can be torn down using . destroy.sh. To remove the cluster entirely, use kind delete cluster.

Bash aliases

The load_scripts.sh file contains a number of bash aliases and functions for convenience. For example, we can use ns myapp to make myapp the default namespace, or pods to list the currently running pods in the myapp namespace (in the current kind context).

The init.sh file calls load_scripts.sh automatically. Alternatively, we can execute . load_scripts.sh manually.