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"

Dockerfile

@@ -30,5 +30,26 @@ 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"]

README.md

@@ -35,7 +35,35 @@ The runtime will start and listen on port 8443 for connections from the OpenPLC
 
 ### Linux Installation
 
-For native Linux installation:
+#### Install (recommended)
+
+```bash
+curl -fsSL https://runtime.getedge.me | sudo bash
+```
+
+No checkout, no build toolchain, no dependencies to install first. The script
+installs Docker if it is missing, then starts the runtime and a small
+bootloader beside it. The bootloader is what lets the OpenPLC Editor change
+the runtime version later, without SSH.
+
+If the device already runs an OpenPLC from systemd, the installer stops and
+disables it first -- the two would otherwise fight over port 8443. Its data in
+`/var/lib/openplc-runtime` is reused, so users, credentials and the stored
+project carry over.
+
+To remove it again:
+
+```bash
+curl -fsSL https://runtime.getedge.me | sudo bash -s -- --uninstall --yes
+```
+
+That removes the containers and images, puts back any systemd runtime it
+displaced, and leaves `/var/lib/openplc-runtime` alone. Add `--purge` to
+delete that too. Docker itself is left installed.
+
+#### Install from source
+
+For a native build -- MSYS2, or a target that cannot run containers:
 
 ```bash
 # Clone repository
@@ -44,12 +72,16 @@ cd openplc-runtime
 git checkout development
 
 # Install dependencies and compile
-sudo ./install.sh
+sudo ./install.sh --native
 
 # Start the runtime
 sudo ./start_openplc.sh
 ```
 
+`--native` is required here: `sudo ./install.sh` on its own takes the
+container path above. The source build needs the repository on disk, which is
+why it is not reachable from the one-liner.
+
 The runtime will start and listen on port 8443. Connect to it from the OpenPLC Editor desktop application by configuring the runtime IP address and logging in from the Editor.
 
 **Supported Distributions:** Any distribution using apt, dnf, yum, pacman, zypper, or apk (Ubuntu, Debian, Fedora, CentOS, RHEL, Arch, openSUSE, Alpine, etc.)

bootloader/Dockerfile

@@ -0,0 +1,64 @@
+# syntax=docker/dockerfile:1
+
+# Bootloader image: a single static binary on scratch.
+#
+# Cross-compiled rather than emulated. Go targets every architecture we ship
+# from one native builder, so buildx needs no QEMU here -- BUILDPLATFORM pins
+# the build stage to the host and TARGETOS/TARGETARCH pick the output. That is
+# the difference between seconds and the many minutes the runtime image spends
+# under emulation.
+#
+# scratch, not alpine: this is the component that has to work when the runtime
+# will not start, and every byte in the image is a byte that could stop it
+# starting. There is no shell to debug with, which is the intended trade -- the
+# bootloader's job is to report over HTTP, not to be poked at over exec.
+FROM --platform=$BUILDPLATFORM golang:1.25-alpine AS build
+
+ARG TARGETOS
+ARG TARGETARCH
+# Bootloader version, independent of the runtime's. It changes rarely, so tying it
+# to every runtime release would produce a long run of identical images.
+ARG BOOTLOADER_VERSION=dev
+
+WORKDIR /src
+
+# go.mod first so the dependency layer survives source-only changes. There are
+# no third-party dependencies today, which keeps this honest rather than
+# theatrical: `go mod download` is a no-op and the layer is a cache anchor.
+COPY go.mod ./
+RUN go mod download
+
+COPY . .
+
+# CGO off so the result is genuinely static and runs on scratch.
+# -trimpath and -s -w keep the binary small and reproducible.
+RUN CGO_ENABLED=0 GOOS=${TARGETOS} GOARCH=${TARGETARCH} \
+    go build \
+    -trimpath \
+    -ldflags="-s -w -X main.version=${BOOTLOADER_VERSION}" \
+    -o /out/openplc-bootloader .
+
+# Fail the build rather than ship an untested bootloader. Tests run on the build
+# platform, which is where they are meaningful -- the logic under test is a
+# state machine, not anything architecture-specific.
+RUN CGO_ENABLED=0 go test ./...
+
+FROM scratch
+
+ARG BOOTLOADER_VERSION=dev
+LABEL org.opencontainers.image.title="OpenPLC Runtime Bootloader" \
+      org.opencontainers.image.description="Bootloader and update manager for a local OpenPLC runtime" \
+      org.opencontainers.image.source="https://github.com/Autonomy-Logic/openplc-runtime" \
+      org.opencontainers.image.version="${BOOTLOADER_VERSION}"
+
+# CA roots for any future outbound HTTPS. Nothing needs them today -- image
+# pulls go through the Docker daemon, which has its own -- but a missing root
+# store fails in a way that is genuinely hard to diagnose from a scratch image.
+COPY --from=build /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/ca-certificates.crt
+
+COPY --from=build /out/openplc-bootloader /openplc-bootloader
+
+# Control API. 8445 keeps to the odd numbers alongside the runtime's 8443.
+EXPOSE 8445
+
+ENTRYPOINT ["/openplc-bootloader"]

