Thales Maciel
ed1b59240b
Make the milestone 3 runtime story predictable instead of treating doctor, self-check, and startup failures as loosely related surfaces. Split doctor and self-check into distinct read-only flows, add tri-state diagnostic status with stable IDs and next steps, and reuse that wording in CLI output, service logs, and tray-triggered diagnostics. Add non-mutating config/model probes, a make runtime-check gate, and public recovery/validation docs for the X11 GA roadmap. Validation: make runtime-check; PYTHONPATH=src python3 -m unittest discover -s tests -p 'test_*.py'; python3 -m py_compile src/*.py tests/*.py; PYTHONPATH=src python3 -m aman doctor --help; PYTHONPATH=src python3 -m aman self-check --help. Leave milestone 3 open in the roadmap until the manual X11 validation rows are filled.
149 lines
3.6 KiB
Markdown
149 lines
3.6 KiB
Markdown
# Portable X11 Install Guide
|
|
|
|
This is the canonical end-user install path for Aman on X11.
|
|
|
|
## 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).
|