diff --git a/BUILDING.md b/BUILDING.md index 141dc3b2..bd5584d4 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -111,8 +111,106 @@ TIME_SAFARI_APP_TITLE="TimeSafari_Test" VITE_APP_SERVER=https://test.timesafari. * Record the new hash in the changelog. Edit package.json to increment version & add "-beta", `npm install`, and commit. Also record what version is on production. +## Docker Deployment +The application can be containerized using Docker for consistent deployment across environments. +### Prerequisites + +- Docker installed on your system +- Docker Compose (optional, for multi-container setups) + +### Building the Docker Image + +1. Build the Docker image: + + ```bash + docker build -t timesafari:latest . + ``` + +2. For development builds with specific environment variables: + + ```bash + docker build --build-arg NODE_ENV=development -t timesafari:dev . + ``` + +### Running the Container + +1. Run the container: + + ```bash + docker run -d -p 80:80 timesafari:latest + ``` + +2. For development with hot-reloading: + + ```bash + docker run -d -p 80:80 -v $(pwd):/app timesafari:dev + ``` + +### Using Docker Compose + +Create a `docker-compose.yml` file: + +```yaml +version: '3.8' +services: + timesafari: + build: . + ports: + - "80:80" + environment: + - NODE_ENV=production + restart: unless-stopped +``` + +Run with Docker Compose: + +```bash +docker-compose up -d +``` + +### Production Deployment + +For production deployment, consider the following: + +1. Use specific version tags instead of 'latest' +2. Implement health checks +3. Configure proper logging +4. Set up reverse proxy with SSL termination +5. Use Docker secrets for sensitive data + +Example production deployment: + +```bash +# Build with specific version +docker build -t timesafari:1.0.0 . + +# Run with production settings +docker run -d \ + --name timesafari \ + -p 80:80 \ + --restart unless-stopped \ + -e NODE_ENV=production \ + timesafari:1.0.0 +``` + +### Troubleshooting Docker + +1. **Container fails to start** + - Check logs: `docker logs ` + - Verify port availability + - Check environment variables + +2. **Build fails** + - Ensure all dependencies are in package.json + - Check Dockerfile syntax + - Verify build context + +3. **Performance issues** + - Monitor container resources: `docker stats` + - Check nginx configuration + - Verify caching settings ## Desktop Build (Electron) @@ -275,253 +373,4 @@ You must add the following intent filter to the `android/app/src/main/AndroidMan - ``` - -You must also add the following to the `android/app/build.gradle` file: - - ```gradle - android { - // ... existing config ... - - lintOptions { - disable 'UnsanitizedFilenameFromContentProvider' - abortOnError false - baseline file("lint-baseline.xml") - - // Ignore Capacitor module issues - ignore 'DefaultLocale' - ignore 'UnsanitizedFilenameFromContentProvider' - ignore 'LintBaseline' - ignore 'LintBaselineFixed' - } - } - ``` - -Modify `/android/build.gradle` to use a stable version of AGP and make sure Kotlin version is compatible. - - ```gradle - buildscript { - repositories { - google() - mavenCentral() - } - dependencies { - // Use a stable version of AGP - classpath 'com.android.tools.build:gradle:8.1.0' - - // Make sure Kotlin version is compatible - classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:1.8.0" - } - } - - allprojects { - repositories { - google() - mavenCentral() - } - } - - // Add this to handle version conflicts - configurations.all { - resolutionStrategy { - force 'org.jetbrains.kotlin:kotlin-stdlib:1.8.0' - force 'org.jetbrains.kotlin:kotlin-stdlib-common:1.8.0' - } - } - ``` - -## 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 all tests (requires XCode and Android Studio/device): - -```bash -npm run test:all -``` - -See [TESTING.md](test-playwright/TESTING.md) for more details. - -## 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 - - -# List all installed packages -adb shell pm list packages | grep timesafari - -# Force stop the app (if it's running) -adb shell am force-stop app.timesafari - -# Clear app data (if you don't want to fully uninstall) -adb shell pm clear app.timesafari - -# Uninstall for all users -adb shell pm uninstall -k --user 0 app.timesafari - -# Check if app is installed -adb shell pm path app.timesafari \ No newline at end of file + ``` \ No newline at end of file