admin/src/pages/sms/SmsSetupPage.tsx

@@ -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 F-Droid Apps */}
+              {/* Part 1: Install Apps */}
               <Alert
                 type="error"
                 showIcon
                 icon={<AndroidOutlined />}
-                message="Step 1 — Install Apps from F-Droid"
+                message="Step 1 — Install Apps on Android"
                 description={
                   <div>
                     <Paragraph>
@@ -315,35 +315,56 @@ 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.
+                        If you have Termux from the Play Store, uninstall it first and reinstall from F-Droid.
                       </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)</Text>
+                        <br /><Text type="secondary">Install from <Text strong>F-Droid</Text> (f-droid.org). If already installed from Play Store, uninstall it first.</Text>
                       </li>
                       <li>
-                        <Text strong>Termux:API</Text> — gives Termux access to SMS, contacts, battery
+                        <Text strong>Termux:API</Text> — gives Termux access to SMS, contacts, battery, GPS
-                        <br /><Text type="secondary">Also from <Text strong>F-Droid</Text>. Must be same source as Termux.</Text>
+                        <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>
                       </li>
                       <li>
-                        <Text strong>Termux:Boot</Text> (optional) — auto-start server on phone reboot
+                        <Text strong>Tailscale</Text> — VPN mesh for stable IP addressing (recommended)
-                        <br /><Text type="secondary">Also from <Text strong>F-Droid</Text>. Open once after install to register.</Text>
+                        <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>
-                      </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: Generate API Key */}
+              {/* Part 2: Termux Setup */}
-              <Divider>Step 2 — Generate API Key</Divider>
+              <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>
               <Paragraph>
-                Generate a shared secret key. The setup script on the phone will use this to authenticate with the server.
+                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.
               </Paragraph>
 
               <Space>
@@ -380,7 +401,7 @@ export default function SmsSetupPage() {
                             message.success('Copied to clipboard');
                           }}
                         >
-                          Copy Key
+                          Copy
                         </Button>
                       </Space>
 
@@ -389,67 +410,64 @@ 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 3: Run setup script */}
+              {/* Part 4: Start the server */}
               {generatedKey && (
                 <Alert
                   type="info"
                   showIcon
                   icon={<RocketOutlined />}
-                  message="Step 3 — Run Setup on Phone"
+                  message="Step 4 — Start the SMS Server"
                   description={
                     <div>
-                      <Paragraph>
+                      <Paragraph>With the API key set, start the Flask server:</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="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="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="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 }}>
-                        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.
+                        You should see output like: <Text code>Termux SMS API Server Starting</Text> with the device IP and port 5001.
                       </Paragraph>
                       <Divider style={{ margin: '12px 0' }} />
-                      <Paragraph type="secondary" style={{ marginBottom: 0 }}>
+                      <Paragraph strong>To keep it running permanently:</Paragraph>
-                        <Text strong>Also recommended:</Text> Disable battery optimization for Termux — Android Settings → Apps → Termux → Battery → Unrestricted.
+                      <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>
+                      <Paragraph type="secondary" style={{ marginTop: 8, marginBottom: 0 }}>
+                        For auto-start on phone reboot, install <Text strong>Termux:Boot</Text> from F-Droid.
+                        Also disable battery optimization: Android Settings → Apps → Termux → Battery → Unrestricted.
                       </Paragraph>
                     </div>
                   }
                 />
               )}
 
-              {/* Already set up? */}
+              {/* Access methods info */}
-              {generatedKey && (
+              <Alert
-                <Alert
+                type="warning"
-                  type="warning"
+                showIcon
-                  showIcon
+                message="Ways to Access the Phone"
-                  message="Already have the server running?"
+                description={
-                  description={
+                  <div>
-                    <div>
+                    <Paragraph style={{ marginBottom: 4 }}>You can run these commands on the phone via:</Paragraph>
-                      <Paragraph style={{ marginBottom: 4 }}>If you've already set up the phone, you can update the server with:</Paragraph>
+                    <ul style={{ marginLeft: 20, lineHeight: 2 }}>
-                      <div style={{ background: 'rgba(0,0,0,0.1)', padding: 12, borderRadius: 6 }}>
+                      <li><Text strong>Directly on phone</Text> — open the Termux app and type commands</li>
-                        <CmdLine comment="Pull latest code and re-run setup" cmd={`cd ~/sms-server && git pull && bash android/setup.sh ${generatedKey}`} />
+                      <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>
-                      </div>
+                      <li><Text strong>scrcpy</Text> — mirror the phone screen to your computer via USB or WiFi</li>
-                    </div>
+                    </ul>
-                  }
+                  </div>
-                />
+                }
-              )}
+              />
 
               <div style={{ marginTop: 16, display: 'flex', justifyContent: 'flex-end' }}>
                 <Button type="primary" onClick={() => setCurrentStep(1)}>

