crowd-funder-for-time-pwa/BUILDING.md

# Building TimeSafari

This guide explains how to build TimeSafari for different platforms.

## Prerequisites

- Node.js (LTS version recommended)
- npm (comes with Node.js)
- Git
- For iOS builds: macOS with Xcode installed
- For Android builds: Android Studio with SDK installed
- For desktop builds: Additional build tools based on your OS

## Initial Setup

1. Clone the repository:
   ```bash
   git clone [repository-url]
   cd TimeSafari
   ```

2. Install dependencies:
   ```bash
   npm install
   ```

## Web Build

To build for web deployment:

1. Run the production build:
   ```bash
   npm run build
   ```

2. The built files will be in the `dist` directory.

3. To test the production build locally:
   ```bash
   npm run serve
   ```

## Desktop Build (Electron)

### Building for Linux

1. Build the electron app in production mode:
   ```bash
   npm run build:electron-prod
   ```

2. Package the Electron app for Linux:
   ```bash
   # For AppImage (recommended)
   npm run electron:build-linux

   # For .deb package
   npm run electron:build-linux-deb
   ```

3. The packaged applications will be in `dist-electron-packages/`:
   - AppImage: `dist-electron-packages/TimeSafari-x.x.x.AppImage`
   - DEB: `dist-electron-packages/timesafari_x.x.x_amd64.deb`

### Running the Packaged App

- AppImage: Make executable and run
  ```bash
  chmod +x dist-electron-packages/TimeSafari-*.AppImage
  ./dist-electron-packages/TimeSafari-*.AppImage
  ```

- DEB: Install and run
  ```bash
  sudo dpkg -i dist-electron-packages/timesafari_*_amd64.deb
  timesafari
  ```

### Development Testing

For testing the Electron build before packaging:

```bash
# Build and run in development mode (includes DevTools)
npm run electron:dev

# Build in production mode and test
npm run build:electron-prod && npm run electron:start
```

## Mobile Builds (Capacitor)

### iOS Build

Prerequisites: macOS with Xcode installed

1. Build the web assets:
   ```bash
   npm run build -- --mode capacitor
   ```

2. Add iOS platform if not already added:
   ```bash
   npx cap add ios
   ```

3. Update iOS project with latest build:
   ```bash
   npx cap sync ios
   ```

4. Open the project in Xcode:
   ```bash
   npx cap open ios
   ```

5. Use Xcode to build and run on simulator or device.

### Android Build

Prerequisites: Android Studio with SDK installed

1. Build the web assets:
   ```bash
   npm run build -- --mode capacitor
   ```

2. Add Android platform if not already added:
   ```bash
   npx cap add android
   ```

3. Update Android project with latest build:
   ```bash
   npx cap sync android
   ```

4. Open the project in Android Studio:
   ```bash
   npx cap open android
   ```

5. Use Android Studio to build and run on emulator or device.

## Development

To run the application in development mode:

1. Start the development server:
   ```bash
   npm run dev
   ```
## PyWebView Desktop Build

### Prerequisites
- Python 3.8 or higher
- pip (Python package manager)
- virtualenv (recommended)
- System dependencies:
  ```bash
  # For Ubuntu/Debian
  sudo apt-get install python3-webview
  # or
  sudo apt-get install python3-gi python3-gi-cairo gir1.2-gtk-3.0 gir1.2-webkit2-4.0
  
  # For Arch Linux
  sudo pacman -S webkit2gtk python-gobject python-cairo
  
  # For Fedora
  sudo dnf install python3-webview
  # or
  sudo dnf install python3-gobject python3-cairo webkit2gtk3
  ```

### Setup
1. Create and activate a virtual environment (recommended):
   ```bash
   python -m venv .venv
   source .venv/bin/activate  # On Linux/macOS
   # or
   .venv\Scripts\activate     # On Windows
   ```

2. Install Python dependencies:
   ```bash
   pip install -r requirements.txt
   ```

### Troubleshooting

If encountering PyInstaller version errors:
```bash
# Try installing the latest stable version
pip install --upgrade pyinstaller
```

### Development
1. Start the PyWebView development build:
   ```bash
   npm run pywebview:dev
   ```

### Building for Distribution

#### Linux
```bash
npm run pywebview:package-linux
```
The packaged application will be in `dist/TimeSafari`

#### Windows
```bash
npm run pywebview:package-win
```
The packaged application will be in `dist/TimeSafari`

#### macOS  
```bash
npm run pywebview:package-mac
```
The packaged application will be in `dist/TimeSafari`

## Testing

Run local tests:
```bash
npm run test-local
```

Run all tests (includes building):
```bash
npm run test-all
```

## Linting

Check code style:
```bash
npm run lint
```

Fix code style issues:
```bash
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
- Electron builds disable PWA features automatically
- Build output directories:
  - Web: `dist/`
  - 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