docs: add Docker deployment instructions to BUILDING.md

- Add comprehensive Docker deployment section - Include build and run instructions for development and production - Add Docker Compose configuration example - Include troubleshooting guide for common Docker issues - Document best practices for production deployment
2025-04-26 10:42:32 +00:00
parent 272f2a91a6
commit e7cb5ffd33
1 changed files with 99 additions and 250 deletions
--- 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 <container_id>`
   - 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
                  <category android:name="android.intent.category.BROWSABLE" />
                  <data android:scheme="timesafari" />
               </intent-filter>
-   ```
+   ```
 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 <VERSION_TAG>
   git push origin <VERSION_TAG>
   ```
 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/<YOUR_KEY>" 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 <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 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