o3de-flatpak/README.md

O3DE Flatpak

Repackage the official Open 3D Engine Linux release as a Flatpak so it can be installed on any distribution — not only Debian/Ubuntu.

A Gitea Actions workflow checks daily for a new O3DE release, builds the Flatpak, and publishes it as a static OSTree Flatpak repository on the pages branch of this repo. You add that as a Flatpak remote and install / update like any other app.

Status: community / unofficial. O3DE is a large application (~15–18 GB installed); building and hosting it is heavy. Treat this as best-effort.

---

Installing (end users)

# Flathub provides the runtime O3DE needs
flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo

# Add this repo (replace <owner> with the Gitea account that owns the repo)
flatpak remote-add --if-not-exists o3de \
  https://gitea.pc-heini.de/<owner>/o3de-flatpak/raw/branch/pages/o3de.flatpakrepo

flatpak install o3de org.o3de.O3DE
flatpak run org.o3de.O3DE

Later updates:

flatpak update org.o3de.O3DE

The repo is currently unsigned (no GPG). Flatpak will add it with GPG verification disabled. See Signing below to harden this.

---

How it works

File	Purpose
org.o3de.O3DE.yaml	flatpak-builder manifest. Unpacks the official o3de_*.deb into /app and wires up a launcher.
o3de-wrapper.sh	Entry point. Finds the versioned o3de Project Manager binary inside the sandbox and sets LD_LIBRARY_PATH.
org.o3de.O3DE.desktop	Desktop entry under the Flatpak app-id.
org.o3de.O3DE.metainfo.xml	AppStream metadata (version stamped at build time).
scripts/get-latest-version.sh	Resolves the latest .deb URL, version, and SHA-256 from o3debinaries.org.
scripts/build.sh	Build + test the Flatpak locally.
.gitea/workflows/build-flatpak.yml	CI: detect new version → build → publish to pages → tag vX.Y.Z.

The engine ships as a Debian package at a predictable URL (https://o3debinaries.org/main/Latest/Linux/o3de_<ver>.deb). The build extracts it (ar + tar) and copies the payload into the Flatpak's /app. The version directory inside the .deb changes every release, so the wrapper discovers the executable at runtime rather than hard-coding a path.

---

CI requirements (Gitea Actions)

The workflow targets a self-hosted act_runner. Because O3DE is large:

• Disk: budget 60 GB+ free. The build needs roughly 2–3× the installed size (extracted payload in build-dir + a copy committed into the OSTree repo/). The job deletes build-dir before publishing to cut peak usage, but it can still be tight. If builds fail on space, that's the first thing to check.
• Privileged container: Flatpak's sandbox (bubblewrap) needs it. The job sets options: --privileged; your runner's config.yaml must allow privileged containers (or run jobs in host mode with flatpak/flatpak-builder installed on the host).
• Runner label: the job uses runs-on: ubuntu-latest. Change it if your runner is registered with a different label.
• Token: publishing force-pushes the pages branch and creates a vX.Y.Z tag. The auto-provided GITHUB_TOKEN (with contents: write) usually suffices. If your instance restricts it, create a Personal Access Token with repo write access and add it as a secret named PUBLISH_TOKEN — the workflow prefers it automatically.

Trigger it manually from the Gitea Actions UI (workflow_dispatch, with an optional force rebuild), or let the daily cron run it. It only rebuilds when the upstream version has no matching vX.Y.Z tag yet, so reruns are cheap no-ops.

---

Building locally

sudo apt install flatpak flatpak-builder      # or your distro's equivalent
./scripts/build.sh

Test without installing:

flatpak-builder --run build-dir org.o3de.O3DE.yaml o3de-wrapper.sh

---

Signing (recommended hardening)

The first iteration publishes an unsigned repo for simplicity. To sign:

1. Generate a key: gpg --quick-gen-key "O3DE Flatpak" default default never
2. Export the public key and add GPGKey=<base64> to the generated .flatpakrepo.
3. Pass --gpg-sign=<KEYID> to both flatpak-builder and build-update-repo, and provide the private key to CI via a secret. Until then, users add the remote with GPG verification disabled.

---

Caveats & things to verify

These were confirmed by inspecting the v26.05 package (opt/O3DE/26.05/…):

• Layout is confirmed for now: the package installs everything under /opt/O3DE/<ver>/, with the launcher at bin/Linux/profile/Default/o3de and ~270 .so files beside it (hence the wrapper's LD_LIBRARY_PATH). If a future release moves things, adjust o3de-wrapper.sh and the manifest.
• Runs against org.freedesktop.Sdk, not Platform. O3DE's package dependencies are a build toolchain (clang/ninja/cmake/pkg-config) because the engine compiles project code at runtime. Those live in the SDK. Users therefore pull the SDK runtime (larger than Platform) on install — Flatpak does this automatically from Flathub.
• Python is baked in at build time. O3DE normally downloads its Python runtime into its own install tree on first use, but that tree is read-only inside a Flatpak. The manifest runs python/get_python.sh during the build (with network access) so Python is part of the immutable image. This is the most likely step to need tweaking — verify it on the first real CI build.
• Runtime writes into the install tree may still fail. Anything O3DE tries to pip install or generate inside /opt/O3DE/... at runtime (e.g. per-gem Python deps when building certain projects) will hit the read-only /app. Base project building should work; exotic gems may not. This is the main open risk.
• No launcher icon yet. The .deb ships only in-editor asset icons, so the desktop entry uses a generic icon. Drop a real O3DE logo into the repo and install it in the manifest to fix this.
• GPU / drivers: the renderer needs working GPU access. The manifest grants --device=dri/--device=all; on some setups you may also want the matching GPU driver extension from Flathub.
• Sandbox filesystem: --filesystem=home lets the Project Manager create and open projects under your home directory. Tighten or widen to taste.
• Hosting via raw branch URLs works because Flatpak fetches individual files (summary, config, objects/…). Gitea serves these from the pages branch. If you later put a real static web host in front of it, just change Url= in the .flatpakrepo.

---

Not affiliated with or endorsed by the Open 3D Foundation. O3DE is licensed under Apache-2.0 / MIT.