Thales Maciel
359b5fbaf4
Make the X11 user path visible on first contact instead of burying it under config and maintainer detail. Rewrite the README around the supported quickstart, expected tray and dictation result, install validation, troubleshooting, and linked follow-on docs. Split deep config and developer material into separate docs, add checked-in screenshots plus a short WebM walkthrough, and add a generator so the media assets stay reproducible. Also fix the CLI discovery gap by letting `aman --help` show the top-level command surface while keeping implicit foreground `run` behavior, and align the settings, help, and about copy with the supported service-plus-diagnostics model. Validation: `PYTHONPATH=src python3 -m unittest tests.test_aman_cli tests.test_config_ui`; `PYTHONPATH=src python3 -m unittest discover -s tests -p 'test_*.py'`; `python3 -m py_compile src/*.py tests/*.py scripts/generate_docs_media.py`; `PYTHONPATH=src python3 -m aman --help`. Milestone 4 stays open in the roadmap because `docs/x11-ga/first-run-review-notes.md` still needs a real non-implementer walkthrough.
152 lines
3.8 KiB
Markdown
152 lines
3.8 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).
|
|
|
|
## 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`.
|
|
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).
|