bamort/RUNTIME_CONFIG_IMPLEMENTATION.md

Runtime Configuration Implementation Summary

What Was Implemented

Enhanced the BaMoRT frontend to support runtime configuration for both desktop (Wails) and web production deployments, eliminating the need to rebuild when changing API URLs.

Architecture

Desktop (Wails)

• Uses Go bindings to read API URL from .env file at runtime
• Method: window['go']['main']['App']['GetAPIBaseURL']()
• Configuration: desktop/.env → API_PORT variable
• No rebuild needed when changing port

Web Production (NEW)

Uses a multi-strategy fallback system:

1. config.json (Priority 1)

   • Loads /config.json from web root
   • Can be modified after deployment
   • Example: {"apiBaseURL": "https://api.yourdomain.com"}

2. Auto-detection (Priority 2)

   • Probes /api/public/version at same origin
   • Works automatically with reverse proxy setups
   • Detects if backend and frontend share same domain

3. VITE_API_URL (Priority 3)

   • Environment variable at build time
   • Used for development: VITE_API_URL=http://localhost:8180

4. Same Origin Fallback (Priority 4)

   • Uses window.location.origin
   • Assumes backend and frontend on same domain

Files Modified

Core Implementation

• /data/dev/bamort/frontend/src/utils/config.js - Enhanced with multi-strategy config loading
• /data/dev/bamort/frontend/src/utils/api.js - Uses dynamic baseURL (already done for desktop)
• /data/dev/bamort/desktop/main.go - GetAPIBaseURL() Go binding (already done for desktop)

Documentation

• /data/dev/bamort/frontend/RUNTIME_CONFIG.md - Complete web configuration guide
• /data/dev/bamort/desktop/RUNTIME_CONFIG.md - Desktop configuration guide (existing)

Configuration Files

• /data/dev/bamort/frontend/public/config.json.example - Template for deployment
• /data/dev/bamort/frontend/.gitignore - Excludes public/config.json from git

How It Works

For Web Development

cd frontend
VITE_API_URL=http://localhost:8180 npm run dev

For Web Production Deployment

Option A: Using config.json (Recommended)

# 1. Build once
cd frontend && npm run build

# 2. Deploy dist/ to web server

# 3. Create config.json in web root
cat > /var/www/bamort/config.json <<EOF
{
  "apiBaseURL": "https://api.production.com"
}
EOF

# 4. Change API URL anytime without rebuild!

Option B: Reverse Proxy Setup Example nginx configuration:

server {
    listen 80;
    server_name yourdomain.com;

    # Frontend
    location / {
        root /var/www/bamort;
        try_files $uri $uri/ /index.html;
    }

    # Backend API
    location /api {
        proxy_pass http://localhost:8180;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Frontend auto-detects and uses same origin.

Option C: Build with Embedded URL

VITE_API_URL=https://api.production.com npm run build

(Not recommended - requires rebuild for URL changes)

For Desktop (Wails)

# 1. Build once
cd desktop && wails build

# 2. Change port in .env (no rebuild!)
echo "API_PORT=9000" > desktop/.env

# 3. Run app - uses new port automatically
./desktop/build/bin/bamort

Verification

Open browser console when loading the app. Look for one of these messages:

Desktop:

Desktop app using API URL from config: http://localhost:8185

Web:

Loaded API URL from config.json: https://api.yourdomain.com

or

Detected backend at same origin: https://yourdomain.com

or

Web app using VITE_API_URL: http://localhost:8180

or

Web app using same origin: https://yourdomain.com

Benefits

✅ No rebuild needed for API URL changes in production web deployments
✅ Same build artifact can be deployed to dev/staging/production
✅ Infrastructure-friendly - works with reverse proxies, Docker, static hosting
✅ Flexible - multiple configuration strategies with sensible fallbacks
✅ Dev-friendly - VITE_API_URL still works for development
✅ Desktop-friendly - reads .env at runtime (already implemented)

Testing Checklist

• Frontend builds successfully (npm run build)
• Desktop app reads runtime config from .env
• Web dev mode works with VITE_API_URL
• Web production with config.json works
• Web production with reverse proxy auto-detection works
• Web production with same-origin fallback works

Migration Path

For existing deployments:

1. No changes needed! Current builds continue working
2. To enable runtime config: Just add config.json to your web root
3. Old builds with VITE_API_URL still work as fallback

For new deployments:

1. Build once: npm run build
2. Deploy dist/ contents
3. Add config.json with your API URL
4. Done!