campaign_connector

@@ -1 +1 @@
-Subproject commit 81fa6c983d49d9fffa7bfa5383897015ef91d9f6
+Subproject commit bd5ab484de1020a6be87315fc054887233ea7220

mkdocs/docs/docs/admin/broadcast/sms.md

@@ -58,77 +58,175 @@ Before starting setup, you'll need:
 
 ---
 
-## Phone Setup
+## Phone Setup Guide
 
-### Step 1: Install Apps from F-Droid
+### Step 1: Install Apps
 
 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 Termux:Boot** (optional) — for auto-start on phone reboot. Open once after install to register.
+4. **Install Tailscale** (recommended) — from Play Store, create account, connect to your tailnet
-5. **Install Tailscale** (recommended) — from Play Store, connect to your tailnet for a stable IP
 
-!!! note "termux-api package"
+### Step 2: Set Up Termux
-    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 2: Generate API Key
+Open the Termux app on your phone and run:
-
-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 SMS server (first time only)
+# Update package repository and install dependencies
-pkg install -y git && git clone https://gitea.bnkops.com/admin/campaign_connector.git ~/sms-server
+pkg update && pkg install python git termux-api openssh -y
 
-# Run the setup script — paste your API key at the end
+# Install the Flask web framework (used by the SMS server)
-bash ~/sms-server/android/setup.sh YOUR_API_KEY_HERE
+pip install flask
 ```
 
-The setup script automatically:
+!!! 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.
 
-- Installs Python, Flask, termux-api, and openssh
+### Step 3: Clone the SMS Server
-- 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)
 
-When done, note the **Phone URL** displayed (e.g. `http://100.64.0.5:5001`).
+The SMS server code is hosted on your Gitea instance. Clone it directly to the phone:
 
-### Step 4: Prevent Android from Killing Termux
+```bash
+# Clone the campaign connector repository
+git clone https://gitea.bnkops.com/admin/campaign_connector.git ~/sms-server
+```
 
-This is **required** for the server to run reliably in the background:
+!!! 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
+    ```
+
+### Step 4: Grant Permissions
+
+Termux:API needs Android permissions to access SMS, contacts, and other features:
+
+```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
+```
+
+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:
 
 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**
 
-### Updating
+#### B. Install Termux:Boot (auto-start on reboot)
 
-To pull the latest server code and re-run setup:
+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.
 
 ```bash
-cd ~/sms-server && git pull && bash android/setup.sh YOUR_API_KEY_HERE
+# Create the boot scripts directory
+mkdir -p ~/.termux/boot
+
+# Create the auto-start script
+cat > ~/.termux/boot/start-sms-server << 'EOF'
+#!/data/data/com.termux/files/usr/bin/sh
+termux-wake-lock
+export SMS_API_SECRET="YOUR_KEY_HERE"
+mkdir -p ~/logs
+nohup python ~/sms-server/android/termux-sms-api-server.py >> ~/logs/sms-api.log 2>&1 &
+EOF
+
+chmod +x ~/.termux/boot/start-sms-server
 ```
 
-### Manual Control
+!!! warning "Replace YOUR_KEY_HERE"
+    Edit the script and replace `YOUR_KEY_HERE` with your actual API key. Or if you've already saved it in `~/.bashrc`, replace the export line with `source ~/.bashrc`.
+
+#### C. Watchdog (auto-restart on crash)
+
+The repo includes a watchdog script that monitors the server and restarts it if it crashes:
 
 ```bash
-# Check if the server is running
+# 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
+cat > ~/.termux/boot/start-sms-server << 'EOF'
+#!/data/data/com.termux/files/usr/bin/sh
+source ~/.bashrc
+nohup bash ~/sms-server/android/sms-watchdog.sh >> ~/logs/sms-watchdog.log 2>&1 &
+EOF
+
+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
 curl http://127.0.0.1:5001/health
 
 # View logs
 tail -f ~/logs/sms-api.log
 
 # Stop the server
-pkill -f sms-watchdog.sh && pkill -f termux-sms-api-server.py
+pkill -f termux-sms-api-server.py
-
-# Restart manually
-cd ~/sms-server/android && bash sms-watchdog.sh
 ```
 
 ---