trent_larson
/
crowd-funder-for-time-pwa
4
1
Fork 2
Code Pull Requests 15 Releases 5 Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
3371 Commits
88 Branches
24 Tags
496 MiB
 
 
 
 
 
 
Tree: de47829dc2
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'de47829dc2'
${ noResults }
crowd-funder-for-time-pwa/docs/build-system/platforms/android-custom-api-ip.md

8.8 KiB
Raw Blame History

Mobile 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 mobile development:

  • Android Emulator: Uses 10.0.2.2:3000 to access host machine's localhost (Android emulator default)
  • iOS Simulator: Uses localhost:3000 to access host machine's localhost (iOS simulator default)
  • Physical Devices: Cannot access localhost or 10.0.2.2 - needs actual IP address for network access

Solution

The mobile build system uses platform-appropriate defaults and supports specifying a custom IP address for the claim API server when building for physical devices:

  • Android: Defaults to 10.0.2.2:3000 for emulator development
  • iOS: Uses Capacitor default (localhost:3000) for simulator development

Usage

Command Line Usage

# Android - Default behavior (uses 10.0.2.2 for emulator)
./scripts/build-android.sh --dev

# Android - Custom IP for physical device
./scripts/build-android.sh --dev --api-ip 192.168.1.100

# iOS - Default behavior (uses localhost for simulator)
./scripts/build-ios.sh --dev

# iOS - Custom IP for physical device
./scripts/build-ios.sh --dev --api-ip 192.168.1.100

# Test environment with custom IP
./scripts/build-android.sh --test --api-ip 192.168.1.100
./scripts/build-ios.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
./scripts/build-ios.sh --dev --api-ip 192.168.1.100 --auto-run

NPM Scripts

# Android - Default development build (uses 10.0.2.2 for emulator)
npm run build:android:dev

# Android - Development build with custom IP (requires IP parameter)
npm run build:android:dev:custom 192.168.1.100

# iOS - Default development build (uses localhost for simulator)
npm run build:ios:dev

# iOS - Development build with custom IP (requires IP parameter)
npm run build:ios:dev:custom 192.168.1.100

# Test builds with custom IP (requires IP parameter)
npm run build:android:test:custom 192.168.1.100
npm run build:ios:test:custom 192.168.1.100

# Development build + auto-run with custom IP
npm run build:android:dev:run:custom 192.168.1.100
npm run build:ios: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
npm run build:ios:test:run:custom 192.168.1.100

Examples

Scenario 1: Development on Simulator/Emulator (Default)

# Android - Default behavior - uses 10.0.2.2 for emulator
npm run build:android:dev

# iOS - Default behavior - uses localhost for simulator
npm run build:ios:dev

# Build and immediately run on simulator/emulator
npm run build:android:dev:run
npm run build:ios:dev:run

Scenario 2: Development on Physical Device

# Your development server is running on 192.168.1.50:3000
npm run build:android:dev:custom 192.168.1.50
npm run build:ios:dev:custom 192.168.1.50

# Build and immediately run on device
npm run build:android:dev:run:custom 192.168.1.50
npm run build:ios:dev:run:custom 192.168.1.50

Scenario 3: Testing on Physical Device

# Your test server is running on 192.168.1.75:3000
npm run build:android:test:custom 192.168.1.75
npm run build:ios:test:custom 192.168.1.75

# Build and immediately run on device
npm run build:android:test:run:custom 192.168.1.75
npm run build:ios:test:run:custom 192.168.1.75

Scenario 4: Direct Script Usage

# Default behavior (uses platform-appropriate defaults)
./scripts/build-android.sh --dev --studio
./scripts/build-ios.sh --dev --studio

# Custom IP for physical device
./scripts/build-android.sh --dev --api-ip 192.168.1.100 --studio
./scripts/build-ios.sh --dev --api-ip 192.168.1.100 --studio

How It Works

Environment Variable Override

The build system handles API server configuration as follows:

  1. Android default: Uses Android emulator default (http://10.0.2.2:3000)
  2. iOS default: Uses Capacitor default (http://localhost:3000)
  3. Custom IP specified: Overrides with http://<custom-ip>:3000 for physical device development
  4. Maintains other APIs: Image and Partner APIs remain at production URLs
  5. Logs the configuration: Shows which IP is being used in build logs

Build Process

# Development mode with Android emulator default (10.0.2.2)
export VITE_DEFAULT_ENDORSER_API_SERVER="http://10.0.2.2:3000"
export VITE_DEFAULT_PARTNER_API_SERVER="http://10.0.2.2:3000"
npm run build:capacitor -- --mode development

# Development mode with iOS simulator default (localhost)
export VITE_DEFAULT_ENDORSER_API_SERVER="http://localhost:3000"
export VITE_DEFAULT_PARTNER_API_SERVER="http://localhost:3000"
npm run build:capacitor -- --mode development

# Development mode with custom IP
export VITE_DEFAULT_ENDORSER_API_SERVER="http://192.168.1.100:3000"
export VITE_DEFAULT_PARTNER_API_SERVER="http://192.168.1.100:3000"
npm run build:capacitor -- --mode development

Default Behavior

  • Android (no --api-ip): Uses Android emulator default (10.0.2.2:3000)
  • iOS (no --api-ip): Uses Capacitor default (localhost: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

# 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

# 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

# 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

# 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

# Check firewall settings
sudo ufw status  # Ubuntu/Debian
sudo firewall-cmd --list-all  # CentOS/RHEL

Debug Mode

# Enable verbose logging
./scripts/build-android.sh --dev --api-ip 192.168.1.100 --verbose

Best Practices

1. Use Consistent IP Addresses

# 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

# 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

# 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

# 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

# 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

# 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