From 8b7c9c87065d25df1e3ee3848b5e3b793caeb284 Mon Sep 17 00:00:00 2001 From: Dennis Kuijs Date: Fri, 13 Nov 2026 16:24:16 +0100 Subject: [PATCH] Add Balena files --- .gitignore | 1 - balena/.gitignore | 2 + balena/Dockerfile | 8 +++ balena/README.md | 85 ++++++++++++++++++++++++++++++++ balena/copy_dockerfile_script.sh | 4 ++ balena/docker-compose.yml | 52 +++++++++++++++++++ balena/env | 11 +++++ balena/run_balena_build.sh | 2 + 8 files changed, 164 insertions(+), 1 deletion(-) create mode 100644 balena/.gitignore create mode 100644 balena/Dockerfile create mode 100644 balena/README.md create mode 100755 balena/copy_dockerfile_script.sh create mode 100755 balena/docker-compose.yml create mode 100644 balena/env create mode 100755 balena/run_balena_build.sh diff --git a/.gitignore b/.gitignore index 27718914c..b8777c9e0 100644 --- a/.gitignore +++ b/.gitignore @@ -48,7 +48,6 @@ local.properties *.ipa *.apk *.dab -*.sh *.iml *.ipr *.iws diff --git a/balena/.gitignore b/balena/.gitignore new file mode 100644 index 000000000..353b8a23b --- /dev/null +++ b/balena/.gitignore @@ -0,0 +1,2 @@ +deployment +manager-build diff --git a/balena/Dockerfile b/balena/Dockerfile new file mode 100644 index 000000000..6c4564651 --- /dev/null +++ b/balena/Dockerfile @@ -0,0 +1,8 @@ +FROM openremote/manager:1.34.0 + +RUN mkdir -p /deployment/manager/extensions + +ADD ./deployment/build/image /deployment + +EXPOSE 8080 +EXPOSE 1883 diff --git a/balena/README.md b/balena/README.md new file mode 100644 index 000000000..89ffeeecf --- /dev/null +++ b/balena/README.md @@ -0,0 +1,85 @@ +# Balena Integration, Documentation + +This README will give some basics of Balena and how to deploy an OpenRemote image to a Balena fleet. + +# What is Balena / Definitions + +Balena is the totality of the product. Look at [balena.io](https://balena.io). + +- BalenaOS is the Operating System which runs on edge devices (Raspberry Pis, Intel NUCs, etc.). BalenaOS is able to + run Docker containers, and allows management by OpenBalena. +- OpenBalena is the open-source backend software that can manage fleets (groups) of devices. It can push new versions of + images to devices, manage those devices (power management, resource management, environment variables, etc) +- BalenaCloud is (the company) Balena's SaaS product, which uses OpenBalena for their core part of the backend, like the + device API, the image registry, etc. They use the "open-source" openBalena backend to then build their SaaS tools on top + of that. + +# OpenRemote and BalenaOS + +> [!CAUTION] +> Issues with bootup could potentially corrupt migrations being performed from Keycloak or the manager, leading to +> data loss. Please be aware of actions and perform backups. + +OpenRemote is a multi-container platform that normally requires multiple containers to start in the correct sequence to +properly start its services (Deployment, Postgres, Keycloak, Manager, Proxy). + +# Gateway authentication + +This configuration is for private edge gateways accessed locally or through OpenRemote reverse tunnels. +Keycloak uses `KC_HOSTNAME_STRICT=false` with `KC_HOSTNAME` unset so URLs follow the incoming proxy headers. +Keep `KC_HOSTNAME` unset in Balena fleet, device, and service variables as well, rather than fixing it to `localhost`. + +The manager uses `OR_KEYCLOAK_DISABLE_ISSUER_VALIDATION=true` to support the changing URLs used by gateway tunnels. +For publicly exposed deployments, configure a fixed Keycloak hostname and keep issuer validation enabled. + +When updating an existing fleet, remove `KC_HOSTNAME` and the obsolete `KEYCLOAK_ISSUER_BASE_URI` variable from its +Balena configuration. The `balena/env` file contains example values and is not automatically loaded by Balena. + +# Required tooling + +I recommend going through the [balena CLI masterclass](https://docs.balena.io/learn/more/masterclasses/cli-masterclass/). + +To manually manage the devices using the terminal, install `balena-cli` to your machine. You can use the CLI to +perform the same actions as with BalenaCloud. Specifically, you can `push` a new release to a device. This is what +we will use to push new versions. Make sure to `balena login` before proceeding. + +# Development and Deployment + +Balena follows a git-like deployment lifecycle, with some more features being sprinkled in over the years. Specifically, +devices or the entire fleet can track the latest release or pin to a specific release, which can be changed by the +administrator from the CLI/from the BalenaCloud dashboard. + +To create a new release, you can push this directory to the fleet using the included `run_balena_build.sh`. + +To push: + +- `./gradlew clean installDist` +- `cd ./balena` +- `./run_balena_build.sh` + +This will rebuild OpenRemote using `clean installDist`, copy the required built Dockerfiles and directories to this +directory, and send all files required to Balena for their systems to build the image and create a release. This might +seem stupid, but Balena's build process requires all files required to be in one directory for it to be pushed. More +of such "intricacies" are outlined in the below section. + +It just seemed easier to have this directory for all the scripts and kind-of automate the process instead of doing it +manually every single time. Also, `clean installDist` is needed to make sure that every file/Dockerfile is rebuilt +before pushed to Balena, so make sure you run it before pushing to Balena. + +# Quirks you should be aware of + +In general, Balena CLI/Balena API/BalenaCloud do things their own way. Some examples: + +- You cannot set a `docker-compose.yml` file to be used specifically for balena, it NEEDS to use`docker-compose.yml`. +- `balena push` **does not** build the image locally. All folders/files referenced in the Dockerfiles/docker-compose + files are uploaded to their own builder platform and are built on their premises. This is done to allow building + the images in all of the different architectures that you might use the release in. +- You cannot use environment variables in the way you usually do. Using default/error values in environment variables + do not work. +- For the above point, the concept of environment variables in a `docker-compose.yml` file doesn't quite exist; + environment variables in Balena environments are set using the CLI or the dashboard, and there are fleet-level and + device-level variables. You would set an environment variable in the docker-compose file specifically when it's an + environment variable that applies for ALL devices that may run this in BalenaOS (or for debugging locally of course). + All environment variables of a device/fleet are included in ALL services. So `OR_MAIN_THREAD_WAIT_MS` WILL end up on + the proxy container, and Keycloak, and the manager, etc. + A script to allow for environment variables of a file to be uploaded to a fleet will be added later on. diff --git a/balena/copy_dockerfile_script.sh b/balena/copy_dockerfile_script.sh new file mode 100755 index 000000000..88fc12837 --- /dev/null +++ b/balena/copy_dockerfile_script.sh @@ -0,0 +1,4 @@ +rm -rf ./manager-build +rm -rf ./deployment +cp -r ../manager/build/ ./manager-build +cp -r ../deployment ./deployment diff --git a/balena/docker-compose.yml b/balena/docker-compose.yml new file mode 100755 index 000000000..0693c194b --- /dev/null +++ b/balena/docker-compose.yml @@ -0,0 +1,52 @@ +# Balena CLI requires this version, see: https://github.com/balena-io/balena-cli/issues/2314 +version: "2.4" + +volumes: + proxy-data: + postgresql-data: + manager-data: + +services: + proxy: + image: openremote/proxy:latest + restart: always + depends_on: + - manager + ports: + - "80:80" + - "443:443" + - "8883:8883" + volumes: + - proxy-data:/deployment + + postgresql: + image: openremote/postgresql:latest-slim + restart: always + volumes: + - postgresql-data:/var/lib/postgresql/data + - manager-data:/storage + + keycloak: + image: openremote/keycloak:latest + restart: always + depends_on: + - postgresql + environment: + KC_HOSTNAME: + KC_HOSTNAME_STRICT: false + + manager: + image: openremote-manager + build: + context: . + restart: always + depends_on: + - keycloak + - postgresql + volumes: + - manager-data:/storage + environment: + OR_WEBSERVER_ALLOWED_ORIGINS: "*" + OR_GATEWAY_TUNNEL_SSH_KEY_FILE: /deployment/sish/client/client + OR_GATEWAY_TUNNEL_AUTO_CLOSE_MINUTES: 20 + OR_KEYCLOAK_DISABLE_ISSUER_VALIDATION: true diff --git a/balena/env b/balena/env new file mode 100644 index 000000000..9311e4d3f --- /dev/null +++ b/balena/env @@ -0,0 +1,11 @@ +KC_HOSTNAME= +KC_HOSTNAME_STRICT=false +OR_HOSTNAME=localhost +OR_ADDITIONAL_HOSTNAMES=localhost +OR_GATEWAY_TUNNEL_SSH_KEY_FILE=/deployment/sish/client/client +OR_GATEWAY_TUNNEL_AUTO_CLOSE_MINUTES=20 +OR_KEYCLOAK_DISABLE_ISSUER_VALIDATION=true +OR_SETUP_RUN_ON_RESTART=false +OR_WEBSERVER_ALLOWED_ORIGINS=* +PROXY_LOGLEVEL=debug +WEBSERVER_LISTEN_HOST=0.0.0.0 diff --git a/balena/run_balena_build.sh b/balena/run_balena_build.sh new file mode 100755 index 000000000..ed3b398ea --- /dev/null +++ b/balena/run_balena_build.sh @@ -0,0 +1,2 @@ + ./copy_dockerfile_script.sh +balena push openremote_internal/openremote