Thales Maciel
31a1e069b3
Add the repo-side pieces for milestone 5: MIT licensing, real maintainer and forge metadata, a public support doc, 1.0.0 release notes, release-prep tooling, and CI uploads for the full candidate artifact set. Keep source-tree version surfaces honest by reading the local project version in the CLI and About dialog, and cover the new release-prep plus version-fallback behavior with focused tests. Document where raw validation evidence belongs, add the GA validation rollup, and archive the latest readiness review. Milestone 5 remains open until the forge release page is published and the milestone 2 and 3 matrices are filled with linked manual evidence. Validation: PYTHONPATH=src python3 -m unittest discover -s tests -p 'test_*.py'; PYTHONPATH=src python3 -m unittest tests.test_release_prep tests.test_portable_bundle tests.test_aman_cli tests.test_config_ui; python3 -m py_compile src/*.py tests/*.py; PYTHONPATH=src python3 -m aman version
158 lines
4 KiB
Markdown
158 lines
4 KiB
Markdown
# 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`](../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
|
|
|
|
## Runtime dependencies
|
|
|
|
Install the runtime dependencies for your distro before running `install.sh`.
|
|
|
|
### Ubuntu/Debian
|
|
|
|
```bash
|
|
sudo apt install -y libportaudio2 python3-gi python3-xlib gir1.2-gtk-3.0 libayatana-appindicator3-1
|
|
```
|
|
|
|
### Arch Linux
|
|
|
|
```bash
|
|
sudo pacman -S --needed portaudio gtk3 libayatana-appindicator python-gobject python-xlib
|
|
```
|
|
|
|
### Fedora
|
|
|
|
```bash
|
|
sudo dnf install -y portaudio gtk3 libayatana-appindicator-gtk3 python3-gobject python3-xlib
|
|
```
|
|
|
|
### openSUSE
|
|
|
|
```bash
|
|
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`.
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
aman self-check --config ~/.config/aman/config.json
|
|
```
|
|
|
|
## Upgrade
|
|
|
|
Extract the new bundle and run the new `install.sh` again.
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
~/.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:
|
|
|
|
```bash
|
|
~/.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`](./runtime-recovery.md).
|
|
|
|
Public support and issue reporting instructions live in
|
|
[`SUPPORT.md`](../SUPPORT.md).
|