Browse Source
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.get-get-hash
Matthew Raymer
1 week ago
5 changed files with 351 additions and 7 deletions
@ -0,0 +1,338 @@ |
|||||
|
# Environment Variable Precedence and API Configuration |
||||
|
|
||||
|
**Date:** August 4, 2025 |
||||
|
**Author:** Matthew Raymer |
||||
|
|
||||
|
## Overview |
||||
|
|
||||
|
This document explains the order of precedence for environment variables in the |
||||
|
TimeSafari project, how `.env` files are used, and the API configuration scheme |
||||
|
for different environments. |
||||
|
|
||||
|
## Order of Precedence (Highest to Lowest) |
||||
|
|
||||
|
### 1. Shell Script Overrides (Highest Priority) |
||||
|
|
||||
|
Shell scripts can override environment variables for platform-specific needs: |
||||
|
|
||||
|
```bash |
||||
|
# scripts/common.sh - setup_build_env() |
||||
|
if [ "$BUILD_MODE" = "development" ]; then |
||||
|
export VITE_DEFAULT_ENDORSER_API_SERVER="http://localhost:3000" |
||||
|
export VITE_DEFAULT_PARTNER_API_SERVER="http://localhost:3000" |
||||
|
fi |
||||
|
``` |
||||
|
|
||||
|
### 2. Platform-Specific Overrides (High Priority) |
||||
|
|
||||
|
Platform-specific build scripts can override for mobile development: |
||||
|
|
||||
|
```bash |
||||
|
# scripts/build-android.sh |
||||
|
if [ "$BUILD_MODE" = "development" ]; then |
||||
|
export VITE_DEFAULT_ENDORSER_API_SERVER="http://10.0.2.2:3000" |
||||
|
export VITE_DEFAULT_PARTNER_API_SERVER="http://10.0.2.2:3000" |
||||
|
fi |
||||
|
``` |
||||
|
|
||||
|
### 3. Environment-Specific .env Files (Medium Priority) |
||||
|
|
||||
|
Environment-specific `.env` files provide environment-specific defaults: |
||||
|
|
||||
|
```bash |
||||
|
# .env.development, .env.test, .env.production |
||||
|
VITE_DEFAULT_ENDORSER_API_SERVER=http://localhost:3000 |
||||
|
VITE_DEFAULT_PARTNER_API_SERVER=http://localhost:3000 |
||||
|
``` |
||||
|
|
||||
|
### 4. Fallback .env File (Low Priority) |
||||
|
|
||||
|
General `.env` file provides project-wide defaults: |
||||
|
|
||||
|
```bash |
||||
|
# .env (if exists) |
||||
|
VITE_DEFAULT_ENDORSER_API_SERVER=http://localhost:3000 |
||||
|
``` |
||||
|
|
||||
|
### 5. app.ts Constants (Lowest Priority - Fallback) |
||||
|
|
||||
|
Hardcoded constants in `src/constants/app.ts` provide safety nets: |
||||
|
|
||||
|
```typescript |
||||
|
export const DEFAULT_ENDORSER_API_SERVER = |
||||
|
import.meta.env.VITE_DEFAULT_ENDORSER_API_SERVER || |
||||
|
AppString.PROD_ENDORSER_API_SERVER; |
||||
|
``` |
||||
|
|
||||
|
## Build Process Flow |
||||
|
|
||||
|
### 1. Shell Scripts Set Base Values |
||||
|
|
||||
|
```bash |
||||
|
# scripts/common.sh |
||||
|
setup_build_env() { |
||||
|
if [ "$BUILD_MODE" = "development" ]; then |
||||
|
export VITE_DEFAULT_ENDORSER_API_SERVER="http://localhost:3000" |
||||
|
export VITE_DEFAULT_PARTNER_API_SERVER="http://localhost:3000" |
||||
|
fi |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
### 2. Platform-Specific Overrides |
||||
|
|
||||
|
```bash |
||||
|
# scripts/build-android.sh |
||||
|
if [ "$BUILD_MODE" = "development" ]; then |
||||
|
export VITE_DEFAULT_ENDORSER_API_SERVER="http://10.0.2.2:3000" |
||||
|
export VITE_DEFAULT_PARTNER_API_SERVER="http://10.0.2.2:3000" |
||||
|
fi |
||||
|
``` |
||||
|
|
||||
|
### 3. Load .env Files |
||||
|
|
||||
|
```bash |
||||
|
# scripts/build-web.sh |
||||
|
local env_file=".env.$BUILD_MODE" # .env.development, .env.test, .env.production |
||||
|
if [ -f "$env_file" ]; then |
||||
|
load_env_file "$env_file" |
||||
|
fi |
||||
|
|
||||
|
# Fallback to .env |
||||
|
if [ -f ".env" ]; then |
||||
|
load_env_file ".env" |
||||
|
fi |
||||
|
``` |
||||
|
|
||||
|
### 4. Vite Processes Environment |
||||
|
|
||||
|
```typescript |
||||
|
// vite.config.common.mts |
||||
|
dotenv.config(); // Loads .env files |
||||
|
``` |
||||
|
|
||||
|
### 5. Application Uses Values |
||||
|
|
||||
|
```typescript |
||||
|
// src/constants/app.ts |
||||
|
export const DEFAULT_ENDORSER_API_SERVER = |
||||
|
import.meta.env.VITE_DEFAULT_ENDORSER_API_SERVER || |
||||
|
AppString.PROD_ENDORSER_API_SERVER; |
||||
|
``` |
||||
|
|
||||
|
## API Configuration Scheme |
||||
|
|
||||
|
### Environment Configuration Summary |
||||
|
|
||||
|
| Environment | Endorser API (Claims) | Partner API | Image API | |
||||
|
|-------------|----------------------|-------------|-----------| |
||||
|
| **Development** | `http://localhost:3000` | `http://localhost:3000` | `https://image-api.timesafari.app` | |
||||
|
| **Test** | `https://test-api.endorser.ch` | `https://test-partner-api.endorser.ch` | `https://image-api.timesafari.app` | |
||||
|
| **Production** | `https://api.endorser.ch` | `https://partner-api.endorser.ch` | `https://image-api.timesafari.app` | |
||||
|
|
||||
|
### Mobile Development Overrides |
||||
|
|
||||
|
#### Android Development |
||||
|
|
||||
|
- **Emulator**: `http://10.0.2.2:3000` (Android emulator default) |
||||
|
- **Physical Device**: `http://{CUSTOM_IP}:3000` (Custom IP for physical device) |
||||
|
|
||||
|
#### iOS Development |
||||
|
|
||||
|
- **Simulator**: `http://localhost:3000` (iOS simulator default) |
||||
|
- **Physical Device**: `http://{CUSTOM_IP}:3000` (Custom IP for physical device) |
||||
|
|
||||
|
## .env File Structure |
||||
|
|
||||
|
### .env.development |
||||
|
```bash |
||||
|
# ========================================== |
||||
|
# DEVELOPMENT ENVIRONMENT CONFIGURATION |
||||
|
# ========================================== |
||||
|
# API Server Configuration: |
||||
|
# - Endorser API (Claims): Local development server |
||||
|
# - Partner API: Local development server (aligned with claims) |
||||
|
# - Image API: Test server (shared for development) |
||||
|
# ========================================== |
||||
|
|
||||
|
# Only the variables that start with VITE_ are seen in the application import.meta.env in Vue. |
||||
|
|
||||
|
# iOS doesn't like spaces in the app title. |
||||
|
TIME_SAFARI_APP_TITLE="TimeSafari_Dev" |
||||
|
VITE_APP_SERVER=http://localhost:8080 |
||||
|
|
||||
|
# This is the claim ID for actions in the BVC project, with the JWT ID on this environment (not production). |
||||
|
VITE_BVC_MEETUPS_PROJECT_CLAIM_ID=https://endorser.ch/entity/01HWE8FWHQ1YGP7GFZYYPS272F |
||||
|
|
||||
|
# API Servers (Development - Local) |
||||
|
VITE_DEFAULT_ENDORSER_API_SERVER=http://localhost:3000 |
||||
|
VITE_DEFAULT_PARTNER_API_SERVER=http://localhost:3000 |
||||
|
|
||||
|
# Image API (Test server for development) |
||||
|
VITE_DEFAULT_IMAGE_API_SERVER=https://test-image-api.timesafari.app |
||||
|
|
||||
|
# Push Server (disabled for localhost) |
||||
|
#VITE_DEFAULT_PUSH_SERVER... can't be set up with localhost domain |
||||
|
|
||||
|
# Feature Flags |
||||
|
VITE_PASSKEYS_ENABLED=true |
||||
|
``` |
||||
|
|
||||
|
### .env.test |
||||
|
```bash |
||||
|
# ========================================== |
||||
|
# TEST ENVIRONMENT CONFIGURATION |
||||
|
# ========================================== |
||||
|
# API Server Configuration: |
||||
|
# - Endorser API (Claims): Test server |
||||
|
# - Partner API: Test server (aligned with claims) |
||||
|
# - Image API: Test server |
||||
|
# ========================================== |
||||
|
|
||||
|
# Only the variables that start with VITE_ are seen in the application import.meta.env in Vue. |
||||
|
|
||||
|
# iOS doesn't like spaces in the app title. |
||||
|
TIME_SAFARI_APP_TITLE="TimeSafari_Test" |
||||
|
VITE_APP_SERVER=https://test.timesafari.app |
||||
|
|
||||
|
# This is the claim ID for actions in the BVC project, with the JWT ID on this environment (not production). |
||||
|
VITE_BVC_MEETUPS_PROJECT_CLAIM_ID=https://endorser.ch/entity/01HWE8FWHQ1YGP7GFZYYPS272F |
||||
|
|
||||
|
# API Servers (Test Environment) |
||||
|
VITE_DEFAULT_ENDORSER_API_SERVER=https://test-api.endorser.ch |
||||
|
VITE_DEFAULT_PARTNER_API_SERVER=https://test-partner-api.endorser.ch |
||||
|
|
||||
|
# Image API (Test server) |
||||
|
VITE_DEFAULT_IMAGE_API_SERVER=https://test-image-api.timesafari.app |
||||
|
|
||||
|
# Push Server (Test) |
||||
|
VITE_DEFAULT_PUSH_SERVER=https://test.timesafari.app |
||||
|
|
||||
|
# Feature Flags |
||||
|
VITE_PASSKEYS_ENABLED=true |
||||
|
``` |
||||
|
|
||||
|
### .env.production |
||||
|
```bash |
||||
|
# ========================================== |
||||
|
# PRODUCTION ENVIRONMENT CONFIGURATION |
||||
|
# ========================================== |
||||
|
# API Server Configuration: |
||||
|
# - Endorser API (Claims): Production server |
||||
|
# - Partner API: Production server (aligned with claims) |
||||
|
# - Image API: Production server |
||||
|
# ========================================== |
||||
|
|
||||
|
# Only the variables that start with VITE_ are seen in the application import.meta.env in Vue. |
||||
|
|
||||
|
# App Server |
||||
|
VITE_APP_SERVER=https://timesafari.app |
||||
|
|
||||
|
# This is the claim ID for actions in the BVC project. |
||||
|
VITE_BVC_MEETUPS_PROJECT_CLAIM_ID=https://endorser.ch/entity/01GXYPFF7FA03NXKPYY142PY4H |
||||
|
|
||||
|
# API Servers (Production Environment) |
||||
|
VITE_DEFAULT_ENDORSER_API_SERVER=https://api.endorser.ch |
||||
|
VITE_DEFAULT_PARTNER_API_SERVER=https://partner-api.endorser.ch |
||||
|
|
||||
|
# Image API (Production server) |
||||
|
VITE_DEFAULT_IMAGE_API_SERVER=https://image-api.timesafari.app |
||||
|
|
||||
|
# Push Server (Production) |
||||
|
VITE_DEFAULT_PUSH_SERVER=https://timesafari.app |
||||
|
``` |
||||
|
|
||||
|
## Key Principles |
||||
|
|
||||
|
### 1. API Alignment |
||||
|
- **Partner API** values follow the same pattern as **Claim API** (Endorser API) |
||||
|
- Both APIs use the same environment-specific endpoints |
||||
|
- This ensures consistency across the application |
||||
|
|
||||
|
### 2. Platform Flexibility |
||||
|
- Shell scripts can override for platform-specific needs |
||||
|
- Android emulator uses `10.0.2.2:3000` |
||||
|
- iOS simulator uses `localhost:3000` |
||||
|
- Physical devices use custom IP addresses |
||||
|
|
||||
|
### 3. Environment Isolation |
||||
|
- Each environment has its own `.env` file |
||||
|
- Test environment uses test APIs |
||||
|
- Development environment uses local APIs |
||||
|
- Production environment uses production APIs |
||||
|
|
||||
|
### 4. Safety Nets |
||||
|
- Hardcoded constants in `app.ts` provide fallbacks |
||||
|
- Multiple layers of configuration prevent failures |
||||
|
- Clear precedence order ensures predictable behavior |
||||
|
|
||||
|
## Usage Examples |
||||
|
|
||||
|
### Development Build |
||||
|
```bash |
||||
|
# Uses .env.development + shell script overrides |
||||
|
npm run build:web -- --mode development |
||||
|
``` |
||||
|
|
||||
|
### Test Build |
||||
|
```bash |
||||
|
# Uses .env.test + shell script overrides |
||||
|
npm run build:web -- --mode test |
||||
|
``` |
||||
|
|
||||
|
### Production Build |
||||
|
```bash |
||||
|
# Uses .env.production + shell script overrides |
||||
|
npm run build:web -- --mode production |
||||
|
``` |
||||
|
|
||||
|
### Android Development |
||||
|
```bash |
||||
|
# Uses .env.development + Android-specific overrides |
||||
|
./scripts/build-android.sh --dev |
||||
|
``` |
||||
|
|
||||
|
### iOS Development |
||||
|
```bash |
||||
|
# Uses .env.development + iOS-specific overrides |
||||
|
./scripts/build-ios.sh --dev |
||||
|
``` |
||||
|
|
||||
|
## Troubleshooting |
||||
|
|
||||
|
### Environment Variable Debugging |
||||
|
```bash |
||||
|
# Show current environment variables |
||||
|
./scripts/build-web.sh --env |
||||
|
|
||||
|
# Check specific variable |
||||
|
echo $VITE_DEFAULT_ENDORSER_API_SERVER |
||||
|
``` |
||||
|
|
||||
|
### Common Issues |
||||
|
|
||||
|
1. **Wrong API Server**: Check if shell script overrides are correct |
||||
|
2. **Missing .env File**: Ensure environment-specific .env file exists |
||||
|
3. **Platform-Specific Issues**: Verify platform overrides in build scripts |
||||
|
4. **Vite Not Loading**: Check if `dotenv.config()` is called |
||||
|
|
||||
|
### Validation |
||||
|
```bash |
||||
|
# Validate environment configuration |
||||
|
npm run test-env |
||||
|
``` |
||||
|
|
||||
|
## Best Practices |
||||
|
|
||||
|
1. **Always use environment-specific .env files** for different environments |
||||
|
2. **Keep shell script overrides minimal** and platform-specific |
||||
|
3. **Document API alignment** in .env file headers |
||||
|
4. **Use hardcoded fallbacks** in `app.ts` for safety |
||||
|
5. **Test all environments** before deployment |
||||
|
6. **Validate configuration** with test scripts |
||||
|
|
||||
|
## Related Documentation |
||||
|
|
||||
|
- [Build System Overview](../build-system/README.md) |
||||
|
- [Android Custom API IP](../platforms/android-custom-api-ip.md) |
||||
|
- [API Configuration](../api-configuration.md) |
||||
|
- [Environment Setup](../environment-setup.md) |
||||
Loading…
Reference in new issue