docs: theme, documenting intro and packer.

docs/conf.py

@@ -31,6 +31,7 @@ release = '0.0.1-pre'
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    'sphinx.ext.graphviz'
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -47,7 +48,8 @@ exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+# html_theme = 'alabaster'
+html_theme = 'sphinx_rtd_theme'
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,

docs/index.rst

@@ -10,7 +10,9 @@ bladerunner
    :maxdepth: 2
    :caption: Contents:
 
+   intro
    packer
+   tools
 
 This is my setup for my
 `computeblade <https://publish.obsidian.md/ai6ua/Projects/Computing/ComputeBlade>`_

docs/intro.rst

@@ -0,0 +1,66 @@
+Introduction
+============
+
+I'm working on building a cluster of Raspberry Pi CM4 compute blades. I plan on
+using the cluster to learn a bunch of stuff, but I need to be able to provision
+the blades automatically. This repo is my work in that area.
+
+There are some assumptions made:
+
+1. All the systems involved are Debian-ish systems, particularly Ubuntu. The
+   build system here will assume this. It may work on non-Ubuntu apt-based
+   systems. For non-Debian systems, I've also been working on including
+   container builds that may work.
+
+There are three types of systems:
+
+- ``dev`` indicates DEV compute blades.
+- ``tpm`` indicates TPM compute blades.
+- ``gw`` indicates the gateway system, which may perform other functions.
+
+The `computeblade docs <https://docs.computeblade.com/>`_ has a description of
+the different blade types.
+
+Below is a diagram of the planned system.
+
+.. graphviz ::
+
+    digraph cluster {
+        subgraph {
+            dev01;
+            dev02;
+            dev03;
+            dev04;
+            dev05;
+
+            tpm01;
+            tpm02;
+            tpm03;
+            tpm04;
+            tpm05;
+        }
+
+        "poe-switch" -> dev01 [dir=both];
+        "poe-switch" -> dev02 [dir=both];
+        "poe-switch" -> dev03 [dir=both];
+        "poe-switch" -> dev04 [dir=both];
+        "poe-switch" -> dev05 [dir=both];
+
+        "poe-switch" -> tpm01 [dir=both];
+        "poe-switch" -> tpm02 [dir=both];
+        "poe-switch" -> tpm03 [dir=both];
+        "poe-switch" -> tpm04 [dir=both];
+        "poe-switch" -> tpm05 [dir=both];
+
+        "poe-switch" -> gw [dir=both];
+        publicnet    -> gw [dir=both];
+    }
+
+
+The hardware isn't slated to arrive until September at the earliest.
+
+Hardware
+--------
+
+Blades:
+

docs/packer.rst

@@ -2,3 +2,38 @@ packer
 ======
 
 `packer <https://www.packer.io/>`_ is used to generate the base images for the cluster.
+
+Build scripts
+-------------
+
+There are a few scripts that are used in building a packer image. In general,
+the workflow looks like:
+
+1. ``install-packer.sh``
+2. ``build-image.sh``
+
+``install-packer.sh``
+^^^^^^^^^^^^^^^^^^^^^^
+
+``install-packer.sh`` will install ``packer`` and ``packer-builder-arm``. If
+``git`` isn't installed, it will assume that it should install dependencies. It 
+will attempt to install these dependencies with ``apt``.
+
+The script will clone the ``packer-builder-arm`` into the ``build`` directory.
+
+The dependencies required to build images with ``packer`` are:
+
+- git
+- unzip
+- xz-utils
+- qemu-user-static
+- e2fsprogs
+- dosfstools
+- libarchive-tools
+
+Go will also need to be installed; there is a script provided in the :doc:`tools`
+directory.
+
+Board files
+------------
+

docs/requirements.txt

@@ -1 +1,2 @@
 Sphinx==4.3.2
+sphinx-rtd-theme==1.2.0

docs/tools.rst

@@ -0,0 +1,4 @@
+tools
+=====
+
+The ``tools`` directory contains various helper scripts.

packer/build-image.sh

@@ -12,7 +12,8 @@ errmsg () {
 preflight () {
     case "${IMAGE_TYPE}" in
         ubuntu) PACKER_BUILD_FILE="boards/cm4-cluster-ubuntu-22.04.2.json" ;;
-        raspbian) PACKER_BUILD_FILE="boards/raspberry-pi/raspios-lite-arm.json" ;;
+        ## TODO(kyle): look into building a Raspbian version if needed.
+        # raspbian) PACKER_BUILD_FILE="boards/raspberry-pi/raspios-lite-arm.json" ;;
         custom)
             if [ -z "${PACKER_BUILD_FILE}" ]
             then
@@ -23,7 +24,7 @@ preflight () {
         *)
             errmsg "[!] invalid image type ${IMAGE_TYPE}."
             errmsg "[!] valid image types are"
-            errmsg "    - raspbian"
+            # errmsg "    - raspbian"
             errmsg "    - ubuntu"
             errmsg "    - custom path/to/board/file"
             exit 1

packer/install-packer.sh

@@ -9,9 +9,13 @@ PACKER_FILE=packer_${PACKER_VERSION}_linux_${ARCH}
 UPSTREAM="https://github.com/mkaczanowski/packer-builder-arm"
 UPGRADE="false"
 BUILD_DIR="$(pwd)/build"
+FORCE_DEPENDENCY_INSTALL="no"
 
 prep () {
-    sudo apt-get update && sudo apt-get -y install git unzip qemu-user-static e2fsprogs dosfstools 'bsdtar|libarchive-tools'
+    if [ -z "$(command -v git)" -o "${FORCE_DEPENDENCY_INSTALL}" = "yes" ]
+    then
+        sudo apt-get update && sudo apt-get -y install git unzip qemu-user-static e2fsprogs dosfstools libarchive-tools
+    fi
     mkdir -p ${BUILD_DIR}
     pushd ${BUILD_DIR}
 }