# 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 for PyWebView - 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 of PyWebView 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 See `.env.*` files for configuration. ## 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 ### Version Management 1. Update CHANGELOG.md with new changes 2. Update version in package.json 3. Commit changes and tag release: ```bash git tag git push origin ``` 4. After deployment, update package.json with next version + "-beta" ### Test Server ```bash # Build using staging environment npm run build -- --mode staging # Deploy to test server rsync -azvu -e "ssh -i ~/.ssh/" 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 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/ ``` ## Troubleshooting Builds ### 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