From a288496dcf5f2a7647a7279b0d27603bf356d3ee Mon Sep 17 00:00:00 2001
From: Matthew Raymer <matthew.raymer@anomalistdesign.com>
Date: Thu, 13 Feb 2025 04:53:40 +0000
Subject: [PATCH] docs: enhance BUILDING.md with environment and deployment
 details

- Add environment configuration section with .env templates for dev/test/prod
- Add deployment instructions for test and production servers
- Add version management workflow steps
- Add troubleshooting section for common build issues
- Improve documentation organization and completeness
---
 BUILDING.md | 83 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 83 insertions(+)

diff --git a/BUILDING.md b/BUILDING.md
index cfbf732..b507de0 100644
--- a/BUILDING.md
+++ b/BUILDING.md
@@ -143,6 +143,34 @@ Fix code style issues:
 npm run lint-fix
 ```
 
+## Environment Configuration
+
+### Development
+Create a `.env.development` file:
+```bash
+TIME_SAFARI_APP_TITLE="TimeSafari_Dev"
+VITE_APP_SERVER=http://localhost:3000
+VITE_DEFAULT_ENDORSER_API_SERVER=http://localhost:3000
+VITE_DEFAULT_IMAGE_API_SERVER=http://localhost:3000
+VITE_DEFAULT_PARTNER_API_SERVER=http://localhost:3000
+VITE_PASSKEYS_ENABLED=true
+```
+
+### Test/Staging
+Create a `.env.staging` file:
+```bash
+TIME_SAFARI_APP_TITLE="TimeSafari_Test"
+VITE_APP_SERVER=https://test.timesafari.app
+VITE_BVC_MEETUPS_PROJECT_CLAIM_ID=https://endorser.ch/entity/01HWE8FWHQ1YGP7GFZYYPS272F
+VITE_DEFAULT_ENDORSER_API_SERVER=https://test-api.endorser.ch
+VITE_DEFAULT_IMAGE_API_SERVER=https://test-image-api.timesafari.app
+VITE_DEFAULT_PARTNER_API_SERVER=https://test-partner-api.endorser.ch
+VITE_PASSKEYS_ENABLED=true
+```
+
+### Production
+The `.env.production` file will be used automatically for production builds.
+
 ## Notes
 
 - The application uses PWA (Progressive Web App) features for web builds
@@ -152,3 +180,58 @@ npm run lint-fix
   - Electron: `dist-electron/`
   - Capacitor: `dist-capacitor/`
 
+## Deployment
+
+### Test Server
+```bash
+# Build using staging environment
+npm run build -- --mode staging
+
+# Deploy to test server
+rsync -azvu -e "ssh -i ~/.ssh/your_key" dist/ ubuntutest@test.timesafari.app:time-safari/
+```
+
+### Production Server
+```bash
+# On the production server:
+pkgx +npm sh
+cd crowd-funder-for-time-pwa
+git checkout master && git pull
+git checkout <version_tag>
+npm install
+npm run build
+cd -
+
+# Backup and deploy
+mv time-safari/dist time-safari-dist-prev.0
+mv crowd-funder-for-time-pwa/dist time-safari/
+```
+
+### Version Management
+1. Update CHANGELOG.md with new changes
+2. Update version in package.json
+3. Commit changes and tag release:
+   ```bash
+   git tag <version>
+   git push origin <version>
+   ```
+4. After deployment, update package.json with next version + "-beta"
+
+## Troubleshooting
+
+### Common Build Issues
+
+1. **Missing Environment Variables**
+   - Check that all required variables are set in your .env file
+   - For development, ensure local services are running on correct ports
+
+2. **Electron Build Failures**
+   - Verify Node.js version compatibility
+   - Check that all required dependencies are installed
+   - Ensure proper paths in electron/main.js
+
+3. **Mobile Build Issues**
+   - For iOS: Xcode command line tools must be installed
+   - For Android: Correct SDK version must be installed
+   - Check Capacitor configuration in capacitor.config.ts
+