Desktop app dynamic config of API Port (#40)

* added dynamic configuration of Port in Desktop app * added dynamic configuration of API_URL to docker deployments. Now it works with editing only .env file.
2026-02-27 11:55:30 +01:00
parent bb9ef4f77e
commit 261a6294cb
24 changed files with 597 additions and 55 deletions
@@ -0,0 +1,174 @@
+# 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
+```bash
+cd frontend
+VITE_API_URL=http://localhost:8180 npm run dev
+```
+
+### For Web Production Deployment
+
+**Option A: Using config.json (Recommended)**
+```bash
+# 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:
+```nginx
+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**
+```bash
+VITE_API_URL=https://api.production.com npm run build
+```
+(Not recommended - requires rebuild for URL changes)
+
+### For Desktop (Wails)
+```bash
+# 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
+
+- [x] Frontend builds successfully (`npm run build`)
+- [x] 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!