Initial O3DE Flatpak packaging + Gitea CI
Repackage the official O3DE Linux .deb as a Flatpak and publish it as a static OSTree repo on the 'pages' branch for install via flatpak remote. - org.o3de.O3DE.yaml: flatpak-builder manifest (extracts the .deb into /app) - o3de-wrapper.sh: launcher that locates the versioned o3de binary at runtime - desktop + AppStream metadata under the app-id - scripts/: live version resolver and local build helper - .gitea/workflows/build-flatpak.yml: daily check -> build -> publish -> tag Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,133 @@
|
||||
# O3DE Flatpak
|
||||
|
||||
Repackage the official [Open 3D Engine](https://o3de.org/) 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](https://ostreedev.github.io/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)
|
||||
|
||||
```sh
|
||||
# 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:
|
||||
|
||||
```sh
|
||||
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
|
||||
|
||||
```sh
|
||||
sudo apt install flatpak flatpak-builder # or your distro's equivalent
|
||||
./scripts/build.sh
|
||||
```
|
||||
|
||||
Test without installing:
|
||||
|
||||
```sh
|
||||
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
|
||||
|
||||
- **The `.deb` internal layout is assumed** (`/opt/O3DE/<ver>/…` with the
|
||||
`o3de` binary under `bin/Linux/…`). If a future release changes this, adjust
|
||||
`o3de-wrapper.sh` and the manifest's copy commands. The first real build will
|
||||
confirm it.
|
||||
- **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.*
|
||||
Reference in New Issue
Block a user