Add custom API IP support for Android physical device development

Implement --api-ip parameter for Android builds with smart defaults: - Defaults to 10.0.2.2 for emulator development when no IP specified - Supports custom IP for physical device development - Added npm scripts for common use cases (dev:custom, test:custom) - Updated help documentation with usage examples - Created comprehensive documentation with troubleshooting guide Usage: ./scripts/build-android.sh --dev # Default 10.0.2.2 ./scripts/build-android.sh --dev --api-ip 192.168.1.100 # Custom IP
1 week ago · 1d6418b02c
3 changed files with 320 additions and 5 deletions
--- a/docs/build-system/platforms/android-custom-api-ip.md
+++ b/docs/build-system/platforms/android-custom-api-ip.md
@ -0,0 +1,284 @@
+# Android Custom API IP Configuration
+
+**Author**: Matthew Raymer  
+**Date**: 2025-01-27  
+**Status**: ✅ **COMPLETE** - Custom API IP support for physical device development
+
+## Overview
+
+When deploying TimeSafari to physical Android devices during development, you may need to specify a custom IP address for the claim API server. This is necessary because physical devices cannot access `localhost` or `10.0.2.2` (Android emulator IP) to reach your local development server.
+
+## Problem
+
+During Android development:
+- **Emulator**: Uses `10.0.2.2:3000` to access host machine's localhost (default)
+- **Physical Device**: Cannot access `localhost` or `10.0.2.2` - needs actual IP address
+
+## Solution
+
+The Android build system defaults to `10.0.2.2:3000` for emulator development and supports specifying a custom IP address for the claim API server when building for physical devices.
+
+## Usage
+
+### Command Line Usage
+
+```bash
+# Default behavior (uses 10.0.2.2 for emulator)
+./scripts/build-android.sh --dev
+
+# Custom IP for physical device
+./scripts/build-android.sh --dev --api-ip 192.168.1.100
+
+# Test environment with custom IP
+./scripts/build-android.sh --test --api-ip 192.168.1.100
+
+# Build and auto-run with custom IP
+./scripts/build-android.sh --dev --api-ip 192.168.1.100 --auto-run
+```
+
+### NPM Scripts
+
+```bash
+# Default development build (uses 10.0.2.2 for emulator)
+npm run build:android:dev
+
+# Development build with custom IP (requires IP parameter)
+npm run build:android:dev:custom 192.168.1.100
+
+# Test build with custom IP (requires IP parameter)
+npm run build:android:test:custom 192.168.1.100
+
+# Development build + auto-run with custom IP
+npm run build:android:dev:run:custom 192.168.1.100
+
+# Test build + auto-run with custom IP
+npm run build:android:test:run:custom 192.168.1.100
+```
+
+## Examples
+
+### Scenario 1: Development on Emulator (Default)
+
+```bash
+# Default behavior - uses 10.0.2.2 for emulator
+npm run build:android:dev
+
+# Build and immediately run on emulator
+npm run build:android:dev:run
+```
+
+### Scenario 2: Development on Physical Device
+
+```bash
+# Your development server is running on 192.168.1.50:3000
+npm run build:android:dev:custom 192.168.1.50
+
+# Build and immediately run on device
+npm run build:android:dev:run:custom 192.168.1.50
+```
+
+### Scenario 3: Testing on Physical Device
+
+```bash
+# Your test server is running on 192.168.1.75:3000
+npm run build:android:test:custom 192.168.1.75
+
+# Build and immediately run on device
+npm run build:android:test:run:custom 192.168.1.75
+```
+
+### Scenario 4: Direct Script Usage
+
+```bash
+# Default behavior (emulator)
+./scripts/build-android.sh --dev --studio
+
+# Custom IP for physical device
+./scripts/build-android.sh --dev --api-ip 192.168.1.100 --studio
+./scripts/build-android.sh --test --api-ip 192.168.1.100 --apk
+```
+
+## How It Works
+
+### Environment Variable Override
+
+The build system handles API server configuration as follows:
+
+1. **Default behavior**: Uses `http://10.0.2.2:3000` for emulator development
+2. **Custom IP specified**: Overrides with `http://<custom-ip>:3000` for physical device development
+3. **Maintains other APIs**: Image and Partner APIs remain at production URLs
+4. **Logs the configuration**: Shows which IP is being used in build logs
+
+### Build Process
+
+```bash
+# Development mode with default IP (10.0.2.2)
+export VITE_DEFAULT_ENDORSER_API_SERVER="http://10.0.2.2:3000"
+npm run build:capacitor -- --mode development
+
+# Development mode with custom IP
+export VITE_DEFAULT_ENDORSER_API_SERVER="http://192.168.1.100:3000"
+npm run build:capacitor -- --mode development
+```
+
+### Default Behavior
+
+- **No `--api-ip` specified**: Uses default emulator IP (`10.0.2.2:3000`)
+- **Custom IP specified**: Uses provided IP address for physical device development
+- **Invalid IP format**: Build will fail with clear error message
+- **Network unreachable**: App will show connection errors at runtime
+
+## Finding Your IP Address
+
+### On Linux/macOS
+
+```bash
+# Find your local IP address
+ifconfig | grep "inet " | grep -v 127.0.0.1
+# or
+ip addr show | grep "inet " | grep -v 127.0.0.1
+```
+
+### On Windows
+
+```bash
+# Find your local IP address
+ipconfig | findstr "IPv4"
+```
+
+### Common Network Patterns
+
+- **Home WiFi**: Usually `192.168.1.x` or `192.168.0.x`
+- **Office Network**: May be `10.x.x.x` or `172.16.x.x`
+- **Mobile Hotspot**: Often `192.168.43.x`
+
+## Troubleshooting
+
+### Common Issues
+
+#### 1. Device Cannot Connect to API
+
+```bash
+# Check if your IP is accessible
+ping 192.168.1.100
+
+# Check if port 3000 is open
+telnet 192.168.1.100 3000
+```
+
+#### 2. Build Fails with Invalid IP
+
+```bash
+# Ensure IP format is correct
+./scripts/build-android.sh --dev --api-ip 192.168.1.100  # ✅ Correct
+./scripts/build-android.sh --dev --api-ip localhost        # ❌ Wrong
+```
+
+#### 3. Firewall Blocking Connection
+
+```bash
+# Check firewall settings
+sudo ufw status  # Ubuntu/Debian
+sudo firewall-cmd --list-all  # CentOS/RHEL
+```
+
+### Debug Mode
+
+```bash
+# Enable verbose logging
+./scripts/build-android.sh --dev --api-ip 192.168.1.100 --verbose
+```
+
+## Best Practices
+
+### 1. Use Consistent IP Addresses
+
+```bash
+# Create aliases for common development scenarios
+alias build-dev="npm run build:android:dev:custom 192.168.1.100"
+alias build-test="npm run build:android:test:custom 192.168.1.100"
+```
+
+### 2. Document Your Setup
+
+```bash
+# Create a development setup file
+echo "DEV_API_IP=192.168.1.100" > .env.development
+echo "TEST_API_IP=192.168.1.100" >> .env.development
+```
+
+### 3. Network Security
+
+- Ensure your development server is only accessible on your local network
+- Use HTTPS in production environments
+- Consider VPN for remote development scenarios
+
+### 4. Team Development
+
+```bash
+# Share IP configuration with team
+# Add to .env.example
+DEV_API_IP=192.168.1.100
+TEST_API_IP=192.168.1.100
+```
+
+## Integration with CI/CD
+
+### Environment Variables
+
+```yaml
+# Example CI/CD configuration
+variables:
+  DEV_API_IP: "192.168.1.100"
+  TEST_API_IP: "192.168.1.100"
+
+build:
+  script:
+    - npm run build:android:dev:custom $DEV_API_IP
+```
+
+### Automated Testing
+
+```bash
+# Test with different IP configurations
+npm run build:android:test:custom 192.168.1.100
+npm run build:android:test:custom 10.0.0.100
+```
+
+## Migration from Legacy
+
+### Previous Workarounds
+
+Before this feature, developers had to:
+1. Manually edit environment files
+2. Use different build configurations
+3. Modify source code for IP addresses
+
+### New Approach
+
+```bash
+# Simple one-liner
+npm run build:android:dev:custom 192.168.1.100
+```
+
+## Future Enhancements
+
+### Planned Features
+
+1. **IP Validation**: Automatic IP format validation
+2. **Network Discovery**: Auto-detect available IP addresses
+3. **Port Configuration**: Support for custom ports
+4. **Multiple APIs**: Support for custom IPs for all API endpoints
+
+### Integration Opportunities
+
+1. **Docker Integration**: Automatic IP detection in containerized environments
+2. **Network Profiles**: Save and reuse common network configurations
+3. **Hot Reload**: Automatic rebuild when IP changes
+
+---
+
+**Status**: Complete and ready for production use  
+**Last Updated**: 2025-01-27  
+**Version**: 1.0  
+**Maintainer**: Matthew Raymer 
--- a/package.json
+++ b/package.json
@ -104,7 +104,11 @@
    "build:android:clean": "./scripts/build-android.sh --clean",
    "build:android:sync": "./scripts/build-android.sh --sync",
    "build:android:assets": "./scripts/build-android.sh --assets",
