forked from jsnbuchanan/crowd-funder-for-time-pwa
974d33b322
Add comprehensive documentation explaining the order of precedence for environment variables in TimeSafari project. Covers shell script overrides, platform-specific configurations, .env file usage, and API alignment between claim and partner APIs. Includes troubleshooting guide and best practices for maintaining consistent environment configuration across development, test, and production environments.
322 lines
8.8 KiB
Markdown
322 lines
8.8 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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)
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```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 |