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:

   git clone [repository-url]
   cd TimeSafari
   

2. Install dependencies:

   npm install
   

Web Build

To build for web deployment:

1. Run the production build:

   npm run build
   

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

3. To test the production build locally:

   npm run serve
   

Desktop Build (Electron)

Building for Linux

1. Build the electron app in production mode:

   npm run build:electron-prod
   

2. Package the Electron app for Linux:

   # 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

  chmod +x dist-electron-packages/TimeSafari-*.AppImage
  ./dist-electron-packages/TimeSafari-*.AppImage
  

• DEB: Install and run

  sudo dpkg -i dist-electron-packages/timesafari_*_amd64.deb
  timesafari
  

Development Testing

For testing the Electron build before packaging:

# 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:

   npm run build -- --mode capacitor
   

2. Add iOS platform if not already added:

   npx cap add ios
   

3. Update iOS project with latest build:

   npx cap sync ios
   

4. Open the project in Xcode:

   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:

   npm run build -- --mode capacitor
   

2. Add Android platform if not already added:

   npx cap add android
   

3. Update Android project with latest build:

   npx cap sync android
   

4. Open the project in Android Studio:

   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:

   npm run dev
   

PyWebView Desktop Build

Prerequisites

• Python 3.8 or higher
• pip (Python package manager)
• virtualenv (recommended)
• System dependencies:

  # 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):

   python -m venv .venv
   source .venv/bin/activate  # On Linux/macOS
   # or
   .venv\Scripts\activate     # On Windows
   

2. Install Python dependencies:

   pip install -r requirements.txt
   

Troubleshooting

If encountering PyInstaller version errors:

# Try installing the latest stable version
pip install --upgrade pyinstaller

Development

1. Start the PyWebView development build:

   npm run pywebview:dev
   

Building for Distribution

Linux

npm run pywebview:package-linux

The packaged application will be in dist/TimeSafari

Windows

npm run pywebview:package-win

The packaged application will be in dist/TimeSafari

macOS

npm run pywebview:package-mac

The packaged application will be in dist/TimeSafari

Testing

Run local tests:

npm run test-local

Run all tests (includes building):

npm run test-all

Linting

Check code style:

npm run lint

Fix code style issues:

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:

   git tag <VERSION_TAG>
   git push origin <VERSION_TAG>
   

4. After deployment, update package.json with next version + "-beta"

Test Server

# 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

# 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/

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