forked from jsnbuchanan/crowd-funder-for-time-pwa
1d6418b02c
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
284 lines
7.0 KiB
Markdown
284 lines
7.0 KiB
Markdown
# 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 |