RTOP-283: update the runtime from the editor, over Docker

.github/workflows/docker.yml

@@ -4,6 +4,14 @@ on:
   push:
     tags:
       - 'v*'
+    # The bootloader has its own version line, so it also builds from a branch
+    # push without waiting for a runtime tag. Deliberately no `paths` filter:
+    # GitHub applies it to tag pushes as well, which would make the runtime
+    # release build conditional on bootloader files having changed. The jobs below
+    # gate themselves instead.
+    branches:
+      - development
+      - main
   workflow_dispatch:
     inputs:
       platforms:
@@ -18,6 +26,10 @@ on:
 
 jobs:
   build:
+    # Release tags and manual runs only -- unchanged from before the bootloader
+    # job was added. A branch push produces no semver tag for the metadata
+    # step, so letting it through would fail with an empty tag list.
+    if: startsWith(github.ref, 'refs/tags/v') || github.event_name == 'workflow_dispatch'
     runs-on: ubuntu-latest
     permissions:
       contents: read
@@ -67,3 +79,132 @@ jobs:
           # default ("dev") for ad-hoc builds without a release tag.
           build-args: |
             RUNTIME_VERSION=${{ inputs.release_tag != '' && inputs.release_tag || github.ref_name }}
+
+  # The bootloader is versioned independently of the runtime (bootloader/VERSION).
+  # Tying it to every runtime tag would publish a long run of byte-identical
+  # images and make "which bootloader is on this device" a meaningless question.
+  #
+  # So a runtime release does NOT imply a bootloader release. This job reads
+  # bootloader/VERSION, and if that tag is already in the registry it publishes
+  # nothing: the runtime ships, the bootloader stays where it is. Bumping
+  # bootloader/VERSION is the only thing that produces a new bootloader image.
+  bootloader:
+    runs-on: ubuntu-latest
+    # Runs on release tags AND branch pushes: it is a seconds-long
+    # cross-compile, and the existence check below makes a run with an
+    # unchanged version free.
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Login to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ secrets.GHCR_USERNAME }}
+          password: ${{ secrets.GHCR_TOKEN }}
+
+      - name: Decide what needs publishing
+        id: plan
+        run: |
+          set -euo pipefail
+          image=ghcr.io/autonomy-logic/openplc-runtime-bootloader
+          version="$(tr -d '[:space:]' < bootloader/VERSION)"
+
+          if [ -z "$version" ]; then
+            echo "::error::bootloader/VERSION is empty"
+            exit 1
+          fi
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+          echo "image=$image" >> "$GITHUB_OUTPUT"
+
+          # A published version is immutable. Rebuilding one would replace a
+          # digest that devices in the field have already installed, with no
+          # version change to show for it -- so an existing tag is left alone
+          # even when the source has drifted.
+          if docker manifest inspect "$image:$version" >/dev/null 2>&1; then
+            exists=true
+          else
+            exists=false
+          fi
+          echo "exists=$exists" >> "$GITHUB_OUTPUT"
+
+          # `latest` is what a fresh install pulls, so it only ever moves for a
+          # stable version from a release tag or main. A development push can
+          # publish its own version for testing, but must not become the
+          # default every new device gets.
+          case "${GITHUB_REF}" in
+            refs/tags/v*|refs/heads/main) releasable=true ;;
+            *) releasable=false ;;
+          esac
+          case "$version" in
+            *-rc*|*-beta*|*-alpha*|*-dev*) releasable=false ;;
+          esac
+          echo "releasable=$releasable" >> "$GITHUB_OUTPUT"
+
+          if [ "$exists" = false ]; then
+            echo "build=true" >> "$GITHUB_OUTPUT"
+            echo "Publishing bootloader $version (not yet in the registry)."
+          else
+            echo "build=false" >> "$GITHUB_OUTPUT"
+            echo "Bootloader $version is already published; nothing to build."
+          fi
+
+      - name: Set up Docker Buildx
+        if: steps.plan.outputs.build == 'true'
+        uses: docker/setup-buildx-action@v3
+
+      # No QEMU step, unlike the runtime build: the bootloader is pure Go and
+      # cross-compiles from the native runner for every target, which takes
+      # seconds instead of the many minutes emulation costs.
+      - name: Build and Push Bootloader
+        if: steps.plan.outputs.build == 'true'
+        uses: docker/build-push-action@v6
+        with:
+          context: ./bootloader
+          push: true
+          platforms: ${{ inputs.platforms || 'linux/amd64,linux/arm64,linux/arm/v7' }}
+          build-args: |
+            BOOTLOADER_VERSION=${{ steps.plan.outputs.version }}
+          # `latest` only when this build is releasable; a development push
+          # publishes its own version and nothing else.
+          tags: ${{ steps.plan.outputs.releasable == 'true' && format('{0}:{1},{0}:latest', steps.plan.outputs.image, steps.plan.outputs.version) || format('{0}:{1}', steps.plan.outputs.image, steps.plan.outputs.version) }}
+
+      # The version was already published, but this is a release and `latest`
+      # may still be behind it -- a bootloader bumped on development and only
+      # later merged to main lands here. Repointing a tag is a registry-side
+      # manifest copy, not a rebuild, so the digest devices already hold stays
+      # exactly as it was.
+      - name: Point latest at the published bootloader
+        if: steps.plan.outputs.build == 'false' && steps.plan.outputs.releasable == 'true'
+        run: |
+          set -euo pipefail
+          image='${{ steps.plan.outputs.image }}'
+          version='${{ steps.plan.outputs.version }}'
+
+          current="$(docker manifest inspect "$image:latest" 2>/dev/null | sha256sum | cut -d' ' -f1 || true)"
+          target="$(docker manifest inspect "$image:$version" | sha256sum | cut -d' ' -f1)"
+          if [ "$current" = "$target" ]; then
+            echo "latest already points at $version."
+            exit 0
+          fi
+          echo "Moving latest to $version."
+          docker buildx imagetools create --tag "$image:latest" "$image:$version"
+
+      - name: Summary
+        run: |
+          {
+            echo "### Bootloader"
+            echo
+            echo "- version: \`${{ steps.plan.outputs.version }}\`"
+            if [ '${{ steps.plan.outputs.build }}' = 'true' ]; then
+              echo "- published a new image"
+            else
+              echo "- already published; no rebuild"
+            fi
+            echo "- latest updated: ${{ steps.plan.outputs.releasable }}"
+          } >> "$GITHUB_STEP_SUMMARY"

