linuxdeploy Build Helper Container

A docker container that aims to help build an AppImage on multiple architectures using linuxdeploy.

Latest version: v3-jammy

Available architectures

amd64
arm64

Usage

Make a docker sub-directory within your project and copy .env and docker-compose.yml to it. Add custom variables to suit your needs.

To build the AppImage:

docker-compose -f docker/docker-compose.yml run --rm build

This is meant to be run from the source root of your project. Using the command above, your current directory will be mounted in the container at /workspace.

You can see an example of an AppImage build script at rmw/packaging/appimage/pre-appimage.sh. Add the /path/to/script in your custom .env file.

When the container starts, 'root' changes the UID of user 'builder' (a user created during the build of the Dockerfile) to match the host user's. This allows builder to build your project and create the AppImage without root privileges (the resulting files will be owned by you).

The host UID/GID are auto-detected from the owner of the bind-mounted workspace (Docker preserves host ownership across bind mounts), so the typical invocation above needs no extra environment.

You can still pass HOSTUID and HOSTGID explicitly to override the auto-detection — useful when the workspace ownership doesn't match the invoking user, or in some CI matrices — by exporting them before running docker-compose:

export HOSTUID=$(id -u) HOSTGID=$(id -g)

You may use sudo in your script to install packages or do other things.

If you would like to look around the container, you can use

docker run -it --rm --entrypoint bash andy5995/linuxdeploy:v3-jammy

docker pull ghcr.io/andy5995/linuxdeploy-build-helper-container:v3-jammy

Locally

To build for other architectures, you may need to use qemu with docker. There may be other ways, but you can check out this document for starters. If you are set up to build on other architectures, edit the PLATFORM variable in docker-compose.yml, or export it when running docker-compose:

PLATFORM=linux/arm64 docker-compose -f docker/docker-compose.yml pull build

To pull the image for the corresponding architecture. Then run docker-compose by preceding it again with the PLATFORM variable:

PLATFORM=linux/arm64 docker-compose -f docker/docker-compose.yml run --rm build

Alternatively, you can export the variable:

export PLATFORM=linux/arm64

And then run the docker-compose commands without preceding them with the variable.

In a GitHub Runner

See test.yml

linuxdeploy Plugins

These plugins are installed in the container:

• linuxdeploy-plugin-gtk
• linuxdeploy-plugin-qt

Pinned toolchain

appimagetool is pinned to release 1.9.1, and the AppImage type2 runtime is pinned to release 20251108 — bundled into the image and verified by SHA-256. The bundled runtime is injected into appimagetool by default, so AppImage builds do not fetch the rolling continuous runtime at build time. To use a different runtime, pass appimagetool --runtime-file <path> (or set LDAI_RUNTIME_FILE when building through the linuxdeploy appimage plugin).

Note

The container runs Ubuntu 22.04 (Jammy Jellyfish). See this discussion for more details on why I chose that version of Ubuntu.

Some 'GITHUB_...' variables will not work inside the container.

Recent versions of cmake, meson, and ninja are installed to '/home/builder/.local/bin' which is the first path in PATH (installing them with apt will probably offer no benefit).

If you want to see more details about the container or what packages are pre-installed, look at the two Dockerfiles in this repository. If you'd like more packages pre-installed, please open an issue.

Contributing

Ok, but it's a good idea to open an issue and ask about a change before starting work on a pull request. Someone, or myself, may already be working on it, or planning to. Also, please consult this guide before you submit a pull request.