# Termux acceptance checklist — one page

Run this on a **real Android device** to turn native Termux from *experimental* into
*supported*. It is the only test that counts: everything else (`termux-sim.sh`,
`supervisor-test.sh`) runs on a Linux host and proves the code, not Android.

Paste the output of step 6 back to the operator; that is the evidence.

---

## 1. What a pass proves

| Check | Means |
|---|---|
| Termux + PREFIX | the adapter is running on real Android, not a simulation |
| `nginx -t` with the generated wrapper | the 35 KB vhost parses with Termux's nginx and its `mime.types` |
| supervisor resolves + runs | 16 services spawn without systemd |
| 4 API endpoints answer 200 | the Python services and ports actually work |
| `https://<domain>/federation/node.json` 200 | the tunnel terminates TLS and reaches nginx |

It does **not** prove: load capacity, battery endurance, or that Cloudflare will keep the
tunnel up for weeks.

## 2. Before you start

- Termux from **F-Droid** or GitHub releases — the Play Store build is abandoned and `pkg` fails.
- ~3 GB free, Android 9+, a domain pointing at the tunnel (Cloudflare account, free tier).
- Termux:Boot add-on if you want services back after a reboot.
- Battery optimisation set to **Unrestricted** for Termux (`Settings → Apps → Termux → Battery`).

```bash
pkg update -y && pkg install -y proot-distro git curl termux-api
termux-wake-lock          # keeps Android from freezing the supervisor
```

## 3. Path A — proot Debian (recommended)

```bash
# Termux shell
git clone --depth 1 https://git.webx11.duckdns.org/webx11.git ~/webx11
bash ~/webx11/deploy/termux-bootstrap.sh          # installs Debian, clones into it

# inside the Debian login that opens:
cd /root/webx11-src
cp deploy/wx11.conf deploy/wx11.conf.local
nano deploy/wx11.conf.local        # set the 11 lines below
```

```bash
WX11_DOMAIN="myphone.example.org"
WX11_USER="root"
WX11_ROOT="/root/webx11"
WX11_DATA="/root/.local/share/webx11"
WX11_STATE="/root/.local/share/webx11/federation"
WX11_LOG_DIR="/root/.local/share/webx11/log"
WX11_PLATFORM="debian"             # inside proot it IS Debian
WX11_SERVICE_MANAGER="supervisor"
WX11_BIND_ADDR="127.0.0.1"
WX11_HTTP_PORT="8080"
WX11_TLS_MODE="tunnel"
WX11_TUNNEL_ID="<uuid printed by: cloudflared tunnel create webx11>"
```

```bash
bash deploy/install.sh --conf deploy/wx11.conf.local --source /root/webx11-src --platform debian
cloudflared tunnel login
cloudflared tunnel create webx11
cloudflared tunnel route dns webx11 myphone.example.org
cloudflared tunnel --config /root/.local/share/webx11/cloudflared/config.yml run
```

## 4. Path B — native (only to test the experimental adapter)

```bash
bash ~/webx11/deploy/termux-bootstrap.sh --native
cd ~/webx11 && cp deploy/wx11.conf deploy/wx11.conf.local
```

Use the config from `docs/PLATFORMS.md` §"mode B" (it sets `WX11_PLATFORM=termux`,
`WX11_PHP=0`, `WX11_PREFIX="$PREFIX"`), then:

```bash
bash deploy/install.sh --conf deploy/wx11.conf.local --source "$HOME/webx11" --platform termux
bash deploy/lib/svc.sh --conf deploy/wx11.conf.local start
```

## 5. Keep it alive

```bash
#!/data/data/com.termux/files/usr/bin/sh
# ~/.termux/boot/webx11.sh   (needs the Termux:Boot add-on)
termux-wake-lock
~/webx11/deploy/lib/svc.sh --conf ~/webx11/deploy/wx11.conf start
```

## 6. The acceptance run

```bash
bash deploy/test-termux.sh
```

A pass ends with exactly:

```
TERMUX ACCEPTANCE PASSED
```

and every line above it reads `OK`. Copy the **whole** output (it is ~20 lines) plus:

```bash
uname -a; echo "$PREFIX"; nginx -v; python3 -V
```

## 7. If it fails

| Symptom | Cause | Fix |
|---|---|---|
| `FAIL not Termux (TERMUX_VERSION unset)` | running in proot or a plain shell | run `test-termux.sh` from the **Termux** shell, not inside the Debian login |
| `FAIL bcrypt missing` | no wheel/build chain for the Termux triplet | `pkg install python-bcrypt`; if unavailable, auth features are unsupported — say so in the report |
| `FAIL nginx -t` | `mime.types` path differs on this nginx build | `grep include "$PREFIX/etc/nginx/nginx.conf.test"` and send the path |
| `:89xx not listening` | a service crash-looped | `tail -40 "$WX11_LOG_DIR/<service>.log"` |
| `supervisor not running` | started without a wake lock, or Doze killed it | `termux-wake-lock; svc.sh start`, re-check |
| `public node.json -> 000/502` | tunnel down or wrong local port | `cloudflared tunnel info webx11`; confirm `WX11_HTTP_PORT` matches the tunnel ingress |
| `public node.json -> 403` | Cloudflare Access policy on the hostname | disable the policy or exempt `/federation/*` |
| proot: `Permission denied` on a bind mount | storage not shared | `proot-distro login debian --shared-tmp`, retry |

## 8. Do not

- Expose `8080` on `0.0.0.0` — bind `127.0.0.1` and let the tunnel be the only door.
- Run the native adapter as root/su; Android has one app UID and `chown` will corrupt the tree.
- Put the admin password in shell history — use `--admin-password-file` and delete it after.
- Report a pass without the full output; a truncated run cannot be verified.

## 9. Report back

Send: the `test-termux.sh` output, the four version lines from step 6, the phone model and
Android version, and which path (A or B) you used. With that, the matrix entry in
`docs/PLATFORMS.md` can change from *experimental* to *supported* honestly.