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:
parent
5461ebd187
commit
9f9244df32
@ -300,12 +300,12 @@ export default function SmsSetupPage() {
|
||||
{/* Step 0: Phone Preparation */}
|
||||
{currentStep === 0 && (
|
||||
<Space direction="vertical" size="middle" style={{ width: '100%' }}>
|
||||
{/* Part 1: Install Apps */}
|
||||
{/* Part 1: Install F-Droid Apps */}
|
||||
<Alert
|
||||
type="error"
|
||||
showIcon
|
||||
icon={<AndroidOutlined />}
|
||||
message="Step 1 — Install Apps on Android"
|
||||
message="Step 1 — Install Apps from F-Droid"
|
||||
description={
|
||||
<div>
|
||||
<Paragraph>
|
||||
@ -315,56 +315,35 @@ export default function SmsSetupPage() {
|
||||
<br />
|
||||
<Text type="secondary">
|
||||
The Play Store version of Termux is abandoned and incompatible with the API plugin.
|
||||
If you have Termux from the Play Store, uninstall it first and reinstall from F-Droid.
|
||||
If you have Termux from the Play Store, uninstall it first.
|
||||
</Text>
|
||||
</Paragraph>
|
||||
<ol style={{ marginLeft: 20, lineHeight: 2.4 }}>
|
||||
<li>
|
||||
<Text strong>Termux</Text> — terminal emulator for Android
|
||||
<br /><Text type="secondary">Install from <Text strong>F-Droid</Text> (f-droid.org). If already installed from Play Store, uninstall it first.</Text>
|
||||
<br /><Text type="secondary">Install from <Text strong>F-Droid</Text> (f-droid.org)</Text>
|
||||
</li>
|
||||
<li>
|
||||
<Text strong>Termux:API</Text> — gives Termux access to SMS, contacts, battery, GPS
|
||||
<br /><Text type="secondary">Also from <Text strong>F-Droid</Text>. Both apps must come from the same source or SMS commands won't work.</Text>
|
||||
<Text strong>Termux:API</Text> — gives Termux access to SMS, contacts, battery
|
||||
<br /><Text type="secondary">Also from <Text strong>F-Droid</Text>. Must be same source as Termux.</Text>
|
||||
</li>
|
||||
<li>
|
||||
<Text strong>Tailscale</Text> — VPN mesh for stable IP addressing (recommended)
|
||||
<br /><Text type="secondary">Install from Play Store. Creates a persistent 100.x.x.x IP so the server can always reach your phone.</Text>
|
||||
<Text strong>Termux:Boot</Text> (optional) — auto-start server on phone reboot
|
||||
<br /><Text type="secondary">Also from <Text strong>F-Droid</Text>. Open once after install to register.</Text>
|
||||
</li>
|
||||
<li>
|
||||
<Text strong>Tailscale</Text> (recommended) — VPN mesh for stable IP addressing
|
||||
<br /><Text type="secondary">Install from Play Store. Creates a persistent 100.x.x.x IP.</Text>
|
||||
</li>
|
||||
</ol>
|
||||
</div>
|
||||
}
|
||||
/>
|
||||
|
||||
{/* Part 2: Termux Setup */}
|
||||
<Alert
|
||||
type="info"
|
||||
showIcon
|
||||
icon={<ApiOutlined />}
|
||||
message="Step 2 — Set Up Termux"
|
||||
description={
|
||||
<div>
|
||||
<Paragraph>Open Termux on the phone and run each command (tap the copy icon):</Paragraph>
|
||||
<div style={{ background: 'rgba(0,0,0,0.1)', padding: 12, borderRadius: 6 }}>
|
||||
<CmdLine comment="Update packages and install dependencies" cmd="pkg update && pkg install python git termux-api openssh -y" />
|
||||
<CmdLine comment="Install Flask (the SMS server framework)" cmd="pip install flask" />
|
||||
<CmdLine comment="Clone the SMS server from Gitea" cmd="git clone https://gitea.bnkops.com/admin/campaign_connector.git ~/sms-server" />
|
||||
<CmdLine comment="Grant SMS permission (tap Allow when prompted)" cmd="termux-sms-list" />
|
||||
<CmdLine comment="Grant Contacts permission (tap Allow when prompted)" cmd="termux-contact-list" />
|
||||
</div>
|
||||
<Paragraph type="secondary" style={{ marginTop: 8, marginBottom: 0 }}>
|
||||
Tap <Text strong>Allow</Text> when Android asks for SMS and Contacts permissions.
|
||||
If you miss the prompt, go to Android Settings → Apps → Termux:API → Permissions.
|
||||
</Paragraph>
|
||||
</div>
|
||||
}
|
||||
/>
|
||||
|
||||
{/* Part 3: API Key */}
|
||||
<Divider>Step 3 — Generate & Set API Key</Divider>
|
||||
{/* Part 2: Generate API Key */}
|
||||
<Divider>Step 2 — Generate API Key</Divider>
|
||||
<Paragraph>
|
||||
Generate a shared secret key. Both the server and phone use this to authenticate API requests.
|
||||
Click the button below, then paste the key into Termux.
|
||||
Generate a shared secret key. The setup script on the phone will use this to authenticate with the server.
|
||||
</Paragraph>
|
||||
|
||||
<Space>
|
||||
@ -401,7 +380,7 @@ export default function SmsSetupPage() {
|
||||
message.success('Copied to clipboard');
|
||||
}}
|
||||
>
|
||||
Copy
|
||||
Copy Key
|
||||
</Button>
|
||||
</Space>
|
||||
|
||||
@ -410,76 +389,67 @@ export default function SmsSetupPage() {
|
||||
{generatedKey}
|
||||
</pre>
|
||||
)}
|
||||
|
||||
<Divider style={{ margin: '12px 0' }} />
|
||||
<Paragraph strong>Now run these in Termux on the phone:</Paragraph>
|
||||
<div style={{ background: 'rgba(0,0,0,0.1)', padding: 12, borderRadius: 6 }}>
|
||||
<CmdLine comment="Set the API key for this session" cmd={`export SMS_API_SECRET='${generatedKey}'`} />
|
||||
<CmdLine comment="Save permanently so it persists across restarts" cmd={`echo 'export SMS_API_SECRET="${generatedKey}"' >> ~/.bashrc`} />
|
||||
</div>
|
||||
</div>
|
||||
}
|
||||
/>
|
||||
)}
|
||||
|
||||
{/* Part 4: Start the server */}
|
||||
{/* Part 3: Run setup script */}
|
||||
{generatedKey && (
|
||||
<Alert
|
||||
type="info"
|
||||
showIcon
|
||||
icon={<RocketOutlined />}
|
||||
message="Step 4 — Start the SMS Server"
|
||||
message="Step 3 — Run Setup on Phone"
|
||||
description={
|
||||
<div>
|
||||
<Paragraph>With the API key set, start the Flask server:</Paragraph>
|
||||
<Paragraph>
|
||||
Open <Text strong>Termux</Text> on the phone and run these two commands.
|
||||
The setup script handles everything: installs packages, saves the key, requests permissions,
|
||||
configures auto-start, and launches the server.
|
||||
</Paragraph>
|
||||
<div style={{ background: 'rgba(0,0,0,0.1)', padding: 12, borderRadius: 6 }}>
|
||||
<CmdLine comment="Reload .bashrc so the API key is available" cmd="source ~/.bashrc" />
|
||||
<CmdLine comment="Create logs dir and start the SMS API server" cmd="mkdir -p ~/logs && cd ~/sms-server/android && python termux-sms-api-server.py" />
|
||||
<CmdLine comment="Clone the SMS server (first time only)" cmd="pkg install -y git && git clone https://gitea.bnkops.com/admin/campaign_connector.git ~/sms-server" />
|
||||
<CmdLine comment="Run the setup script with your API key" cmd={`bash ~/sms-server/android/setup.sh ${generatedKey}`} />
|
||||
</div>
|
||||
<Paragraph style={{ marginTop: 12 }}>
|
||||
The script will:
|
||||
</Paragraph>
|
||||
<ul style={{ marginLeft: 20, lineHeight: 2 }}>
|
||||
<li>Install Python, Flask, and termux-api</li>
|
||||
<li>Save the API key to ~/.bashrc</li>
|
||||
<li>Request SMS and Contacts permissions (tap <Text strong>Allow</Text>)</li>
|
||||
<li>Set up Termux:Boot auto-start (if installed)</li>
|
||||
<li>Start the server with the watchdog</li>
|
||||
</ul>
|
||||
<Paragraph style={{ marginTop: 8 }}>
|
||||
You should see output like: <Text code>Termux SMS API Server Starting</Text> with the device IP and port 5001.
|
||||
When done, note the <Text strong>Phone URL</Text> displayed (e.g. <Text code>http://100.x.x.x:5001</Text>) — you'll need it in the next step.
|
||||
</Paragraph>
|
||||
<Divider style={{ margin: '12px 0' }} />
|
||||
<Paragraph strong>To keep it running permanently:</Paragraph>
|
||||
<div style={{ background: 'rgba(0,0,0,0.1)', padding: 12, borderRadius: 6 }}>
|
||||
<CmdLine comment="Run the watchdog (auto-restarts server if it crashes)" cmd="nohup bash ~/sms-server/android/sms-watchdog.sh >> ~/logs/sms-watchdog.log 2>&1 &" />
|
||||
</div>
|
||||
<Divider style={{ margin: '12px 0' }} />
|
||||
<Paragraph strong>Auto-start on phone reboot:</Paragraph>
|
||||
<Paragraph type="secondary">
|
||||
Install <Text strong>Termux:Boot</Text> from F-Droid, then run these commands one at a time:
|
||||
</Paragraph>
|
||||
<div style={{ background: 'rgba(0,0,0,0.1)', padding: 12, borderRadius: 6 }}>
|
||||
<CmdLine comment="Create boot dir + first line of script" cmd="mkdir -p ~/.termux/boot && echo '#!/data/data/com.termux/files/usr/bin/bash' > ~/.termux/boot/start-sms-server" />
|
||||
<CmdLine cmd="echo 'termux-wake-lock' >> ~/.termux/boot/start-sms-server" />
|
||||
<CmdLine cmd="echo 'cd ~/sms-server/android' >> ~/.termux/boot/start-sms-server" />
|
||||
<CmdLine cmd="echo 'nohup bash sms-watchdog.sh >> ~/logs/watchdog.log 2>&1 &' >> ~/.termux/boot/start-sms-server" />
|
||||
<CmdLine comment="Make it executable" cmd="chmod +x ~/.termux/boot/start-sms-server" />
|
||||
</div>
|
||||
<Paragraph type="secondary" style={{ marginTop: 8, marginBottom: 0 }}>
|
||||
Also disable battery optimization: Android Settings → Apps → Termux → Battery → Unrestricted.
|
||||
<Paragraph type="secondary" style={{ marginBottom: 0 }}>
|
||||
<Text strong>Also recommended:</Text> Disable battery optimization for Termux — Android Settings → Apps → Termux → Battery → Unrestricted.
|
||||
</Paragraph>
|
||||
</div>
|
||||
}
|
||||
/>
|
||||
)}
|
||||
|
||||
{/* Access methods info */}
|
||||
<Alert
|
||||
type="warning"
|
||||
showIcon
|
||||
message="Ways to Access the Phone"
|
||||
description={
|
||||
<div>
|
||||
<Paragraph style={{ marginBottom: 4 }}>You can run these commands on the phone via:</Paragraph>
|
||||
<ul style={{ marginLeft: 20, lineHeight: 2 }}>
|
||||
<li><Text strong>Directly on phone</Text> — open the Termux app and type commands</li>
|
||||
<li><Text strong>SSH</Text> — run <Text code>sshd</Text> in Termux, then <Text code>ssh -p 8022 phone-ip</Text> from your computer</li>
|
||||
<li><Text strong>scrcpy</Text> — mirror the phone screen to your computer via USB or WiFi</li>
|
||||
</ul>
|
||||
</div>
|
||||
}
|
||||
/>
|
||||
{/* Already set up? */}
|
||||
{generatedKey && (
|
||||
<Alert
|
||||
type="warning"
|
||||
showIcon
|
||||
message="Already have the server running?"
|
||||
description={
|
||||
<div>
|
||||
<Paragraph style={{ marginBottom: 4 }}>If you've already set up the phone, you can update the server with:</Paragraph>
|
||||
<div style={{ background: 'rgba(0,0,0,0.1)', padding: 12, borderRadius: 6 }}>
|
||||
<CmdLine comment="Pull latest code and re-run setup" cmd={`cd ~/sms-server && git pull && bash android/setup.sh ${generatedKey}`} />
|
||||
</div>
|
||||
</div>
|
||||
}
|
||||
/>
|
||||
)}
|
||||
|
||||
<div style={{ marginTop: 16, display: 'flex', justifyContent: 'flex-end' }}>
|
||||
<Button type="primary" onClick={() => setCurrentStep(1)}>
|
||||
|
||||
@ -1 +1 @@
|
||||
Subproject commit bd5ab484de1020a6be87315fc054887233ea7220
|
||||
Subproject commit 81fa6c983d49d9fffa7bfa5383897015ef91d9f6
|
||||
@ -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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user