Skip to content

flatpak

An application or runtime from a Flatpak remote such as Flathub, in the system installation or the connecting user’s.

Use flatpak to put an app from Flathub, or any other Flatpak remote, on a desktop or kiosk, and to keep it there. Every plan reads flatpak list, so an app someone uninstalled by hand shows up in conn3x drift.

Install an app from Flathub for every user on the host:

step "calculator" {
flatpak {
name = "org.gnome.Calculator"
}
}

Install a few at once, into the connecting user’s own installation:

step "desktop_apps" {
for_each = toset(["org.mozilla.firefox", "org.videolan.VLC", "org.libreoffice.LibreOffice"])
flatpak {
name = item.value
method = "user"
}
}

Keep an app at the newest build the remote has, and take one out:

step "browser" {
flatpak {
name = "org.mozilla.firefox"
state = "latest"
}
}
step "old_player" {
flatpak {
name = "org.gnome.Totem"
state = "absent"
}
}
Name Type Required Description
method string No “system” (default) for every user on the host, or “user” for the connecting user’s own installation.
name string Yes Application ID, such as org.gnome.Calculator.
on_remove string No What happens on the host when this step is removed: “forget” (default) leaves the app, “delete” uninstalls it.
remote string No Remote to install from, which the host must already have. Defaults to flathub.
state string No “present” (default), “latest” or “absent”.

Conn3x sets these; reference them as conn3x_flatpak.<circuit>__<step>["<host>"].<name>.

Name Type Description
in_sync bool Whether the app is installed, or not, as wanted, and with state “latest” as new as the remote has.
revision string Changes each time Conn3x changes this on the host. Handlers watch it.

A step lowers to the conn3x_flatpak resource, one instance per host, and connects with its circuit’s ssh block.

The remote. remote is where a missing app is installed from, and defaults to flathub. The host has to have it already: Conn3x doesn’t add remotes, so add Flathub with a command step guarded by flatpak remotes, or bake it into the image. An app that’s already installed is accepted from whatever remote it came from, as Ansible’s module does.

Reading. On every plan, Conn3x runs flatpak list for the installation method names. in_sync is true when the app is installed, or with state = "absent" when it isn’t. With state = "latest" it also asks the remote with flatpak remote-ls --updates, which takes network access, and is out of sync while the remote has a newer build.

Applying. A missing app is installed with flatpak install -y --noninteractive remote name, and its runtime comes with it. An outdated one is updated with flatpak update. An unwanted one is uninstalled; its runtime stays, since other apps may share it. Nothing runs when the host already matches.

The installation. method = "system", the default, is the installation every user on the host shares, and needs root. method = "user" is the connecting user’s own installation under their home, and the remote has to be added there too, with flatpak remote-add --user.

Changing a step. Changing remote or state updates in place. Changing name or method replaces the step, and the old app is handled by its on_remove.

When you delete a flatpak step, on_remove decides what happens on the host. The default, "forget", leaves the app installed. "delete" uninstalls it.

conn3x convert ansible turns community.general.flatpak tasks into flatpak steps, one for each name, keeping remote, method and state. A task stays a TODO with the reason when a name is a ref such as app/org.gnome.Calculator/x86_64/stable or a URL to a .flatpakref file, when it sets executable to something other than flatpak, or when it sets no_dependencies, which the step doesn’t have.