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