Wild Waggle Node Image Customization Example

This repository is an example (that can be forked) for how to customize the wildnode-image. The open-source wildnode-image is an open platform and therefore has open credentials (for the root user) and is missing potential secrets needed for a production deployment. The tools provided here are a template for how to add customizations and secrets to build a secure wildnode-image.

It is highly recommended that the entirity of this README is read before getting started.

How it works?

The following steps are taken to create the customized wildnode-image image:

1. The wildnode-image code is cloned into a ./_workdir
2. Any changes within the ROOTFS folder are synced "on top" of the wildnode-image cloned code
3. Any (optional) additional file system modifications are made as defined within the ./overlay.sh script
4. A "secret" version file is created within the cloned wildnode-image file system to be included in the resulting build image
5. The wildnode-image build script (i.e. ./_workdir/build.sh) is executed, creating the customized wildnode-image image

Creating your custom wildnode-image repository

In order to build your own custom wildnode-image you will need to create your own GitHub project (ex. wildnode-myproject) to store your custom changes and build / store the built images. To create your own project the following steps need to be taken:

1. Create a new repository (within the waggle-sensor organization) using this repository as a template

   You probably want to create your project as a "private" repository as it will contain your secrets to secure your customized image.

2. Execute the steps to setup your own GitHub Self-Hosted Runner. See Configuring your GitHub self-hosted runner below.

   This is necessary as the image build process requires more resources than are allowed in a standard GitHub runner. It is recommended to use an x86 Linux machine for this self-hosted runner.

3. Tag the first commit of your git repository to v0.0.0 (i.e. git tag v0.0.0).

   This is necessary to ensure a proper version (ex. customexample-0.0.0-1-gfe06d2d) can be created and attached to the build image files.

Now that your GitHub project exists, you can start committing code changes to it that will modify the wildnode-image file system.

In fact, the first commit you should make is to modify the ./project_name file from the default example project name to something more specific to your project (ex. custom_project). It is used in the naming of the resulting image file and the version stored in the image.

Usage Instructions

When making custom changes and to secure your own wildnode-image image the following steps needs to be taken:

1. Add file system customizations to the ROOTFS folder within this repository.

   Simply place a file into ROOTFS directory in the exact relative path you desire the file to appear in the resulting image. For example, if you want to create a the /etc/waggle/demofile in the resulting image you could do the following:

   mkdir -p ./ROOTFS/etc/waggle
   echo "demo file contents" > /etc/waggle/demofile

   It is important to replace the ./ROOTFS/root/credentials file contents with a secure password, as this will be the password of the root user in the resulting image. See Creating the root user credentials below.

   See the wildnode-image for more details on the secrets that will need to be added to build a fully functional image.

2. Optionally, make modifications to the ./overlay.sh script to change how the base wildnode-image file system is modified

   There is a "placeholder" section within the ./overlay.sh script that is intended for more advanced file system customizations. See Appending a base wildnode-image file example below.

3. Update the ./base_image_tag file to indicate the base version of wildnode-image that you want to use.

   $ cat ./base_image_tag
   v1.9.0

   See the wildnode-image tags for a list of valid tags

4. Execute the ./build.sh script to start the build process.

   ./build.sh <arguments>

   See wildnode-image build.sh script for details on build arguments

5. Extract the resulting image from the ./_workdir folder.

   $ ls -la _workdir/*.tbz2
   -rw-r--r--  1 jswantek  staff  4004545457 Aug 29 16:53 _workdir/testbuild_mfi_nx-1.9.0-0-ga2a8c51.tbz2

Creating a Release

After all the code changes have been made and merged to origin/main, a "release image" can be created in GitHub. This is done by creating a git tag and pushing the tag to GitHub.

git tag v<tag version>
git push origin v<tag version>

This will automatically trigger the release to be built via the GitHub workflow defined in ./.github/workflows/release.yml.

Advanced Details & Instructions

Configuring your GitHub self-hosted runner

Building the image requires more resources than are offered in the GitHub-hosted runners and therefore a GitHub Self-Hosted Runner needs to be created.

This repository uses GitHub Reusable Workflows to reference the "CI" and "Release" workflows of wildnode-image. These workflows will use your defined "Self-Hosted Runner" assuming it follows the runner rules.

Creating the root user credentials

The root credentials file (/root/credentials) is a salted file used to set the root user password on the image. To set the contents of the file do the following:

echo "PASSWORD" | mkpasswd --stdin --method=sha-512

Appending a base wildnode-image file example

Files within the ROOTFS directory are copied (in their entirety) to the image file system. If it desired to modify a file on the resulting file system this can be done with the same basic bash commands. For example, the following example concatenates the contents to the end of the config-prod.ini file.

pushd ${BASE_WORKDIR}/ROOTFS/etc/waggle/
cat config.ini-customize >> config-prod.ini
popd

The ./overlay.sh files contains a "placeholder" section setup for customizations.

Versioning your custom image

The version string (ex. customexample-1.1.2-0-g962859e) of the customized repo (constructed from the contents of the project_name file and the repository git tag) is appended to the wildnode-image version string (ex. nx-1.8.8-0-g5a64cdf) at build time. This combined version (ex. nx-1.8.8-0-g5a64cdf-customexample-1.1.2-0-g962859e) is included in the resulting image's version file (i.e. /etc/waggle_version_os).

$ cat /etc/waggle_version_os
nx-1.8.8-0-g5a64cdf-customexample-1.1.2-0-g962859e [kernel: Tegra186_Linux_R32.4.4_aarch64 | rootfs: Waggle_Linux_Custom-Root-Filesystem_nx-1.8.8-0-g5a64cdf-customexample-1.1.2-0-g962859e_aarch64 | cti_kernel_extension: CTI-L4T-XAVIER-NX-32.4.4-V005-SAGE-32.4.4.7-0-g205b5bb6d]

The above example indicates the base wildnode-image was on git tag 1.8.8 (sha1: 5a64cdf) while the forked build repository (ex. wildnode-myproject) was on git tag 1.1.2 (sha1: 962859e).