Merge pull request #3186 from balena-io/alanb128-balenalib-cleanup7

Update dockerfile.template section of develop/dockerfile/

Author: flowzone-app[bot]

.cspell/balena-words.txt

@@ -6,6 +6,7 @@ balena-build
 balena-builder
 balenacli
 balenahup
+balenalabs
 balenalib
 balenista
 balenistas

.cspell/computer-terms.txt

@@ -414,6 +414,7 @@ toidentifier
 tooltipped
 topo
 TOTP
+trixie
 tuneables
 typer
 tzdata
@@ -461,4 +462,4 @@ yallist
 yocto
 Yocto
 zenbook
-zerotier
+zerotier

pages/learn/develop/dockerfile.md

@@ -67,11 +67,23 @@ __Note:__ You *don't* need to worry about ignoring `.git` as the builders alread
 
 ## Dockerfile templates
 
-One of the goals of {{ $names.company.lower }} is code portability and ease of use, so you can easily manage and deploy a whole fleet of different devices. This is why Docker containers were such a natural choice. However, there are cases where Dockerfiles fall short and can't easily target multiple different device architectures.
+Dockerfile templates are a balena-specific feature that allow our builders to substitute a value for one of the following variables at build time:
 
-To allow our builders to build containers for multiple architectures from one code repository, we implemented simple Dockerfile templates.
+{{> "deployment/build-variables" }}
+
+The original purpose of these templates was to allow our builders to build containers for multiple architectures from one code repository when using the deprecated balenalib base images. For new projects, we recommend using standard Dockerfiles and either specifying the architecture in your FROM line, or utilizing base images that are published with the [multi-platform feature](https://docs.docker.com/build/building/multi-platform/). For example:
+
+`FROM bh.cr/balenalabs/browser-aarch64`
+
+Here, we are pulling an ARMv8 (aarch64) architecture-specific container image. This image can only be used for fleets with devices of that architecture. 
+
+`FROM debian:trixie`
+
+This Debian Official Docker image is a multi-arch image instead. Upon build time, the balena builders would pull the correct architecture of the image based on the default device type of your fleet. This reduces complexity and provides a similar feature set to Dockerfile templates in the past.
 
-It is now possible to define a `Dockerfile.template` file that looks like this:
+It is possible to have different device types in the same fleet, as long as they have the same or compatible architectures. You need to ensure that your packages and modules are also available in that target architecture, otherwise, your application might throw errors or fail during runtime.
+
+If you are still using balenalib base images for an existing project, you can use dockerfile templates as described below:
 
 ```Dockerfile
 FROM {{ $names.base_images.lib }}/%%{{ $names.company.allCaps }}_MACHINE_NAME%%-node
@@ -83,22 +95,16 @@ COPY src/ /usr/src/app
 CMD ["node", "/usr/src/app/main.js"]
 ```
 
-This template will build and deploy a Node.js project for any of the devices supported by {{ $names.company.lower }}, regardless of whether the device architecture is [ARM][ARM-link] or [x86][x86-link].
-In this example, you can see the build variable `%%{{ $names.company.allCaps }}_MACHINE_NAME%%`. This will be replaced by the machine name (i.e.: `raspberry-pi`) at build time. See below for a list of machine names.
-
-The machine name is inferred from the device type of the fleet you are deploying on. So if you have a NanoPi Neo Air fleet, the machine name will be `nanopi-neo-air` and an `armv7hf` architecture base image will be built.
-
-__Note:__ You need to ensure that your dependencies and Node.js modules are also multi-architecture, otherwise you will have a bad time.
+This `dockerfile.template` file will build and deploy a Node.js project for any of the devices supported by {{ $names.company.lower }}, regardless of device architecture, whether is [ARM][ARM-link] or [x86][x86-link].
 
-Currently our builder supports the following build variables:
+In this example, the build variable `%%{{ $names.company.allCaps }}_MACHINE_NAME%%`. This will be replaced by the machine name (i.e.: `raspberry-pi`) at build time. Refer to [supported machine names and architectures][supported-devices].
 
-{{> "deployment/build-variables" }}
+The machine name is inferred from the device type of the fleet you are deploying on. So if you have a NanoPi Neo Air fleet, the machine name will be `nanopi-neo-air` and an `armv7hf` architecture base image will be built.
 
 __Note:__ If your fleet contains devices of different types, the `%%{{ $names.company.allCaps }}_MACHINE_NAME%%` build variable **will not** evaluate correctly for all devices. Your fleet services are built once for all devices, and the `%%{{ $names.company.allCaps }}_MACHINE_NAME%%` variable will pull from the device type associated with the fleet, rather than the target device. In this scenario, you can use `%%{{ $names.company.allCaps }}_ARCH%%` to pull a base image that matches the shared architecture of the devices in your fleet.
 
 If you want to see an example of build variables in action, have a look at this [basic openssh example]({{ $links.githubPlayground }}/balena-openssh).
 
-Here are the [supported machine names and architectures][supported-devices].
 
 ## Multiple Dockerfiles
 
@@ -214,4 +220,4 @@ The {{ $names.company.lower }} Supervisor requires that the directory `/tmp/bale
 [aptitude]:https://wiki.debian.org/Aptitude
 
 [services-masterclass]:/learn/more/masterclasses/services-masterclass/
-[update-locks]:/learn/deploy/release-strategy/update-locking/
+[update-locks]:/learn/deploy/release-strategy/update-locking/