From 1d6418b02c89888e18c478facf80520b9a9979df Mon Sep 17 00:00:00 2001 From: Matthew Raymer Date: Tue, 5 Aug 2025 10:26:38 +0000 Subject: [PATCH] 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 --- .../platforms/android-custom-api-ip.md | 284 ++++++++++++++++++ package.json | 6 +- scripts/build-android.sh | 35 ++- 3 files changed, 320 insertions(+), 5 deletions(-) create mode 100644 docs/build-system/platforms/android-custom-api-ip.md diff --git a/docs/build-system/platforms/android-custom-api-ip.md b/docs/build-system/platforms/android-custom-api-ip.md new file mode 100644 index 00000000..1db748c5 --- /dev/null +++ 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://: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 \ No newline at end of file diff --git a/package.json b/package.json index 758ce227..9ec3b946 100644 --- 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", diff --git a/scripts/build-android.sh b/scripts/build-android.sh index 1e3c4bed..874761ce 100755 --- 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 - for arg in "${args[@]}"; do + while [ $i -lt ${#args[@]} ]; do + local arg="${args[$i]}" + 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 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 - 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" + 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 default 10.0.2.2 for emulator" + fi fi # Setup application directories