This document walks through building the Medical Document Processor AppImage on Manjaro Linux (KDE Plasma). The same steps work on Arch Linux, with minor adaptations for Ubuntu/Fedora noted at the end.
TL;DR —
cd packages/desktop && bash build_appimage.sh --version-from-git --smoke-test
sudo pacman -Syu --needed \
python python-pip \
tesseract tesseract-data-eng tesseract-data-ara \
poppler \
qt6-base qt6-imageformats \
cairo pango gdk-pixbuf2 \
libfuse2Notes:
libfuse2is required by AppImage runtime (otherwise AppImages won't mount).tesseract-data-araprovides Arabic OCR.popplerprovidespdf2imagerendering for PDF inputs.
Two options:
Option A — AUR (recommended):
yay -S appimagetoolOption B — Auto-download (build script handles this):
The build_appimage.sh script auto-downloads appimagetool-x86_64.AppImage from GitHub releases if appimagetool is not on $PATH. The downloaded binary lands at /tmp/appimagetool.
# System-wide (or use a venv)
python -m venv ~/venvs/omni
source ~/venvs/omni/bin/activate
# Install scanner_fixer (editable) + desktop deps
cd packages/scanner_fixer && pip install -e . && cd ../..
cd packages/desktop && pip install -r requirements.txt
pip install pyinstallerVerify:
python -c "import PySide6, cv2, scanner_fixer; print('OK')"cd packages/desktop
# Option 1: explicit version
bash build_appimage.sh 1.1.0-rc1
# Option 2: derive version from git tags
bash build_appimage.sh --version-from-git
# Option 3: full pipeline with smoke test
bash build_appimage.sh --version-from-git --smoke-test| Step | Action |
|---|---|
| 1 | Detect distro (Manjaro/Arch/Debian/Fedora) |
| 2 | Verify PySide6, cv2, scanner_fixer, PyInstaller |
| 3 | Run build.sh → dist/medical-doc-processor (PyInstaller onefile ELF) |
| 4 | Stage AppDir/ with binary, .desktop, icon, metainfo.xml |
| 5 | Generate AppRun launcher (Qt platform abstraction) |
| 6 | Acquire appimagetool (system or auto-download) |
| 7 | Pack AppDir/ → MedicalDocProcessor-<ver>-x86_64.AppImage |
| 8 | Generate <name>.AppImage.sha256 checksum |
| 9 | (Optional) Smoke-test the AppImage with OMNI_APPIMAGE_OFFSCREEN=1 |
packages/desktop/
├── MedicalDocProcessor-1.1.0-rc1-x86_64.AppImage (~250-400 MB)
├── MedicalDocProcessor-1.1.0-rc1-x86_64.AppImage.sha256
├── dist/
│ └── medical-doc-processor (PyInstaller ELF, intermediate)
└── AppDir/ (staged tree, intermediate)
chmod +x MedicalDocProcessor-1.1.0-rc1-x86_64.AppImage
./MedicalDocProcessor-1.1.0-rc1-x86_64.AppImageKDE Plasma 6 on Manjaro defaults to Wayland. The AppRun launcher auto-detects WAYLAND_DISPLAY and sets QT_QPA_PLATFORM=wayland. If you hit rendering glitches, force X11:
QT_QPA_PLATFORM=xcb ./MedicalDocProcessor-1.1.0-rc1-x86_64.AppImageFor automated testing without a display:
OMNI_APPIMAGE_OFFSCREEN=1 ./MedicalDocProcessor-1.1.0-rc1-x86_64.AppImage --versionsudo mv MedicalDocProcessor-1.1.0-rc1-x86_64.AppImage /usr/local/bin/medical-doc-processor.AppImage
sudo mv MedicalDocProcessor-1.1.0-rc1-x86_64.AppImage.sha256 /usr/local/bin/
sudo chmod +x /usr/local/bin/medical-doc-processor.AppImage
# Verify checksum
sha256sum -c /usr/local/bin/medical-doc-processor.AppImage.sha256
# Optional: create a desktop entry (so it shows in KDE menu)
sudo tee /usr/share/applications/medical-doc-processor.desktop << 'EOF'
[Desktop Entry]
Type=Application
Name=Medical Document Processor
Exec=/usr/local/bin/medical-doc-processor.AppImage
Icon=medical-doc-processor
Terminal=false
Categories=Office;Graphics;Scanning;MedicalSoftware;
EOF# Confirm checksum matches
sha256sum -c MedicalDocProcessor-1.1.0-rc1-x86_64.AppImage.sha256
# Inspect AppDir contents
./MedicalDocProcessor-1.1.0-rc1-x86_64.AppImage --appimage-extract
ls squashfs-root/Manjaro fix:
sudo pacman -S libfuse2You're running without X/Wayland. Either log into KDE Plasma or use:
OMNI_APPIMAGE_OFFSCREEN=1 ./MedicalDocProcessor-*.AppImageReinstall scanner_fixer editable:
cd packages/scanner_fixer && pip install -e .Install Arabic tesseract data:
sudo pacman -S tesseract-data-araVerify:
tesseract --list-langs | grep araThe PyInstaller onefile bundles Python + Qt + OpenCV. To shrink:
- Use
--onefile(already default) instead of--onedir. - Strip debug symbols:
strip dist/medical-doc-processor. - Consider UPX compression (adds startup cost):
upx --best dist/medical-doc-processor.
sudo apt update
sudo apt install -y python3 python3-pip python3-venv \
tesseract-ocr tesseract-ocr-ara poppler-utils \
libfuse2 qt6-base-dev
# appimagetool: download from GitHub releases
wget https://github.com/AppImage/AppImageKit/releases/download/continuous/appimagetool-x86_64.AppImage
chmod +x appimagetool-x86_64.AppImage
sudo mv appimagetool-x86_64.AppImage /usr/local/bin/appimagetoolThen run bash build_appimage.sh as above.
sudo dnf install -y python3 python3-pip \
tesseract tesseract-langpack-ara poppler-utils \
fuse fuse-libs qt6-qtbase
# appimagetool via direct download (same as Ubuntu)The GitHub Actions workflow at .github/workflows/appimage-build.yml builds the AppImage on every push to feat/rc-hardening-p0 and on tags matching v*. It runs the smoke test in offscreen mode and uploads the AppImage + checksum as an artifact.
Download artifacts from: Actions tab → latest run → appimage-artifacts
- Bump version in
RELEASE_CANDIDATE_CHECKLIST.md - Tag the release:
git tag -a v1.1.0-rc1 -m "v1.1.0-rc1" - Push tag:
git push origin v1.1.0-rc1 - Wait for
appimage-build.ymlto complete - Download the AppImage artifact
- Run smoke test on Manjaro:
bash build_appimage.sh --smoke-test - Create GitHub Release with AppImage + checksum attached
- Update
RELEASE_NOTES_v1.1.0-rc1.mdwith download links