diff --git a/electron/README-BUILDING.md b/electron/README-BUILDING.md new file mode 100644 index 00000000..ca1681fa --- /dev/null +++ b/electron/README-BUILDING.md @@ -0,0 +1,251 @@ +# Building TimeSafari Electron App + +This guide explains how to build distributable packages for the TimeSafari Electron desktop application. + +## Quick Start + +### From Project Root +```bash +# Build all Linux packages (AppImage, deb) +npm run electron:build + +# Build specific package types +npm run electron:build:appimage # AppImage only +npm run electron:build:deb # Debian package only +``` + +### From Electron Directory +```bash +cd electron + +# Build all packages +./build-packages.sh + +# Build specific types +./build-packages.sh appimage +./build-packages.sh deb +./build-packages.sh pack # Unpacked directory (for testing) +``` + +## Package Types + +### 1. AppImage (Recommended for Linux) +- **File**: `TimeSafari-1.0.0.AppImage` +- **Size**: ~145MB +- **Usage**: Download and run directly, no installation required +- **Distribution**: Upload to GitHub releases or website + +```bash +# Make executable and run +chmod +x TimeSafari-1.0.0.AppImage +./TimeSafari-1.0.0.AppImage +``` + +### 2. Debian Package (.deb) +- **File**: `TimeSafari_1.0.0_amd64.deb` +- **Size**: ~96MB +- **Usage**: Install via package manager +- **Distribution**: Upload to repositories or direct download + +```bash +# Install +sudo dpkg -i TimeSafari_1.0.0_amd64.deb + +# Run +timesafari +``` + +### 3. RPM Package (.rpm) +- **File**: `TimeSafari-1.0.0.x86_64.rpm` +- **Requirements**: `rpmbuild` must be installed +- **Usage**: Install via package manager + +```bash +# Install rpmbuild (Arch Linux) +sudo pacman -S rpm-tools + +# Build RPM +./build-packages.sh rpm + +# Install (on RPM-based systems) +sudo rpm -i TimeSafari-1.0.0.x86_64.rpm +``` + +## Build Requirements + +### System Dependencies +- Node.js 18+ +- npm or yarn +- Python 3 (for native module compilation) +- Build tools (gcc, make) + +### Optional Dependencies +- `rpmbuild` - for RPM packages +- `fpm` - automatically downloaded by electron-builder + +### Node Dependencies +All required dependencies are in `package.json`: +- `electron-builder` - Main build tool +- `better-sqlite3-multiple-ciphers` - SQLite with encryption +- Native module compilation tools + +## Build Process + +### 1. Preparation +```bash +# Install dependencies +npm install + +# Build TypeScript +npm run build +``` + +### 2. Package Creation +The build process: +1. Compiles TypeScript to JavaScript +2. Rebuilds native modules for Electron +3. Packages the app with electron-builder +4. Creates platform-specific installers + +### 3. Output Location +All built packages are saved to `electron/dist/`: +``` +dist/ +├── TimeSafari-1.0.0.AppImage # Portable AppImage +├── TimeSafari_1.0.0_amd64.deb # Debian package +├── TimeSafari-1.0.0.x86_64.rpm # RPM package (if built) +└── linux-unpacked/ # Unpacked directory +``` + +## Configuration + +### App Metadata +App information is configured in `electron/package.json`: +```json +{ + "name": "TimeSafari", + "version": "1.0.0", + "description": "Time Safari - Community building through gifts, gratitude, and collaborative projects", + "homepage": "https://timesafari.app", + "author": { + "name": "Matthew Raymer", + "email": "matthew@timesafari.app" + } +} +``` + +### Build Configuration +Build settings are in `electron/electron-builder.config.json`: +- Package formats and architectures +- Icons and assets +- Platform-specific settings +- Signing and publishing options + +## Troubleshooting + +### Common Issues + +#### 1. Native Module Compilation Errors +```bash +# Clear cache and rebuild +npm run build +``` + +#### 2. Missing Dependencies +```bash +# Install system dependencies (Arch Linux) +sudo pacman -S base-devel python + +# Install Node dependencies +npm install +``` + +#### 3. RPM Build Fails +```bash +# Install rpmbuild +sudo pacman -S rpm-tools + +# Try building again +./build-packages.sh rpm +``` + +#### 4. Large Package Size +The packages are large (~100-150MB) because they include: +- Complete Electron runtime +- Node.js runtime +- SQLite native modules +- Application assets + +This is normal for Electron applications. + +### Debug Mode +For detailed build information: +```bash +DEBUG=electron-builder npx electron-builder build +``` + +## Distribution + +### GitHub Releases +1. Create a new release on GitHub +2. Upload the built packages as release assets +3. Users can download and install directly + +### Package Repositories +- **Debian/Ubuntu**: Upload `.deb` to repository +- **Fedora/CentOS**: Upload `.rpm` to repository +- **Arch Linux**: Create PKGBUILD for AUR + +### Direct Download +Host the packages on your website for direct download. + +## Cross-Platform Building + +### Current Support +- **Linux**: Full support (AppImage, deb, rpm) +- **Windows**: Configured but requires Windows build environment +- **macOS**: Configured but requires macOS build environment + +### Building for Other Platforms +To build for Windows or macOS, you need: +- The target platform's build environment +- Platform-specific signing certificates +- Updated build configuration + +## Security Considerations + +### Code Signing +For production releases, consider code signing: +- **Linux**: Not required but recommended +- **Windows**: Required for Windows SmartScreen +- **macOS**: Required for Gatekeeper + +### Package Integrity +- Verify package checksums +- Use HTTPS for distribution +- Consider GPG signatures for packages + +## Performance Tips + +### Build Optimization +- Use `--dir` flag for faster development builds +- Cache node_modules between builds +- Use CI/CD for automated builds + +### Package Size Reduction +- Remove unnecessary dependencies +- Use electron-builder's file filtering +- Consider using electron-updater for delta updates + +## Support + +For build issues: +1. Check the console output for specific errors +2. Verify all dependencies are installed +3. Try cleaning and rebuilding +4. Check electron-builder documentation +5. Open an issue with build logs + +--- + +**Happy Building! 🚀** \ No newline at end of file diff --git a/electron/build-packages.sh b/electron/build-packages.sh new file mode 100755 index 00000000..54c578c8 --- /dev/null +++ b/electron/build-packages.sh @@ -0,0 +1,56 @@ +#!/bin/bash + +# TimeSafari Electron Build Script +# Usage: ./build-packages.sh [pack|appimage|deb|rpm|all] + +set -e + +echo "🚀 TimeSafari Electron Build Script" +echo "==================================" + +# Build TypeScript and rebuild native modules +echo "📦 Building TypeScript and native modules..." +npm run build + +BUILD_TYPE="${1:-all}" + +case "$BUILD_TYPE" in + "pack") + echo "📦 Creating unpacked build..." + npx electron-builder build --dir -c ./electron-builder.config.json + ;; + "appimage") + echo "📦 Creating AppImage..." + npx electron-builder build --linux AppImage -c ./electron-builder.config.json + ;; + "deb") + echo "📦 Creating Debian package..." + npx electron-builder build --linux deb -c ./electron-builder.config.json + ;; + "rpm") + echo "📦 Creating RPM package..." + if ! command -v rpmbuild &> /dev/null; then + echo "⚠️ rpmbuild not found. Install with: sudo pacman -S rpm-tools" + exit 1 + fi + npx electron-builder build --linux rpm -c ./electron-builder.config.json + ;; + "all") + echo "📦 Creating all Linux packages..." + npx electron-builder build --linux -c ./electron-builder.config.json + ;; + *) + echo "❌ Unknown build type: $BUILD_TYPE" + echo "Usage: $0 [pack|appimage|deb|rpm|all]" + exit 1 + ;; +esac + +echo "" +echo "✅ Build completed successfully!" +echo "📁 Output files in: ./dist/" +echo "" +echo "📦 Available packages:" +ls -la dist/ | grep -E '\.(AppImage|deb|rpm)$' || echo " No packages found" +echo "" +echo "🎉 Ready to distribute!" \ No newline at end of file diff --git a/electron/electron-builder.config.json b/electron/electron-builder.config.json index 4d454bba..762f3ec4 100644 --- a/electron/electron-builder.config.json +++ b/electron/electron-builder.config.json @@ -1,7 +1,9 @@ { - "appId": "com.yourdoamnin.yourapp", + "appId": "app.timesafari.desktop", + "productName": "TimeSafari", "directories": { - "buildResources": "resources" + "buildResources": "resources", + "output": "dist" }, "files": [ "assets/**/*", @@ -12,17 +14,51 @@ "publish": { "provider": "github" }, + "linux": { + "target": [ + { + "target": "AppImage", + "arch": ["x64"] + }, + { + "target": "deb", + "arch": ["x64"] + }, + { + "target": "rpm", + "arch": ["x64"] + } + ], + "icon": "assets/appIcon.png", + "category": "Office", + "description": "Time Safari - Community building through gifts, gratitude, and collaborative projects", + "maintainer": "Matthew Raymer ", + "vendor": "TimeSafari" + }, "nsis": { "allowElevation": true, "oneClick": false, - "allowToChangeInstallationDirectory": true + "allowToChangeInstallationDirectory": true, + "createDesktopShortcut": true, + "createStartMenuShortcut": true }, "win": { - "target": "nsis", + "target": [ + { + "target": "nsis", + "arch": ["x64"] + } + ], "icon": "assets/appIcon.ico" }, "mac": { - "category": "your.app.category.type", - "target": "dmg" + "category": "public.app-category.productivity", + "target": [ + { + "target": "dmg", + "arch": ["x64", "arm64"] + } + ], + "icon": "assets/appIcon.png" } } \ No newline at end of file diff --git a/electron/package.json b/electron/package.json index 480827f0..daa15ca5 100644 --- a/electron/package.json +++ b/electron/package.json @@ -1,14 +1,15 @@ { "name": "TimeSafari", "version": "1.0.0", - "description": "An Amazing Capacitor App", + "description": "Time Safari - Community building through gifts, gratitude, and collaborative projects", + "homepage": "https://timesafari.app", "author": { - "name": "", - "email": "" + "name": "Matthew Raymer", + "email": "matthew@timesafari.app" }, "repository": { "type": "git", - "url": "" + "url": "https://github.com/trentlarson/crowd-master" }, "license": "MIT", "main": "build/src/index.js", diff --git a/package.json b/package.json index 0e2d2bb5..bb9db22e 100644 --- a/package.json +++ b/package.json @@ -25,6 +25,9 @@ "electron:dev": "npm run build:capacitor && npx cap copy electron && cd electron && npm run electron:start", "electron:setup": "./scripts/setup-electron.sh", "electron:dev-full": "./scripts/electron-dev.sh", + "electron:build": "npm run build:capacitor && npx cap copy electron && cd electron && ./build-packages.sh", + "electron:build:appimage": "npm run build:capacitor && npx cap copy electron && cd electron && ./build-packages.sh appimage", + "electron:build:deb": "npm run build:capacitor && npx cap copy electron && cd electron && ./build-packages.sh deb", "clean:android": "adb uninstall app.timesafari.app || true", "build:android": "./scripts/build-android.sh", "fastlane:ios:beta": "cd ios && fastlane beta",