-    "build:android:deploy": "./scripts/build-android.sh --deploy"
+    "build:android:deploy": "./scripts/build-android.sh --deploy",
+    "build:android:dev:custom": "./scripts/build-android.sh --dev --api-ip",
+    "build:android:test:custom": "./scripts/build-android.sh --test --api-ip",
+    "build:android:dev:run:custom": "./scripts/build-android.sh --dev --api-ip --auto-run",
+    "build:android:test:run:custom": "./scripts/build-android.sh --test --api-ip --auto-run"
  },
  "dependencies": {
    "@capacitor-community/electron": "^5.0.1",
--- a/scripts/build-android.sh
+++ b/scripts/build-android.sh
@ -60,12 +60,16 @@ SYNC_ONLY=false
 ASSETS_ONLY=false
 DEPLOY_APP=false
 AUTO_RUN=false
+CUSTOM_API_IP=""

 # Function to parse Android-specific arguments
 parse_android_args() {
    local args=("$@")
+    local i=0
+    
+    while [ $i -lt ${#args[@]} ]; do
+        local arg="${args[$i]}"
        
-    for arg in "${args[@]}"; do
        case $arg in
            --dev|--development)
                BUILD_MODE="development"
@ -106,6 +110,18 @@ parse_android_args() {
            --auto-run)
                AUTO_RUN=true
                ;;
+            --api-ip)
+                if [ $((i + 1)) -lt ${#args[@]} ]; then
+                    CUSTOM_API_IP="${args[$((i + 1))]}"
+                    i=$((i + 1))  # Skip the next argument
+                else
+                    log_error "Error: --api-ip requires an IP address"
+                    exit 1
+                fi
+                ;;
+            --api-ip=*)
+                CUSTOM_API_IP="${arg#*=}"
+                ;;
            -h|--help)
                print_android_usage
                exit 0
@ -117,6 +133,7 @@ parse_android_args() {
                log_warn "Unknown argument: $arg"
                ;;
        esac
+        i=$((i + 1))
    done
 }

@ -138,6 +155,7 @@ print_android_usage() {
    echo "  --assets                Generate assets only"
    echo "  --deploy                Deploy APK to connected device"
    echo "  --auto-run              Auto-run app after build"
+    echo "  --api-ip <ip>          Custom IP address for claim API (defaults to 10.0.2.2)"
    echo ""
    echo "Common Options:"
    echo "  -h, --help             Show this help message"
@ -151,6 +169,8 @@ print_android_usage() {
    echo "  $0 --clean             # Clean only"
    echo "  $0 --sync              # Sync only"
    echo "  $0 --deploy            # Build and deploy to device"
+    echo "  $0 --dev                    # Dev build with default 10.0.2.2"
+    echo "  $0 --dev --api-ip 192.168.1.100  # Dev build with custom API IP"
    echo ""
 }

@ -166,10 +186,17 @@ log_info "Build type: $BUILD_TYPE"
 # Setup environment for Capacitor build
 setup_build_env "capacitor"

-# Override API server for Android emulator development
+# Override API server for Android development
 if [ "$BUILD_MODE" = "development" ]; then
+    if [ -n "$CUSTOM_API_IP" ]; then
+        # Use custom IP for physical device development
+        export VITE_DEFAULT_ENDORSER_API_SERVER="http://${CUSTOM_API_IP}:3000"
+        log_info "Android development mode: Using custom IP ${CUSTOM_API_IP} for physical device"
+    else
+        # Use default emulator IP (10.0.2.2) for Android development
        export VITE_DEFAULT_ENDORSER_API_SERVER="http://10.0.2.2:3000"
-    log_debug "Android development mode: Using 10.0.2.2 for emulator, production for Image/Partner APIs"
+        log_debug "Android development mode: Using default 10.0.2.2 for emulator"
+    fi
 fi

 # Setup application directories