Simplify SMS phone setup to single setup.sh script
Replaced multi-step manual instructions (heredocs, printf, individual echo commands) with a single convenience script. Users now just clone the repo and run: bash setup.sh YOUR_API_KEY The script handles package install, key config, permissions, Termux:Boot, and starting the server. Updated both the admin wizard and MkDocs docs. Bunker Admin
This commit is contained in:
@@ -58,168 +58,77 @@ Before starting setup, you'll need:
|
||||
|
||||
---
|
||||
|
||||
## Phone Setup Guide
|
||||
## Phone Setup
|
||||
|
||||
### Step 1: Install Apps
|
||||
### Step 1: Install Apps from F-Droid
|
||||
|
||||
On your Android phone:
|
||||
|
||||
1. **Install F-Droid** — download from [f-droid.org](https://f-droid.org) if you don't have it
|
||||
2. **Install Termux** — search in F-Droid and install
|
||||
3. **Install Termux:API** — search in F-Droid and install
|
||||
4. **Install Tailscale** (recommended) — from Play Store, create account, connect to your tailnet
|
||||
|
||||
### Step 2: Set Up Termux
|
||||
|
||||
Open the Termux app on your phone and run:
|
||||
|
||||
```bash
|
||||
# Update package repository and install dependencies
|
||||
pkg update && pkg install python git termux-api openssh -y
|
||||
|
||||
# Install the Flask web framework (used by the SMS server)
|
||||
pip install flask
|
||||
```
|
||||
4. **Install Termux:Boot** (optional) — for auto-start on phone reboot. Open once after install to register.
|
||||
5. **Install Tailscale** (recommended) — from Play Store, connect to your tailnet for a stable IP
|
||||
|
||||
!!! note "termux-api package"
|
||||
The `termux-api` package provides the command-line tools (`termux-sms-send`, `termux-sms-list`, etc.) that bridge to the Termux:API Android app. You need **both** the F-Droid app and this Termux package installed.
|
||||
You need **two things** called "termux-api": the **F-Droid app** (Termux:API) and the **Termux package** (`pkg install termux-api`). The setup script installs the package automatically, but the F-Droid app must be installed manually.
|
||||
|
||||
### Step 3: Clone the SMS Server
|
||||
### Step 2: Generate API Key
|
||||
|
||||
The SMS server code is hosted on your Gitea instance. Clone it directly to the phone:
|
||||
Go to the admin dashboard **SMS Setup** page (`/app/sms/setup`) and click **Generate API Key**. Copy the key — you'll paste it into the setup command.
|
||||
|
||||
### Step 3: Run the Setup Script
|
||||
|
||||
Open Termux on the phone and run:
|
||||
|
||||
```bash
|
||||
# Clone the campaign connector repository
|
||||
git clone https://gitea.bnkops.com/admin/campaign_connector.git ~/sms-server
|
||||
# Clone the SMS server (first time only)
|
||||
pkg install -y git && git clone https://gitea.bnkops.com/admin/campaign_connector.git ~/sms-server
|
||||
|
||||
# Run the setup script — paste your API key at the end
|
||||
bash ~/sms-server/android/setup.sh YOUR_API_KEY_HERE
|
||||
```
|
||||
|
||||
!!! tip "Alternative: Copy just the server file"
|
||||
If git isn't available or you prefer minimal setup, you only need one file:
|
||||
```bash
|
||||
mkdir -p ~/sms-server/android
|
||||
# Copy termux-sms-api-server.py from your server to the phone
|
||||
# via SSH, USB transfer, or paste the contents directly
|
||||
```
|
||||
The setup script automatically:
|
||||
|
||||
### Step 4: Grant Permissions
|
||||
- Installs Python, Flask, termux-api, and openssh
|
||||
- Saves the API key to `~/.bashrc`
|
||||
- Requests SMS and Contacts permissions (tap **Allow** when prompted)
|
||||
- Creates a Termux:Boot auto-start script (if Termux:Boot is installed)
|
||||
- Starts the SMS server with the watchdog (auto-restarts on crash)
|
||||
|
||||
Termux:API needs Android permissions to access SMS, contacts, and other features:
|
||||
When done, note the **Phone URL** displayed (e.g. `http://100.64.0.5:5001`).
|
||||
|
||||
```bash
|
||||
# These commands will trigger Android permission prompts
|
||||
# Tap "Allow" when prompted
|
||||
termux-sms-list # Triggers SMS permission
|
||||
termux-contact-list # Triggers Contacts permission
|
||||
termux-battery-status # Usually auto-granted
|
||||
```
|
||||
### Step 4: Prevent Android from Killing Termux
|
||||
|
||||
If you missed a prompt, go to **Android Settings → Apps → Termux:API → Permissions** and enable SMS and Contacts manually.
|
||||
|
||||
### Step 5: Set the API Key
|
||||
|
||||
Go to the admin dashboard SMS Setup page (`/app/sms/setup`) and click **Generate API Key**. Copy the generated key, then set it in Termux:
|
||||
|
||||
```bash
|
||||
# Replace YOUR_KEY_HERE with the key from the setup wizard
|
||||
export SMS_API_SECRET='YOUR_KEY_HERE'
|
||||
|
||||
# Save it permanently so it survives restarts
|
||||
echo 'export SMS_API_SECRET="YOUR_KEY_HERE"' >> ~/.bashrc
|
||||
```
|
||||
|
||||
### Step 6: Start the Server
|
||||
|
||||
```bash
|
||||
cd ~/sms-server/android
|
||||
python termux-sms-api-server.py
|
||||
```
|
||||
|
||||
You should see output like:
|
||||
|
||||
```
|
||||
🚀 Termux SMS API Server Starting
|
||||
📱 Device IP: 100.64.0.5
|
||||
🌐 API Base URL: http://100.64.0.5:5001
|
||||
🔗 Health Check: http://100.64.0.5:5001/health
|
||||
📞 SMS Endpoint: http://100.64.0.5:5001/api/sms/send
|
||||
```
|
||||
|
||||
Note the **Device IP** — you'll need it for the connection wizard.
|
||||
|
||||
### Step 7: Run Persistently
|
||||
|
||||
By default, the server dies if you close Termux or restart the phone. Here's how to make it survive:
|
||||
|
||||
#### A. Prevent Android from Killing Termux
|
||||
|
||||
This is **required** regardless of which method you use below:
|
||||
This is **required** for the server to run reliably in the background:
|
||||
|
||||
1. Open **Android Settings → Apps → Termux → Battery** → set to **Unrestricted**
|
||||
2. Lock Termux in the recent apps view (long-press the app card → Lock/Pin)
|
||||
3. Samsung phones: also add Termux to **Settings → Device Care → Battery → Never Sleeping Apps**
|
||||
|
||||
#### B. Install Termux:Boot (auto-start on reboot)
|
||||
### Updating
|
||||
|
||||
Install [Termux:Boot](https://f-droid.org/packages/com.termux.boot/) from F-Droid (must be same source as Termux), then open it once to register with Android.
|
||||
|
||||
Run each command one at a time (copy-paste friendly):
|
||||
To pull the latest server code and re-run setup:
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.termux/boot && echo '#!/data/data/com.termux/files/usr/bin/bash' > ~/.termux/boot/start-sms-server
|
||||
echo 'source ~/.bashrc' >> ~/.termux/boot/start-sms-server
|
||||
echo 'termux-wake-lock' >> ~/.termux/boot/start-sms-server
|
||||
echo 'mkdir -p ~/logs' >> ~/.termux/boot/start-sms-server
|
||||
echo 'nohup python ~/sms-server/android/termux-sms-api-server.py >> ~/logs/sms-api.log 2>&1 &' >> ~/.termux/boot/start-sms-server
|
||||
chmod +x ~/.termux/boot/start-sms-server
|
||||
cd ~/sms-server && git pull && bash android/setup.sh YOUR_API_KEY_HERE
|
||||
```
|
||||
|
||||
!!! tip "Why individual echo commands?"
|
||||
Heredocs and `printf` with `\n` are unreliable when copy-pasting to a mobile terminal — the clipboard mangles escape sequences or adds trailing whitespace. Individual `echo >>` commands are the most reliable approach for mobile copy-paste.
|
||||
|
||||
#### C. Watchdog (auto-restart on crash)
|
||||
|
||||
The repo includes a watchdog script that monitors the server and restarts it if it crashes:
|
||||
### Manual Control
|
||||
|
||||
```bash
|
||||
# Run the watchdog (it starts the server automatically)
|
||||
cd ~/sms-server/android
|
||||
bash sms-watchdog.sh
|
||||
```
|
||||
|
||||
The watchdog:
|
||||
|
||||
- Acquires a wake lock (`termux-wake-lock`) to prevent Android from sleeping
|
||||
- Checks the server health every 30 seconds
|
||||
- Automatically restarts the server if it's unresponsive
|
||||
- Logs everything to `~/logs/sms-api.log`
|
||||
|
||||
For maximum reliability, use the watchdog as your boot script:
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.termux/boot && echo '#!/data/data/com.termux/files/usr/bin/bash' > ~/.termux/boot/start-sms-server
|
||||
echo 'termux-wake-lock' >> ~/.termux/boot/start-sms-server
|
||||
echo 'cd ~/sms-server/android' >> ~/.termux/boot/start-sms-server
|
||||
echo 'nohup bash sms-watchdog.sh >> ~/logs/watchdog.log 2>&1 &' >> ~/.termux/boot/start-sms-server
|
||||
chmod +x ~/.termux/boot/start-sms-server
|
||||
```
|
||||
|
||||
#### D. Quick Background (simplest)
|
||||
|
||||
If you just want to background the server without persistence:
|
||||
|
||||
```bash
|
||||
# Start in background
|
||||
termux-wake-lock
|
||||
nohup python ~/sms-server/android/termux-sms-api-server.py >> ~/logs/sms-api.log 2>&1 &
|
||||
|
||||
# Check if it's running
|
||||
# Check if the server is running
|
||||
curl http://127.0.0.1:5001/health
|
||||
|
||||
# View logs
|
||||
tail -f ~/logs/sms-api.log
|
||||
|
||||
# Stop the server
|
||||
pkill -f termux-sms-api-server.py
|
||||
pkill -f sms-watchdog.sh && pkill -f termux-sms-api-server.py
|
||||
|
||||
# Restart manually
|
||||
cd ~/sms-server/android && bash sms-watchdog.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
Reference in New Issue
Block a user