bootloader/VERSION

@@ -0,0 +1 @@
+bootloader-v1.0.0

bootloader/go.mod

@@ -0,0 +1,31 @@
+// The bootloader keeps its dependencies to the minimum the job actually needs.
+// It is the component that recovers a device when the runtime will not start,
+// so every dependency is a way for that recovery to fail: the Docker Engine
+// API is plain HTTP over a unix socket, JWT is an HMAC over two base64
+// segments, and PBKDF2 is twenty lines of RFC 8018 -- all of which net/http
+// and crypto/* already cover -- PBKDF2 is crypto/pbkdf2 as of Go 1.24.
+//
+// The one exception is modernc.org/sqlite. Authenticating a caller while the
+// runtime is DOWN means reading the runtime's own users table, and cold
+// recovery after a reboot is exactly when there is no runtime to ask. A
+// second credential store in the bootloader would have avoided the dependency at
+// the cost of another thing that can be forgotten when an account is revoked,
+// which is the worse trade. Pure Go, so it still cross-compiles with CGO off
+// and still runs on scratch.
+module github.com/Autonomy-Logic/openplc-runtime/bootloader
+
+go 1.25.0
+
+require modernc.org/sqlite v1.58.0
+
+require (
+	github.com/dustin/go-humanize v1.0.1 // indirect
+	github.com/google/uuid v1.6.0 // indirect
+	github.com/mattn/go-isatty v0.0.24 // indirect
+	github.com/ncruces/go-strftime v1.0.0 // indirect
+	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
+	golang.org/x/sys v0.47.0 // indirect
+	modernc.org/libc v1.75.6 // indirect
+	modernc.org/mathutil v1.7.1 // indirect
+	modernc.org/memory v1.12.1 // indirect
+)

bootloader/go.sum

