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
This commit is contained in:
Matthew Raymer
284
docs/build-system/platforms/android-custom-api-ip.md
Normal file
284
docs/build-system/platforms/android-custom-api-ip.md
Normal file
@@ -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
|
||||
@@ -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",
|
||||
|
||||
@@ -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 <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
|
||||
|
||||
Reference in New Issue
Block a user