Change the base image or pin an architecture
Move a Borago Board project container to Ubuntu 26.04, or pin it to x64 for a dependency that has no Apple silicon build, and rebuild it safely.
Every Borago Board project runs in a container the app builds from a generated Dockerfile. Two settings decide what that image is. The base image is the Linux system it starts from. The CPU architecture decides which processor it is built for. This tutorial does two short jobs with them.
You will build
A project moved to a newer base image, and a project pinned to x64 so a dependency without an Apple silicon build can install.
You need
- The desktop app with a project whose container the app generates. The Containers tab shows Auto-generated under the container name. With Custom, you run the container yourself and neither setting applies.
- For the second job, an Apple silicon Mac with Docker Desktop.
Steps
1. Commit or copy out your work
Before either change, commit the project's code and send the commits to its remote repository, or confirm the project has a local folder on this computer.
What happens. Both changes rebuild the container. A project with no local folder keeps its code only inside the container, and a rebuild resets that code. Uncommitted changes and unpushed commits are then lost for good. A project with a local folder keeps its files on your disk and loses nothing.
2. Pick the new base image
Press Edit project and open the Containers tab. Open Base image and pick one of the three listed systems.
| Choice | Notes |
|---|---|
| Ubuntu 26.04 LTS | The default for new projects |
| Ubuntu 24.04 LTS | What every project created before the setting existed uses |
| Debian 13 (trixie) | The third tested choice |
What happens. The generated Dockerfile changes its starting image and keeps everything else. Existing projects are never moved on their own, so an older project stays on 24.04 until you choose. If you edited the Dockerfile by hand and it starts from one of the listed images, the picker rewrites that line too, visible in the Dockerfiles tab. If it starts from any other image, the picker is disabled and says the Dockerfile decides.
3. Save and rebuild
Press Save changes.
What happens. When the container is running, the app asks Rebuild the container?, because it is still on the old image. Rebuild now rebuilds it from scratch. Later keeps the old one, and the new image is used at the next start, restart or rebuild. When the code lives only in the container, the dialog adds a warning that uncommitted changes and unpushed commits are permanently lost, and the button turns red.
4. Pin the architecture
On the Mac, open the same Containers tab. Under Base image, open Container CPU architecture and pick x64 (Intel/AMD). Press Save changes.
What happens. The default follows the machine that runs the container, arm64 on an Apple silicon Mac and x64 on a PC. Force one only for a dependency published for a single architecture, such as an x64-only binary or a 32-bit package. The choice syncs with the project, so every machine builds it for x64. Under the control, the app warns that the container runs under emulation on this Mac. Emulated builds and tests are noticeably slower, and gVisor sandboxing is always off for an emulated container.
5. Rebuild the container
On the board, press Rebuild container in the project controls and confirm with Rebuild. The same lost-work warning appears here when the code lives only in the container.
What happens. Before every start, restart and rebuild, the app checks whether this machine can run the chosen architecture. Docker Desktop can emulate the other one, so the build goes ahead. The bell shows a notice that the project runs under CPU emulation. A repeat while it is unread is added to that notice rather than raised as a new one.
Check it worked
Open the terminal and run:
cat /etc/os-release
uname -mThe first names the base image you picked. After the pin, the second prints x86_64.
If the machine cannot emulate
On a Linux machine with no emulator registered, the app refuses the start before building anything. A red notice names the fix, a command to register the emulator or setting the architecture back to Default. The refusal saves a build that would run for minutes and then fail. To undo a pin, pick the Default option, which names this machine's architecture.
Where to go next
See Container management for what the container holds and Containers for the build details.
Related: Creating a project, Container management, Containers, Why Docker