Thales Maciel
a3368056ff
Some checks are pending
ci / test-and-build (push) Waiting to run
Implement milestone 2 around a portable X11 release bundle instead of\nkeeping distro packages as the only end-user path.\n\nAdd make/package scripts plus a portable installer helper that builds the\ntarball, creates a user-scoped venv install, manages the user service, handles\nupgrade rollback, and supports uninstall with optional purge.\n\nFlip the end-user docs to the portable bundle, add a dedicated install guide\nand validation matrix, and leave the roadmap milestone open only for the\nremaining manual distro validation evidence.\n\nValidation: python3 -m py_compile src/*.py packaging/portable/portable_installer.py tests/test_portable_bundle.py; PYTHONPATH=src python3 -m unittest tests.test_portable_bundle; PYTHONPATH=src python3 -m unittest tests.test_aman_cli tests.test_diagnostics tests.test_portable_bundle; PYTHONPATH=src python3 -m unittest discover -s tests -p 'test_*.py'
146 lines
3.5 KiB
Markdown
146 lines
3.5 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`
|