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. First build the web assets:

   npm run build
   

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:

npm run electron:dev

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
   

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

Development

Create a .env.development file:

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:

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

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

Version Management

1. Update CHANGELOG.md with new changes
2. Update version in package.json
3. Commit changes and tag release:

   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