thaloco/aman
1
Fork 0
Code Pull requests Releases Packages Activity Actions
aman/docs/portable-install.md
Thales Maciel dd2813340b Align CI with the validated Ubuntu support floor 
Stop implying that one Ubuntu 3.11 unit lane validates the full Linux support surface Aman documents.\n\nSplit CI into an Ubuntu CPython 3.10/3.11/3.12 unit-package matrix, a portable install plus doctor smoke lane, and a packaging lane gated on both. Add a reproducible ci_portable_smoke.sh helper with fake systemctl coverage, and force the installer onto /usr/bin/python3 so the smoke path uses the distro-provided GI and X11 Python packages it is meant to validate.\n\nUpdate the README, release/distribution docs, and Debian metadata to distinguish the automated Ubuntu CI floor from broader manual GA signoff families, and add the missing AppIndicator introspection package to the Ubuntu/Debian dependency lists.\n\nValidate with python3 -m unittest discover -s tests -p 'test_*.py', python3 -m py_compile src/*.py tests/*.py, and bash -n scripts/ci_portable_smoke.sh. The full xvfb-backed smoke could not be run locally in this sandbox because xvfb-run is unavailable.
2026-03-14 15:45:21 -03:00

4.3 KiB
Raw Blame History

Portable X11 Install Guide

This is the canonical end-user install path for Aman on X11.

For the shortest first-run path, screenshots, and the expected tray/dictation result, start with the quickstart in README.md.

Download published bundles, checksums, and release notes from https://git.thaloco.com/thaloco/aman/releases.

Supported environment

  • X11 desktop session
  • systemd --user
  • System CPython 3.10, 3.11, or 3.12
  • Runtime dependencies installed from the distro package manager

Current automated validation covers Ubuntu CI on CPython 3.10, 3.11, and 3.12 for unit/package coverage, plus a portable install and aman doctor smoke path with Ubuntu system python3. The other distro-family instructions below remain manual validation targets.

Runtime dependencies

Install the runtime dependencies for your distro before running install.sh.

Ubuntu/Debian

sudo apt install -y libportaudio2 python3-gi python3-xlib gir1.2-gtk-3.0 gir1.2-ayatanaappindicator3-0.1 libayatana-appindicator3-1

Arch Linux

sudo pacman -S --needed portaudio gtk3 libayatana-appindicator python-gobject python-xlib

Fedora

sudo dnf install -y portaudio gtk3 libayatana-appindicator-gtk3 python3-gobject python3-xlib

openSUSE

sudo zypper install -y portaudio gtk3 libayatana-appindicator3-1 python3-gobject python3-python-xlib

Fresh install

  1. Download aman-x11-linux-<version>.tar.gz and aman-x11-linux-<version>.tar.gz.sha256 from the releases page.
  2. Verify the checksum.
  3. Extract the bundle.
  4. Run install.sh.
sha256sum -c aman-x11-linux-<version>.tar.gz.sha256
tar -xzf aman-x11-linux-<version>.tar.gz
cd aman-x11-linux-<version>
./install.sh

The installer:

  • creates ~/.local/share/aman/<version>/
  • updates ~/.local/share/aman/current
  • creates ~/.local/bin/aman
  • installs ~/.config/systemd/user/aman.service
  • runs systemctl --user daemon-reload
  • runs systemctl --user enable --now aman

If ~/.config/aman/config.json does not exist yet, the first service start opens the graphical settings window automatically.

After saving the first-run settings, validate the install with:

aman self-check --config ~/.config/aman/config.json

Upgrade

Extract the new bundle and run the new install.sh again.

tar -xzf aman-x11-linux-<new-version>.tar.gz
cd aman-x11-linux-<new-version>
./install.sh

Upgrade behavior:

  • existing config in ~/.config/aman/ is preserved
  • existing cache in ~/.cache/aman/ is preserved
  • the old installed version is removed after the new one passes install and service restart
  • the service is restarted on the new version automatically

Uninstall

Run the installed uninstaller from the active install:

~/.local/share/aman/current/uninstall.sh

Default uninstall removes:

  • ~/.local/share/aman/
  • ~/.local/bin/aman
  • ~/.config/systemd/user/aman.service

Default uninstall preserves:

  • ~/.config/aman/
  • ~/.cache/aman/

Purge uninstall

To remove config and cache too:

~/.local/share/aman/current/uninstall.sh --purge

Filesystem layout

  • Installed payload: ~/.local/share/aman/<version>/
  • Active symlink: ~/.local/share/aman/current
  • Command shim: ~/.local/bin/aman
  • Install state: ~/.local/share/aman/install-state.json
  • User service: ~/.config/systemd/user/aman.service

Conflict resolution

The portable installer refuses to overwrite:

  • an unmanaged ~/.local/bin/aman
  • an unmanaged ~/.config/systemd/user/aman.service
  • another non-portable aman found earlier in PATH

If you already installed Aman from a distro package:

  1. uninstall the distro package
  2. remove any leftover aman command from PATH
  3. remove any leftover user service file
  4. rerun the portable install.sh

Recovery path

If installation succeeds but runtime behavior is wrong, use the supported recovery order:

  1. aman doctor --config ~/.config/aman/config.json
  2. aman self-check --config ~/.config/aman/config.json
  3. journalctl --user -u aman -f
  4. aman run --config ~/.config/aman/config.json --verbose

The failure IDs and example outputs for this flow are documented in docs/runtime-recovery.md.

Public support and issue reporting instructions live in SUPPORT.md.