2d17bfd3b4
- Update BUILDING.md with current build system information - Modernize various README files across the project - Update CHANGELOG.md with recent changes - Improve documentation consistency and formatting - Update platform-specific documentation (iOS, Electron, Docker) - Enhance test documentation and build guides
302 lines
6.1 KiB
Markdown
302 lines
6.1 KiB
Markdown
# TimeSafari Electron Build Guide
|
|
|
|
**Author**: Matthew Raymer
|
|
**Date**: 2025-07-11
|
|
**Status**: **ACTIVE** - Production Ready
|
|
|
|
## Overview
|
|
|
|
This guide covers building and running the TimeSafari Electron application for desktop platforms (Windows, macOS, Linux).
|
|
|
|
## Prerequisites
|
|
|
|
- Node.js 18+ and npm
|
|
- TypeScript
|
|
- Electron Builder
|
|
- Platform-specific build tools (see below)
|
|
|
|
## Quick Start
|
|
|
|
### Development Mode
|
|
|
|
```bash
|
|
# Start development server
|
|
npm run build:electron:dev
|
|
|
|
# Or manually
|
|
cd electron
|
|
npm run electron:start
|
|
```
|
|
|
|
### Production Builds
|
|
|
|
```bash
|
|
# Build for current platform
|
|
npm run build:electron:prod
|
|
|
|
# Platform-specific builds
|
|
npm run build:electron:windows
|
|
npm run build:electron:mac
|
|
npm run build:electron:linux
|
|
|
|
# Package-specific builds
|
|
npm run build:electron:appimage # Linux AppImage
|
|
npm run build:electron:dmg # macOS DMG installer
|
|
npm run build:electron:deb # Linux DEB package
|
|
```
|
|
|
|
## Single Instance Enforcement
|
|
|
|
The Electron app enforces single instance operation to prevent database conflicts and resource contention:
|
|
|
|
### Implementation
|
|
|
|
- Uses Electron's built-in `app.requestSingleInstanceLock()`
|
|
- Second instances exit immediately with user-friendly message
|
|
- Existing instance focuses and shows informational dialog
|
|
|
|
### Behavior
|
|
|
|
- **First instance**: Starts normally and acquires lock
|
|
- **Second instance**: Detects existing instance, exits immediately
|
|
- **User experience**: Clear messaging about single instance requirement
|
|
|
|
### Benefits
|
|
|
|
- Prevents database corruption from concurrent access
|
|
- Avoids resource conflicts
|
|
- Maintains data integrity
|
|
- User-friendly error handling
|
|
|
|
## Build Configuration
|
|
|
|
### Environment Modes
|
|
|
|
```bash
|
|
# Development (default)
|
|
npm run build:electron:dev
|
|
|
|
# Testing
|
|
npm run build:electron:test
|
|
|
|
# Production
|
|
npm run build:electron:prod
|
|
```
|
|
|
|
### Platform-Specific Builds
|
|
|
|
```bash
|
|
# Windows
|
|
npm run build:electron:windows:dev
|
|
npm run build:electron:windows:test
|
|
npm run build:electron:windows:prod
|
|
|
|
# macOS
|
|
npm run build:electron:mac:dev
|
|
npm run build:electron:mac:test
|
|
npm run build:electron:mac:prod
|
|
|
|
# Linux
|
|
npm run build:electron:linux:dev
|
|
npm run build:electron:linux:test
|
|
npm run build:electron:linux:prod
|
|
```
|
|
|
|
### Package Types
|
|
|
|
```bash
|
|
# Linux AppImage
|
|
npm run build:electron:appimage:dev
|
|
npm run build:electron:appimage:test
|
|
npm run build:electron:appimage:prod
|
|
|
|
# macOS DMG
|
|
npm run build:electron:dmg:dev
|
|
npm run build:electron:dmg:test
|
|
npm run build:electron:dmg:prod
|
|
|
|
# Linux DEB
|
|
npm run build:electron:deb:dev
|
|
npm run build:electron:deb:test
|
|
npm run build:electron:deb:prod
|
|
```
|
|
|
|
## Platform-Specific Requirements
|
|
|
|
### Windows
|
|
|
|
- Windows 10+ (64-bit)
|
|
- Visual Studio Build Tools (for native modules)
|
|
|
|
### macOS
|
|
|
|
- macOS 10.15+ (Catalina)
|
|
- Xcode Command Line Tools
|
|
- Code signing certificate (for distribution)
|
|
|
|
### Linux
|
|
|
|
- Ubuntu 18.04+ / Debian 10+ / CentOS 7+
|
|
- Development headers for native modules
|
|
|
|
## Database Configuration
|
|
|
|
### SQLite Integration
|
|
|
|
- Uses native Node.js SQLite3 for Electron
|
|
- Database stored in user's app data directory
|
|
- Automatic migration from IndexedDB (if applicable)
|
|
|
|
### Single Instance Protection
|
|
|
|
- File-based locking prevents concurrent database access
|
|
- Automatic cleanup on app exit
|
|
- Graceful handling of lock conflicts
|
|
|
|
## Security Features
|
|
|
|
### Content Security Policy
|
|
|
|
- Strict CSP in production builds
|
|
- Development mode allows localhost connections
|
|
- Automatic configuration based on build mode
|
|
|
|
### Auto-Updater
|
|
|
|
- Disabled in development mode
|
|
- Production builds check for updates automatically
|
|
- AppImage builds skip update checks
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
#### Build Failures
|
|
|
|
```bash
|
|
# Clean and rebuild
|
|
npm run clean:electron
|
|
npm run build:electron:dev
|
|
```
|
|
|
|
#### Native Module Issues
|
|
|
|
```bash
|
|
# Rebuild native modules
|
|
cd electron
|
|
npm run electron:rebuild
|
|
```
|
|
|
|
#### Single Instance Conflicts
|
|
|
|
- Ensure no other TimeSafari instances are running
|
|
- Check for orphaned processes: `ps aux | grep electron`
|
|
- Restart system if necessary
|
|
|
|
#### Database Issues
|
|
|
|
- Check app data directory permissions
|
|
- Verify SQLite database integrity
|
|
- Clear app data if corrupted
|
|
|
|
### Debug Mode
|
|
|
|
```bash
|
|
# Enable debug logging
|
|
DEBUG=* npm run build:electron:dev
|
|
```
|
|
|
|
## File Structure
|
|
|
|
```
|
|
electron/
|
|
├── src/
|
|
│ ├── index.ts # Main process entry point
|
|
│ ├── preload.ts # Preload script
|
|
│ └── setup.ts # App setup and configuration
|
|
├── assets/ # App icons and resources
|
|
├── package.json # Electron-specific dependencies
|
|
├── electron-builder.config.json # Build configuration
|
|
└── tsconfig.json # TypeScript configuration
|
|
```
|
|
|
|
## Development Workflow
|
|
|
|
1. **Start Development**
|
|
|
|
```bash
|
|
npm run build:electron:dev
|
|
```
|
|
|
|
2. **Make Changes**
|
|
- Edit source files in `src/`
|
|
- Changes auto-reload in development
|
|
|
|
3. **Test Build**
|
|
|
|
```bash
|
|
npm run build:electron:test
|
|
```
|
|
|
|
4. **Production Build**
|
|
|
|
```bash
|
|
npm run build:electron:prod
|
|
```
|
|
|
|
## Performance Considerations
|
|
|
|
### Memory Usage
|
|
|
|
- Monitor renderer process memory
|
|
- Implement proper cleanup in components
|
|
- Use efficient data structures
|
|
|
|
### Startup Time
|
|
|
|
- Lazy load non-critical modules
|
|
- Optimize database initialization
|
|
- Minimize synchronous operations
|
|
|
|
### Database Performance
|
|
|
|
- Use transactions for bulk operations
|
|
- Implement proper indexing
|
|
- Monitor query performance
|
|
|
|
## Security Checklist
|
|
|
|
- [ ] Content Security Policy configured
|
|
- [ ] Auto-updater properly configured
|
|
- [ ] Single instance enforcement active
|
|
- [ ] Database access properly secured
|
|
- [ ] IPC handlers validate input
|
|
- [ ] File system access restricted
|
|
- [ ] Network requests validated
|
|
|
|
## Deployment
|
|
|
|
### Distribution
|
|
|
|
- Windows: `.exe` installer
|
|
- macOS: `.dmg` disk image
|
|
- Linux: `.AppImage` or `.deb` package
|
|
|
|
### Code Signing
|
|
|
|
- Windows: Authenticode certificate
|
|
- macOS: Developer ID certificate
|
|
- Linux: GPG signing (optional)
|
|
|
|
### Auto-Updates
|
|
|
|
- Configured for production builds
|
|
- Disabled for development and AppImage
|
|
- Handles update failures gracefully
|
|
|
|
---
|
|
|
|
**Last Updated**: 2025-07-11
|
|
**Version**: 1.0.3-beta
|
|
**Status**: Production Ready
|