# Termux Node.js Server Setup Guide

A complete guide to running Node.js servers on Android using Termux, including background services, wake locks, and auto-start configuration.

## Table of Contents

1. [Installing Termux](#1-installing-termux)
2. [Initial Termux Setup](#2-initial-termux-setup)
3. [Installing Node.js](#3-installing-nodejs)
4. [Installing Claude Code](#4-installing-claude-code)
5. [Setting Up Termux Services](#5-setting-up-termux-services)
6. [Creating a Node.js Service](#6-creating-a-nodejs-service)
7. [Managing Services](#7-managing-services)
8. [Background Execution & Wake Lock](#8-background-execution--wake-lock)
9. [Auto-Start on Boot](#9-auto-start-on-boot)
10. [Android Permissions](#10-android-permissions)
11. [Termux:API Integration](#11-termuxapi-integration)
12. [Troubleshooting](#12-troubleshooting)

---

## 1. Installing Termux

### Download from F-Droid (Recommended)

**Do NOT use the Play Store version** - it is outdated and deprecated.

1. Download F-Droid from https://f-droid.org
2. Install F-Droid APK (allow installs from unknown sources when prompted)
3. Open F-Droid and wait for repositories to sync
4. Search for "Termux" and install it
5. Also install **Termux:API** from F-Droid (same source)

> **Warning Dialog:** When installing, Android may show a warning dialog. Look for the **"Install anyway"** text link (usually at the bottom or less prominent). Do NOT tap "Got it" which cancels the install - the "Install anyway" text is intentionally styled to look like plain text, not a button.

> **Important:** All Termux apps must come from the same source. Do not mix F-Droid and Play Store versions.

---

## 2. Initial Termux Setup

### First Launch

Open Termux and wait for the initial setup to complete.

### Update Packages

```bash
pkg update && pkg upgrade -y
```

### Set Up Storage Access

```bash
termux-setup-storage
```

Grant storage permission when prompted. This creates symlinks in `~/storage/` to access device storage:
- `~/storage/shared/` - Internal storage
- `~/storage/dcim/` - Camera photos
- `~/storage/downloads/` - Downloads folder

---

## 3. Installing Node.js

```bash
pkg install nodejs -y
```

Verify installation:
```bash
node --version
npm --version
```

---

## 4. Installing Claude Code

### Install Claude Code CLI

```bash
npm install -g @anthropic-ai/claude-code
```

### Run Claude Code

```bash
claude
```

On first run, you'll need to authenticate with your Anthropic API key or Claude account.

### Usage

Navigate to your project directory and run:
```bash
cd ~/storage/shared/myproject
claude
```

Claude Code provides an AI assistant for coding tasks directly in your terminal.

---

## 5. Setting Up Termux Services

### Install termux-services

```bash
pkg install termux-services -y
```

### Restart Termux

Close and reopen Termux for the service daemon to start, or run:
```bash
source $PREFIX/etc/profile
```

---

## 6. Creating a Node.js Service

### Directory Structure

Services are stored in `$PREFIX/var/service/`. Each service needs a `run` script.

### Create Service Directory

```bash
mkdir -p $PREFIX/var/service/myserver
```

### Create the Run Script

Create `$PREFIX/var/service/myserver/run`:

```bash
#!/data/data/com.termux/files/usr/bin/sh
exec node /path/to/your/server.js 2>&1
```

**Example for photoserver:**
```bash
#!/data/data/com.termux/files/usr/bin/sh
exec node /data/data/com.termux/files/home/storage/shared/sites/geo.camera/apps/photoserver.js 2>&1
```

### Make Executable

```bash
chmod +x $PREFIX/var/service/myserver/run
```

### Enable the Service

```bash
sv-enable myserver
```

---

## 7. Managing Services

### Service Commands

| Command | Description |
|---------|-------------|
| `sv status myserver` | Check if service is running |
| `sv start myserver` | Start the service |
| `sv stop myserver` | Stop the service |
| `sv restart myserver` | Restart the service |
| `sv-enable myserver` | Enable service (starts automatically) |
| `sv-disable myserver` | Disable service |

### View Service Logs

```bash
cat $PREFIX/var/log/sv/myserver/current
```

### List All Services

```bash
ls $PREFIX/var/service/
```

---

## 8. Background Execution & Wake Lock

### The Problem

Android aggressively kills background processes to save battery. Without proper configuration, your server will stop when:
- Screen turns off
- Phone goes to sleep
- Android decides to "optimize" battery

### Acquire Wake Lock

Prevents Android from sleeping Termux:

```bash
termux-wake-lock
```

A persistent notification will appear showing Termux is holding a wake lock.

### Release Wake Lock

```bash
termux-wake-unlock
```

### Verify Wake Lock

Look for the Termux notification with "wake lock held" or similar text.

---

## 9. Auto-Start on Boot

### Option A: Termux:Boot (Recommended)

1. Install **Termux:Boot** from F-Droid
2. Open Termux:Boot once to initialize it
3. Create boot script directory:
   ```bash
   mkdir -p ~/.termux/boot
   ```
4. Create boot script `~/.termux/boot/start-services`:
   ```bash
   #!/data/data/com.termux/files/usr/bin/sh
   termux-wake-lock
   . $PREFIX/etc/profile
   sv-enable myserver
   ```
5. Make executable:
   ```bash
   chmod +x ~/.termux/boot/start-services
   ```

### Option B: Using Tasker or MacroDroid

If Termux:Boot fails to install (common due to signature mismatch between F-Droid versions), use an automation app as an alternative.

#### MacroDroid (Free - Recommended for Simple Setup)

**Install:** Google Play Store (free)

**Setup for Boot Start:**
1. Open MacroDroid
2. Tap **Add Macro**
3. **Trigger:** Select "Device Events" → "Device Boot"
4. **Action:** Select "Applications" → "Launch Application" → Choose "Termux"
5. **Action (optional):** Add "Wait" → 5 seconds, then "Applications" → "Launch Application" → "Termux" (ensures it stays open)
6. Name it "Start Termux on Boot" and save
7. Grant MacroDroid any requested permissions

**Additional useful macros:**
- Launch Termux when connecting to home WiFi
- Launch Termux at a specific time daily

#### Tasker (Paid ~$3.50 - More Powerful)

**Install:** Google Play Store (paid)

**Setup for Boot Start:**
1. Open Tasker
2. Go to **Profiles** tab → Tap **+**
3. Select **Event** → **System** → **Device Boot**
4. Tap back, then **New Task** → Name it "Start Termux"
5. Tap **+** to add action → **App** → **Launch App** → Select "Termux"
6. Tap back to save

**Advanced Tasker features:**
- Run shell commands directly (can call your server APIs)
- Create home screen widgets to control your server
- HTTP Request action to trigger photoserver endpoints
- Location-based triggers (start server when arriving home)
- NFC tag triggers
- Schedule-based automation
- Create custom notification controls

**Example: Tasker widget to capture photo**
1. Create Task "Capture Photo"
2. Add Action: **Net** → **HTTP Request**
   - Method: GET
   - URL: `http://localhost:8080/api/capture?camera=back`
3. Add Task to home screen as widget

#### Why Termux:Boot May Fail

Termux:Boot requires the same cryptographic signature as your Termux installation. If you installed Termux from:
- A different F-Droid repository
- GitHub releases
- An older version with different signing keys

...then Termux:Boot from F-Droid won't install. The workaround is using Tasker/MacroDroid, or uninstalling all Termux apps and reinstalling everything fresh from F-Droid.

### Option C: Manual Start

Simply open Termux after reboot. Enabled services start automatically with Termux.

---

## 10. Android Permissions

### Battery Optimization

**Critical:** Disable battery optimization for all Termux apps.

1. Settings → Apps → Termux → Battery → **Unrestricted**
2. Settings → Apps → Termux:API → Battery → **Unrestricted**
3. Settings → Apps → Termux:Boot → Battery → **Unrestricted**

### Storage Permission

Grant when running `termux-setup-storage` or manually:
- Settings → Apps → Termux → Permissions → Storage → Allow

### Termux:API Permissions

For camera, location, sensors:
- Settings → Apps → Termux:API → Permissions → Enable as needed:
  - Camera
  - Location (Allow all the time for background use)
  - Microphone
  - etc.

---

## 11. Termux:API Integration

### Install Package

```bash
pkg install termux-api
```

### Available Commands

| Command | Description |
|---------|-------------|
| `termux-camera-photo -c 0 photo.jpg` | Take photo (0=back, 1=front) |
| `termux-camera-info` | List cameras |
| `termux-location` | Get GPS location |
| `termux-battery-status` | Battery info |
| `termux-wifi-connectioninfo` | WiFi info |
| `termux-toast "message"` | Show toast notification |
| `termux-vibrate` | Vibrate device |
| `termux-brightness 255` | Set brightness |

### Example: Geotagged Photos

```javascript
const { exec } = require('child_process');

// Get location
exec('termux-location -p network', (err, stdout) => {
  const location = JSON.parse(stdout);
  console.log(location.latitude, location.longitude);
});

// Take photo
exec('termux-camera-photo -c 0 "/path/to/photo.jpg"', (err) => {
  if (!err) console.log('Photo captured');
});
```

---

## 12. Troubleshooting

### Service Not Starting

Check the run script is executable:
```bash
ls -la $PREFIX/var/service/myserver/run
chmod +x $PREFIX/var/service/myserver/run
```

### Port Already in Use

```bash
# Find process using port
lsof -i :8080

# Kill by PID
kill -9 <PID>

# Or kill by name
pkill -f server.js
```

### Server Stops When Screen Off

1. Acquire wake lock: `termux-wake-lock`
2. Disable battery optimization for Termux
3. Check Termux notification shows wake lock is held

### Empty Camera Photos (0 bytes)

Grant camera permission to Termux:API:
- Settings → Apps → Termux:API → Permissions → Camera → Allow

### termux-camera-photo Not Found

Install both the package and app:
```bash
pkg install termux-api
```
Then install Termux:API app from F-Droid.

### Service Logs

```bash
# View logs
cat $PREFIX/var/log/sv/myserver/current

# Follow logs in real-time
tail -f $PREFIX/var/log/sv/myserver/current
```

### Check Running Processes

```bash
ps aux | grep node
```

### Get Local IP Address

```bash
ifconfig wlan0 | grep inet
```

---

## Quick Reference: Setting Up a New Node Server

```bash
# 1. Create your server.js
nano ~/storage/shared/myapp/server.js

# 2. Create service directory
mkdir -p $PREFIX/var/service/myapp

# 3. Create run script
cat > $PREFIX/var/service/myapp/run << 'EOF'
#!/data/data/com.termux/files/usr/bin/sh
exec node /data/data/com.termux/files/home/storage/shared/myapp/server.js 2>&1
EOF

# 4. Make executable
chmod +x $PREFIX/var/service/myapp/run

# 5. Enable service
sv-enable myapp

# 6. Check status
sv status myapp

# 7. Acquire wake lock for background running
termux-wake-lock
```

---

## Modifying Services

To change which server a service runs, edit the run script:

```bash
nano $PREFIX/var/service/myserver/run
```

Change the path to your server file:
```bash
#!/data/data/com.termux/files/usr/bin/sh
exec node /path/to/different/server.js 2>&1
```

Then restart:
```bash
sv restart myserver
```

---

## Example: photoserver.js Service

The photoserver provides HTTP endpoints for camera capture and photo browsing.

### Endpoints

| Endpoint | Description |
|----------|-------------|
| `GET /` | Landing page |
| `GET /gallery` | Photo gallery |
| `GET /api/capture?camera=back` | Capture and save to gallery |
| `GET /api/capture-image?camera=back` | Capture and return image directly |
| `GET /api/photos` | List photos (JSON) |
| `GET /photo/{filename}` | View photo |

### Access from Network

Find your IP:
```bash
ifconfig wlan0 | grep inet
```

Access from other devices: `http://192.168.x.x:8080`