mirror of
https://github.com/PR0M3TH3AN/VoxVera.git
synced 2026-10-27 17:50:42 +00:00
179 lines
3.8 KiB
Markdown
179 lines
3.8 KiB
Markdown
# Linux Hosting Validation
|
|
|
|
This runbook defines the operational validation standard for VoxVera's only supported hosting target:
|
|
|
|
- Linux CLI with `systemd --user`
|
|
|
|
Everything else remains below that bar until equivalent evidence exists.
|
|
|
|
## Prerequisites
|
|
|
|
- `voxvera` installed and on `PATH`
|
|
- `tor` installed
|
|
- `onionshare-cli` available
|
|
- a user account that can run `systemctl --user`
|
|
|
|
## Quick Verification
|
|
|
|
Use the helper script first:
|
|
|
|
```bash
|
|
bash scripts/linux-recovery-check.sh
|
|
```
|
|
|
|
This checks:
|
|
|
|
- `platform-status --json`
|
|
- `doctor --json`
|
|
- `autostart status --json`
|
|
- expected Linux support tier and platform id
|
|
- presence of `~/host`
|
|
- Tor and OnionShare discovery
|
|
- autostart artifacts and timer state
|
|
- per-site state for `.onionshare-session`, `onionshare.log`, and `server.pid`
|
|
|
|
## Core Commands
|
|
|
|
Install autostart:
|
|
|
|
```bash
|
|
voxvera autostart
|
|
```
|
|
|
|
Inspect autostart:
|
|
|
|
```bash
|
|
voxvera autostart status
|
|
systemctl --user status voxvera-start.timer
|
|
systemctl --user status voxvera-start.service
|
|
```
|
|
|
|
Remove autostart:
|
|
|
|
```bash
|
|
voxvera autostart uninstall
|
|
```
|
|
|
|
Inspect runtime diagnostics:
|
|
|
|
```bash
|
|
voxvera doctor
|
|
voxvera doctor --json
|
|
```
|
|
|
|
## Validation Checklist
|
|
|
|
### 1. Fresh install
|
|
|
|
Run the Linux installer or install through the supported CLI path, then confirm:
|
|
|
|
```bash
|
|
voxvera platform-status --json
|
|
voxvera doctor --json
|
|
voxvera autostart status --json
|
|
```
|
|
|
|
Expected:
|
|
|
|
- `platform_id` is `linux_cli_systemd`
|
|
- support tier is `supported`
|
|
- `voxvera_cli`, `onionshare_cli`, and `tor_binary` pass
|
|
|
|
### 2. Build and serve
|
|
|
|
Create or edit a site, then build and serve it:
|
|
|
|
```bash
|
|
voxvera build
|
|
voxvera serve
|
|
```
|
|
|
|
Expected:
|
|
|
|
- site output appears under `~/host/<folder_name>/`
|
|
- `index.html` and QR code images exist
|
|
- `onionshare.log` is written
|
|
- `.onionshare-session` appears after the hidden service is started
|
|
|
|
### 3. Identity persistence
|
|
|
|
Confirm the site keeps its identity across rebuilds:
|
|
|
|
```bash
|
|
ls -la ~/host/<folder_name>/
|
|
voxvera build --config ~/host/<folder_name>/config.json
|
|
```
|
|
|
|
Expected:
|
|
|
|
- `.onionshare-session` still exists after rebuild
|
|
|
|
### 4. Autostart persistence
|
|
|
|
Confirm the recovery timer exists and is enabled:
|
|
|
|
```bash
|
|
voxvera autostart status
|
|
systemctl --user is-enabled voxvera-start.timer
|
|
systemctl --user is-active voxvera-start.timer
|
|
```
|
|
|
|
Expected:
|
|
|
|
- timer artifacts exist under `~/.config/systemd/user/`
|
|
- timer is enabled
|
|
|
|
### 5. Reboot recovery
|
|
|
|
After a reboot, verify:
|
|
|
|
```bash
|
|
bash scripts/linux-recovery-check.sh
|
|
systemctl --user status voxvera-start.timer
|
|
journalctl --user -u voxvera-start.service --no-pager -n 50
|
|
```
|
|
|
|
Expected:
|
|
|
|
- timer remains enabled
|
|
- service has retried `start-all`
|
|
- configured sites are restorable without manual reconfiguration
|
|
|
|
### 6. Offline/reconnect recovery
|
|
|
|
Temporarily disconnect the host from the network, reconnect, then wait through at least one timer interval.
|
|
|
|
Verify:
|
|
|
|
```bash
|
|
systemctl --user status voxvera-start.timer
|
|
journalctl --user -u voxvera-start.service --no-pager -n 50
|
|
bash scripts/linux-recovery-check.sh
|
|
```
|
|
|
|
Expected:
|
|
|
|
- timer is still active
|
|
- `start-all` retries appear in the service logs
|
|
- Tor becomes reachable again
|
|
|
|
## Paths That Matter
|
|
|
|
- `~/.config/systemd/user/voxvera-start.service`
|
|
- `~/.config/systemd/user/voxvera-start.timer`
|
|
- `~/host/<folder_name>/config.json`
|
|
- `~/host/<folder_name>/.onionshare-session`
|
|
- `~/host/<folder_name>/onionshare.log`
|
|
- `~/host/<folder_name>/server.pid`
|
|
|
|
## Failure Interpretation
|
|
|
|
If `bash scripts/linux-recovery-check.sh` fails:
|
|
|
|
- missing `onionshare_cli` or `tor_binary` means the runtime is incomplete
|
|
- missing `host_root` means no sites are built yet
|
|
- missing autostart artifacts means recovery was never installed or was removed
|
|
- `tor_socks_reachable` warning means Tor is not currently reachable even if it is installed
|
|
|
|
Linux should remain the only supported target until this runbook is repeatable on real hosts without caveats.
|