.github/workflows/tests.yml

@@ -0,0 +1,138 @@
+name: Tests
+
+# Nothing in this repository used to run on a pull request: docker.yml fires on
+# tag and branch pushes, windows-installer.yml on tags. Every "tests pass" in a
+# review was therefore a claim about somebody's laptop, and a bootloader change
+# without a VERSION bump got no automated testing at all -- the only `go test`
+# was inside bootloader/Dockerfile, which only builds when the version is new.
+on:
+  pull_request:
+  push:
+    branches:
+      - development
+      - main
+  workflow_dispatch:
+
+# A new push supersedes an in-flight run for the same ref.
+concurrency:
+  group: tests-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  bootloader:
+    name: Bootloader (Go)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: bootloader/go.mod
+          cache-dependency-path: bootloader/go.sum
+
+      - name: gofmt
+        working-directory: bootloader
+        run: |
+          unformatted="$(gofmt -l .)"
+          if [ -n "$unformatted" ]; then
+            echo "::error::gofmt would change these files:"
+            echo "$unformatted"
+            exit 1
+          fi
+
+      - name: go vet
+        working-directory: bootloader
+        run: go vet ./...
+
+      # -race because the bugs this package is prone to are concurrency ones:
+      # the spec was being written by the updater while the API read it.
+      - name: go test -race
+        working-directory: bootloader
+        run: go test -race -count=1 ./...
+
+  webserver:
+    name: Webserver (pytest)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install test dependencies
+        run: |
+          python -m pip install --upgrade pip
+          if [ -f requirements-dev.txt ]; then pip install -r requirements-dev.txt; fi
+          if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+          pip install -e .
+          # Every plugin's requirements, not just one.
+          #
+          # The plugin suites import their driver modules at collection time --
+          # pymodbus, asyncua -- so a missing dependency is a COLLECTION error
+          # that takes the whole run down rather than skipping those files.
+          # scripts/run-pytest.sh installs only modbus_master's, which is why
+          # it fails the same way when run by hand.
+          for req in core/src/drivers/plugins/python/*/requirements.txt; do
+            echo "Installing $req"
+            pip install -r "$req"
+          done
+          pip install pytest pytest-asyncio
+
+      # The plugin suites are excluded, and that is a statement about them
+      # rather than about this gate.
+      #
+      # They are red on `development` today: 48 failures and 10 collection
+      # errors across tests/pytest/plugins, modbus_master and modbus_slave,
+      # reproducible on a clean checkout of the base branch. They expect the
+      # per-plugin virtualenvs that install.sh builds, and in some cases a
+      # running OPC-UA server. Gating on them would mean a check that can
+      # never pass, which is a check everyone learns to ignore.
+      #
+      # What remains is 147 tests that do pass, covering the REST API,
+      # compile pipeline and webserver behaviour this repository's own changes
+      # touch. Repairing the plugin suites is real work and deserves its own
+      # ticket; when it is done, delete these three lines.
+      - name: pytest
+        run: |
+          pytest tests/pytest -q \
+            --ignore=tests/pytest/plugins \
+            --ignore=tests/pytest/modbus_master \
+            --ignore=tests/pytest/modbus_slave
+
+  shell:
+    name: Installer scripts
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: shellcheck
+        run: |
+          sudo apt-get update -qq && sudo apt-get install -y -qq shellcheck
+          shellcheck -S warning install.sh scripts/install-docker.sh \
+            windows/provision-msys2.sh tests/integration/harness.sh
+
+      # The Windows installer ships a compiled runtime inside an MSYS2 tree, so
+      # its callers must ask install.sh for the source build. install.sh does
+      # force native on MSYS2, but relying on that made a change to its
+      # platform detection able to break the Windows build from another file.
+      - name: The Windows build asks for a native install
+        run: |
+          set -euo pipefail
+          fail=0
+          for f in .github/workflows/windows-installer.yml windows/provision-msys2.sh; do
+            if grep -qE '(^|[^-])\./install\.sh[[:space:]]*$' "$f"; then
+              echo "::error file=$f::calls ./install.sh without --native"
+              fail=1
+            fi
+          done
+          # The image builds are the same story: there is no engine to install
+          # inside a build layer.
+          for f in Dockerfile Dockerfile.dev; do
+            if ! grep -q 'install\.sh --native' "$f"; then
+              echo "::error file=$f::must RUN ./install.sh --native"
+              fail=1
+            fi
+          done
+          [ "$fail" -eq 0 ] || exit 1
+          echo "All installer callers ask for the build they need."

.github/workflows/windows-installer.yml

@@ -55,11 +55,37 @@ jobs:
           echo "Installing OpenPLC Runtime via install.sh"
           echo "=========================================="
 
-          # Run the install script which handles all dependencies and build
-          ./install.sh
+          # --native explicitly, even though install.sh forces it on MSYS2 anyway.
+          # The Windows installer ships a built runtime inside an MSYS2 tree;
+          # the default path installs Docker and compiles nothing, which would
+          # produce a payload with no runtime in it. Relying on the script's own
+          # platform detection means a change to that detection silently breaks
+          # this build, so the intent is stated here where it is needed.
+          ./install.sh --native
 
           echo "Installation complete!"
 
+      # The payload is assembled by copying whatever is on disk, with no idea
+      # what produced it. This is the check that a native build actually
+      # happened: venvs/runtime is created only by install.sh's source path,
+      # never by the container one.
+      - name: Verify the native install produced its artifacts
+        shell: msys2 {0}
+        run: |
+          missing=0
+          for path in venvs/runtime webserver/app.py; do
+            if [ ! -e "$path" ]; then
+              echo "::error::$path is missing -- install.sh did not complete a native install"
+              missing=1
+            fi
+          done
+          if [ ! -x venvs/runtime/bin/python3 ] && [ ! -x venvs/runtime/Scripts/python.exe ]; then
+            echo "::error::the runtime virtualenv has no interpreter"
+            missing=1
+          fi
+          [ "$missing" -eq 0 ] || exit 1
+          echo "Native install verified."
+
       - name: Prepare installer payload
         shell: pwsh
         run: |

Dockerfile

@@ -22,13 +22,37 @@ RUN mkdir -p /var/run/runtime && \
 RUN rm -rf build/ venvs/ .venv/ 2>/dev/null || true
 
 # Run installation script
-RUN ./install.sh
+# --native, because install.sh now defaults to installing Docker and
+# compiling nothing -- and there is no engine to install inside a build
+# layer. Without this the image build fails at the installer's curl check.
+RUN ./install.sh --native
 
 # Clean up apt cache to reduce image size (Docker-specific optimization)
 RUN rm -rf /var/lib/apt/lists/*
 
 # Expose webserver port
 EXPOSE 8443
 
+# Liveness for the bootloader (RTOP-283), which reads Docker's health state off
+# the events stream instead of polling the runtime itself.
+#
+# /api/version, NOT /api/ping: ping sits behind @jwt_required(), so a
+# healthcheck against it always gets a 401 and `curl -f` always fails. (The
+# example in docs/DOCKER.md had exactly that bug.)
+#
+# Scope is deliberately "the webserver answers" and nothing more. Whether
+# plc_main is running, whether a program is loaded, and whether that program
+# is in ERROR are the webserver's own business -- runtimemanager._monitor()
+# already restarts plc_main and drops it into safe mode on rapid crashes. If
+# this probe cared about PLC state, a user uploading broken logic would make
+# the container unhealthy and trigger a runtime recovery, turning a program
+# bug into a device outage.
+#
+# start-period is generous because a cold start compiles nothing but does load
+# plugin venvs, and a runtime marked unhealthy before it has finished booting
+# would be restarted for no reason.
+HEALTHCHECK --interval=30s --timeout=10s --start-period=90s --retries=3 \
+    CMD curl -kfsS https://127.0.0.1:8443/api/version >/dev/null || exit 1
+
 # Default execution - Start OpenPLC Runtime
 CMD ["bash", "./start_openplc.sh"]

Dockerfile.dev

@@ -12,7 +12,10 @@ RUN mkdir -p /var/run/runtime
 # Clean any existing build artifacts to ensure clean Docker build
 RUN rm -rf build/ venvs/ 2>/dev/null || true
 RUN chmod +x install.sh scripts/* start_openplc.sh
-RUN ./install.sh
+# --native, because install.sh now defaults to installing Docker and
+# compiling nothing -- and there is no engine to install inside a build
+# layer. Without this the dev image build fails at the installer's curl check.
+RUN ./install.sh --native
 
 # Clean up apt cache to reduce image size (Docker-specific optimization)
 RUN rm -rf /var/lib/apt/lists/*