@@ -0,0 +1,50 @@
+github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
+github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
+github.com/google/pprof v0.0.0-20260802141513-ef3492d7dac3 h1:LMLX+LgTNWpfvCBdFebv6EsYotImrt/Ppc5cXIriCSo=
+github.com/google/pprof v0.0.0-20260802141513-ef3492d7dac3/go.mod h1:jl5iWTm0/hd5PjEYEOuwAJ57L/CibdZfrqZ5XA5GrCk=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/hashicorp/golang-lru/v2 v2.0.7 h1:a+bsQ5rvGLjzHuww6tVxozPZFVghXaHOwFs4luLUK2k=
+github.com/hashicorp/golang-lru/v2 v2.0.7/go.mod h1:QeFd9opnmA6QUJc5vARoKUSoFhyfM2/ZepoAG6RGpeM=
+github.com/mattn/go-isatty v0.0.24 h1:tGZZoVgT/KiqK1c8ocVLeDS8BSWMRd47J3Lbz7vsReI=
+github.com/mattn/go-isatty v0.0.24/go.mod h1:nMCL3Zebbrt45jsMDgnfIwz6ydEQApk5oEI3HqDio6A=
+github.com/ncruces/go-strftime v1.0.0 h1:HMFp8mLCTPp341M/ZnA4qaf7ZlsbTc+miZjCLOFAw7w=
+github.com/ncruces/go-strftime v1.0.0/go.mod h1:Fwc5htZGVVkseilnfgOVb9mKy6w1naJmn9CehxcKcls=
+github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94icq4NjY3clb7Lk8O1qJ8BdBEF8z0ibU0rE=
+github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo=
+golang.org/x/mod v0.38.0 h1:MECBjubtXD7yj4HrhIUcywNaGeNVUdfVnxmPajOk4yk=
+golang.org/x/mod v0.38.0/go.mod h1:V6Xz0pq8TQ3dGqVQ1FVHuelZpAL0uNhSkk9ogYP3c40=
+golang.org/x/sync v0.22.0 h1:SZjpbeLmrCk4xhRSZFNZW5gFUeCeFgjekvI/+gfScek=
+golang.org/x/sync v0.22.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
+golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs=
+golang.org/x/sys v0.47.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/tools v0.48.0 h1:3+hClM1aLL5mjMKm5ovokw9epgRXPuu2tILgismM6RE=
+golang.org/x/tools v0.48.0/go.mod h1:08xX0orndb/F7jJxGDicx061tyd5pcMto75YMAXr6lk=
+modernc.org/cc/v4 v4.29.2 h1:h6+9ciCnPKutf4I03CvheAvDLX7+IHlqR6Iy6J+cgd8=
+modernc.org/cc/v4 v4.29.2/go.mod h1:OnovgIhbbMXMu1aISnJ0wvVD1KnW+cAUJkIrAWh+kVI=
+modernc.org/ccgo/v4 v4.35.0 h1:F+TUsmw09QxLzmi3aeYYGxjAXarmZaKgj3mKQHNaA8w=
+modernc.org/ccgo/v4 v4.35.0/go.mod h1:qrVGs9S3Sr2Ztcg9ve+kTAYMp5a3YvWjo+SoN06kJ5I=
+modernc.org/fileutil v1.4.0 h1:j6ZzNTftVS054gi281TyLjHPp6CPHr2KCxEXjEbD6SM=
+modernc.org/fileutil v1.4.0/go.mod h1:EqdKFDxiByqxLk8ozOxObDSfcVOv/54xDs/DUHdvCUU=
+modernc.org/gc/v2 v2.6.5 h1:nyqdV8q46KvTpZlsw66kWqwXRHdjIlJOhG6kxiV/9xI=
+modernc.org/gc/v2 v2.6.5/go.mod h1:YgIahr1ypgfe7chRuJi2gD7DBQiKSLMPgBQe9oIiito=
+modernc.org/gc/v3 v3.1.5 h1:21ldfPfRYE31Tb7B3mwAK8gy1AxP4+dKjrOQPfqakoc=
+modernc.org/gc/v3 v3.1.5/go.mod h1:HFK/6AGESC7Ex+EZJhJ2Gni6cTaYpSMmU/cT9RmlfYY=
+modernc.org/goabi0 v0.2.0 h1:HvEowk7LxcPd0eq6mVOAEMai46V+i7Jrj13t4AzuNks=
+modernc.org/goabi0 v0.2.0/go.mod h1:CEFRnnJhKvWT1c1JTI3Avm+tgOWbkOu5oPA8eH8LnMI=
+modernc.org/libc v1.75.6 h1:yKk8qo+Di4gkmvRboK8ocCqH22FiUCR6jRy2OwtCRus=
+modernc.org/libc v1.75.6/go.mod h1:bO5o2ztHxBb2rjz0PgdHN0sSMw57CgxGFLZ3Qd/QpVQ=
+modernc.org/mathutil v1.7.1 h1:GCZVGXdaN8gTqB1Mf/usp1Y/hSqgI2vAGGP4jZMCxOU=
+modernc.org/mathutil v1.7.1/go.mod h1:4p5IwJITfppl0G4sUEDtCr4DthTaT47/N3aT6MhfgJg=
+modernc.org/memory v1.12.1 h1:nFMiWrpStgZczNl6XI9GnIk/rWhYIyHGUaR04pGbp9g=
+modernc.org/memory v1.12.1/go.mod h1:/JP4VbVC+K5sU2wZi9bHoq2MAkCnrt2r98UGeSK7Mjw=
+modernc.org/opt v0.2.0 h1:tGyef5ApycA7FSEOMraay9SaTk5zmbx7Tu+cJs4QKZg=
+modernc.org/opt v0.2.0/go.mod h1:03fq9lsNfvkYSfxrfUhZCWPk1lm4cq4N+Bh//bEtgns=
+modernc.org/sortutil v1.2.1 h1:+xyoGf15mM3NMlPDnFqrteY07klSFxLElE2PVuWIJ7w=
+modernc.org/sortutil v1.2.1/go.mod h1:7ZI3a3REbai7gzCLcotuw9AC4VZVpYMjDzETGsSMqJE=
+modernc.org/sqlite v1.58.0 h1:38u40/bwkfM7f0Myhosl+SEMltSDxnGdQf8o6Kjmys0=
+modernc.org/sqlite v1.58.0/go.mod h1:rsD2CckafgObKC4DhBlGBf+RiHxkc3hINGt1Xw32tVY=
+modernc.org/strutil v1.2.1 h1:UneZBkQA+DX2Rp35KcM69cSsNES9ly8mQWD71HKlOA0=
+modernc.org/strutil v1.2.1/go.mod h1:EHkiggD70koQxjVdSBM3JKM7k6L0FbGE5eymy9i3B9A=
+modernc.org/token v1.1.0 h1:Xl7Ap9dKaEs5kLoOQeQmPWevfnk/DM5qcLcYlA8ys6Y=
+modernc.org/token v1.1.0/go.mod h1:UGzOrNV1mAFSEB63lOFHIpNRUVMvYTc6yu1SMY/XTDM=