# KeePassXC RHEL 9-Compatible AppImage Build

Build KeePassXC 2.8.x AppImages on Ubuntu 20.04 (Focal) that run on
RHEL 9.x systems.  The official 2.8.0 AppImage was built on Ubuntu 24.04
and requires GLIBC_2.38, which fails on RHEL 9 (glibc 2.34).  See
[GitHub issue #13969](https://github.com/keepassxreboot/keepassxc/issues/13969).

## Why Ubuntu 20.04?

AppImages bundle Qt and most libraries, but still link against the host
`libc`, `libm`, and `libstdc++`.  To run on RHEL 9 (glibc 2.34), the
AppImage must be built on a system with equal or older glibc.

| System         | glibc  | libstdc++ (GLIBCXX) |
|----------------|--------|---------------------|
| Ubuntu 20.04   | 2.31   | 3.4.28 (GCC 10)     |
| RHEL 9.x       | 2.34   | 3.4.29 (GCC 11.5)   |
| Ubuntu 24.04   | 2.38   | 3.4.32 (GCC 13)     |

Our AppImage needs max GLIBC_2.30 and GLIBCXX_3.4.28 — well within
RHEL 9 capabilities.

## Build Host Setup (one-time)

### 1. Install Rob Savoury's PPAs for Qt 6.2

KeePassXC 2.8.x requires Qt >= 6.2.4.  Ubuntu 20.04 ships Qt 5 only.
The Savoury PPA provides Qt 6.2.13 LTS backported to Focal, depending
only on libc6 >= 2.29 and libstdc++6 >= 10.

The PPAs must be added in this order due to dependencies:

```bash
sudo add-apt-repository -y ppa:savoury1/build-tools
sudo add-apt-repository -y ppa:savoury1/backports
sudo add-apt-repository -y ppa:savoury1/python
sudo add-apt-repository -y ppa:savoury1/fonts
sudo add-apt-repository -y ppa:savoury1/graphics
sudo add-apt-repository -y ppa:savoury1/multimedia
sudo add-apt-repository -y ppa:savoury1/ffmpeg4
sudo add-apt-repository -y ppa:savoury1/display
sudo add-apt-repository -y ppa:savoury1/llvm-defaults-13
sudo add-apt-repository -y ppa:savoury1/qt-6-2
```

### 2. Install build dependencies

```bash
sudo apt-get install -y g++-10 cmake ninja-build git \
  qt6-base-dev qt6-base-dev-tools qt6-base-private-dev \
  qt6-tools-dev qt6-tools-dev-tools qt6-l10n-tools \
  qt6-svg-dev qt6-wayland qt6-wayland-dev qt6-wayland-dev-tools \
  qt6-websockets-dev qt6-image-formats-plugins qt6-translations-l10n \
  libargon2-dev libqrencode-dev libreadline-dev libxi-dev libxtst-dev \
  libyubikey-dev libykpers-1-dev libusb-1.0-0-dev libpcsclite-dev \
  libminizip-dev libkeyutils-dev libxkbcommon-dev asciidoctor \
  zlib1g-dev fuse libfuse2 libgl1-mesa-dev
```

We use **GCC 10** specifically because it emits max GLIBCXX_3.4.28,
safe for RHEL 9.  Do not use the default GCC 9 (lacks C++20 features
KPXC needs) or GCC 11+ (would raise the GLIBCXX floor above RHEL 9).

### 3. Build Botan 2.19.5 from source

KeePassXC 2.8.x requires Botan >= 2.19.1.  Ubuntu 20.04 ships
Botan 2.12.1 which is too old.

```bash
cd ~/src
./build_botan.sh
```

This builds Botan 2.19.5 with GCC 10 and installs to /usr.  The
resulting library needs only GLIBC_2.29 and GLIBCXX_3.4.26.

Note: If a future KPXC release requires a newer Botan, update
BOTAN_VERSION in build_botan.sh and re-run it.

Important: Remove the distro Botan dev package first to avoid
conflicts:

```bash
sudo apt remove libbotan-2-dev
```

The build_botan.sh script manually copies headers to
/usr/include/botan-2/botan/ using cp -aL (dereference symlinks)
to avoid broken symlinks.

### 4. Install AppImage tooling

The build needs current versions of linuxdeploy, linuxdeploy-plugin-qt,
and appimagetool.  Old versions (pre-2020) only support Qt 5.

```bash
cd /usr/local/bin
sudo curl -fL -o linuxdeploy \
  https://github.com/linuxdeploy/linuxdeploy/releases/download/continuous/linuxdeploy-x86_64.AppImage
sudo curl -fL -o linuxdeploy-plugin-qt \
  https://github.com/linuxdeploy/linuxdeploy-plugin-qt/releases/download/continuous/linuxdeploy-plugin-qt-x86_64.AppImage
sudo curl -fL -o appimagetool \
  https://github.com/AppImage/appimagetool/releases/download/continuous/appimagetool-x86_64.AppImage
sudo chmod +x linuxdeploy linuxdeploy-plugin-qt appimagetool
```

### 5. Clone KeePassXC

```bash
cd ~/src
git clone https://github.com/keepassxreboot/keepassxc.git
```

### 6. Proxy considerations

If the build host uses a Squid proxy, the https_proxy environment
variable MUST use the http:// scheme, not https://.  Git 2.50+
(from the Savoury PPA) is strict about this and will fail with
"gnutls_handshake() failed" if https:// is used.

```bash
# Correct:
export https_proxy=http://proxy.example.com:3128/
# Wrong (will fail with git 2.50+):
export https_proxy=https://proxy.example.com:3128/
```

The build script unsets proxy variables entirely to avoid this issue.

## Building

```bash
cd ~/src
./do_kpxc_appimage.py                # build default version (2.8.0)
./do_kpxc_appimage.py 2.8.1          # build a specific version
./do_kpxc_appimage.py --latest       # auto-detect latest 2.8.x tag
```

Build takes about 4 minutes on an 8-core VM.  The AppImage is
automatically copied to /net/imladris/var/tmp/DUMP-Unsorted/.

Output filename format: KeePassXC-2.8.0-1-RHEL9-x86_64.AppImage

## What the Build Script Does

1. Fetches all tags from upstream (git fetch --all --tags --force)
2. Checks out the release tag (e.g., 2.8.0)
3. Nuclear-cleans the tree (git checkout -f + git clean -fdx)
4. Creates a local branch rhel9-build-VERSION
5. Patches release-tool.py with three fixes:
   - Copies the app icon to AppDir root (newer appimagetool requires it)
   - Creates usr/translations directory (avoids symlink warnings)
   - Adds --no-appstream flag (skips AppStream metadata validation
     that fails on harmless warnings)
6. Commits the patch (release-tool refuses to build from a dirty tree)
7. Builds using release-tool.py with --snapshot and --override-version
   (since we build from a branch, not the tag directly)
8. Renames the AppImage with -RHEL9- suffix
9. Copies to the shared destination

## Key Environment Variables

The build script sets these for the KeePassXC build system:

| Variable                   | Value                            | Why                              |
|----------------------------|----------------------------------|----------------------------------|
| CC / CXX                   | gcc-10 / g++-10                  | GLIBCXX compat with RHEL 9       |
| QMAKE                      | /usr/bin/qmake6                  | linuxdeploy-plugin-qt needs this |
| EXTRA_QT_PLUGINS           | waylandcompositor;svg            | Bundle Wayland + SVG support     |
| EXTRA_PLATFORM_PLUGINS     | libqwayland-egl.so;...           | Bundle Wayland platform plugins  |

## Files

| File                    | Purpose                                    |
|-------------------------|--------------------------------------------|
| do_kpxc_appimage.py     | Main build script                          |
| build_botan.sh          | Botan 2.19.5 build/install (one-time)      |
| keepassxc/              | KeePassXC git clone                        |
| Botan-2.19.5/           | Botan source tree                          |
| Botan-2.19.5.tar.xz    | Botan source tarball                       |
| legacy/                 | Old bash build script                      |

## ABI Verification

To verify an AppImage is RHEL 9 compatible:

```bash
cd /tmp && mkdir check && cd check
./KeePassXC-*.AppImage --appimage-extract >/dev/null 2>&1
find squashfs-root -name "*.so*" -o -name "keepassxc*" -type f | \
  xargs objdump -T 2>/dev/null | \
  grep -oP "GLIBC_[0-9.]+" | sort -V -u | tail -1
# Must be <= GLIBC_2.34 for RHEL 9
```

## Troubleshooting

**gnutls_handshake() failed during git fetch:**
Proxy https_proxy is using https:// scheme.  Change to http://
or unset it.

**Could not find Qt modules during AppImage packaging:**
Old linuxdeploy-plugin-qt.  Re-download current version (see step 4).

**GLIBC_2.38 not found when running on RHEL 9:**
The AppImage was built on too new a system.  Must be built on
Ubuntu 20.04 with GCC 10.

**Botan version too old:**
Remove the distro package (sudo apt remove libbotan-2-dev) and
rebuild from source with build_botan.sh.

**release-tool.py "working tree is not clean":**
The build script handles this automatically by committing patches
on a local branch.  If running manually, commit or stash changes
before building.

**appimagetool "Failed to validate AppStream information":**
The --no-appstream patch handles this.  If running manually, pass
--no-appstream to appimagetool.

---
*Created: 2026-10-31*
*Author: Vincent S. Cojot*
