Add comprehensive Heroku deployment guide with both web interface and CLI methods

.github/workflows/preview-deploy.yml

@@ -0,0 +1,175 @@
+name: Preview Branch Deployment
+
+on:
+  pull_request:
+    branches: [main]
+    types: [opened, synchronize, reopened]
+  push:
+    branches:
+      - main
+      - develop
+      - 'preview/**'
+      - 'feature/**'
+
+jobs:
+  deploy-preview:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    if: github.event_name == 'pull_request' || (github.event_name == 'push' && github.ref != 'refs/heads/main')
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up JDK 17
+        uses: actions/setup-java@v4
+        with:
+          distribution: 'zulu'
+          java-version: 17
+
+      - name: Cache gradle
+        uses: actions/cache@v4
+        with:
+          path: ~/.gradle/caches
+          key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle*') }}
+          restore-keys: |
+            ${{ runner.os }}-gradle-
+
+      - name: Set branch name
+        id: branch
+        run: |
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            echo "branch_name=pr-${{ github.event.number }}" >> $GITHUB_OUTPUT
+            echo "deploy_url=pr-${{ github.event.number }}" >> $GITHUB_OUTPUT
+          else
+            branch_name=${GITHUB_REF#refs/heads/}
+            echo "branch_name=${branch_name//\//-}" >> $GITHUB_OUTPUT
+            echo "deploy_url=${branch_name//\//-}" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Run tests
+        run: ./gradlew test --no-daemon
+
+      - name: Build Android APK (Debug)
+        run: ./gradlew assembleDebug --no-daemon
+
+      - name: Build Web WAR
+        run: ./gradlew :web:bootWar --no-daemon
+
+      - name: Upload Android APK
+        uses: actions/upload-artifact@v4
+        with:
+          name: android-apk-${{ steps.branch.outputs.branch_name }}
+          path: app/build/outputs/apk/debug/app-debug.apk
+          retention-days: 7
+
+      - name: Upload Web WAR  
+        uses: actions/upload-artifact@v4
+        with:
+          name: web-war-${{ steps.branch.outputs.branch_name }}
+          path: web/build/libs/web.war
+          retention-days: 7
+
+      # Optional: Deploy to Heroku Review Apps (if configured)
+      - name: Deploy to Heroku Review App
+        if: github.event_name == 'pull_request' && vars.HEROKU_APP_NAME
+        uses: akhileshns/heroku-deploy@v3.13.15
+        with:
+          heroku_api_key: ${{ secrets.HEROKU_API_KEY }}
+          heroku_app_name: ${{ vars.HEROKU_APP_NAME }}-${{ steps.branch.outputs.deploy_url }}
+          heroku_email: ${{ secrets.HEROKU_EMAIL }}
+          usedocker: false
+          buildpack: heroku/java
+
+      # Optional: Deploy to custom preview environment
+      - name: Deploy to Preview Environment
+        if: vars.PREVIEW_DEPLOY_ENABLED == 'true'
+        run: |
+          echo "Deploying to preview environment: ${{ steps.branch.outputs.deploy_url }}"
+          # Add your custom deployment commands here
+          # For example, deploy to a staging server, cloud platform, etc.
+
+      - name: Comment deployment info on PR
+        if: github.event_name == 'pull_request'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const branchName = '${{ steps.branch.outputs.branch_name }}';
+            const deployUrl = '${{ steps.branch.outputs.deploy_url }}';
+
+            let body = `## 🚀 Preview Deployment\n\n`;
+            body += `**Branch:** \`${branchName}\`\n\n`;
+            body += `### Available Artifacts:\n`;
+            body += `- 📱 [Android APK](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }})\n`;
+            body += `- 🌐 [Web WAR](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }})\n\n`;
+
+            if (process.env.HEROKU_APP_NAME) {
+              body += `### Live Preview:\n`;
+              body += `- 🌐 [Web App Preview](https://${{ vars.HEROKU_APP_NAME }}-${deployUrl}.herokuapp.com)\n\n`;
+            }
+
+            body += `### Installation Instructions:\n`;
+            body += `1. Download the APK from the artifacts above\n`;
+            body += `2. Install on Android device: \`adb install app-debug.apk\`\n`;
+            body += `3. For web app: Download WAR and run \`java -jar web.war\`\n\n`;
+            body += `*Artifacts will be retained for 7 days*`;
+
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: body
+            });
+
+  deploy-main:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up JDK 17
+        uses: actions/setup-java@v4
+        with:
+          distribution: 'zulu'
+          java-version: 17
+
+      - name: Cache gradle
+        uses: actions/cache@v4
+        with:
+          path: ~/.gradle/caches
+          key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle*') }}
+          restore-keys: |
+            ${{ runner.os }}-gradle-
+
+      - name: Run tests
+        run: ./gradlew test --no-daemon
+
+      - name: Build Android APK (Debug)
+        run: ./gradlew assembleDebug --no-daemon
+
+      - name: Build Web WAR
+        run: ./gradlew :web:bootWar --no-daemon
+
+      - name: Upload Android APK
+        uses: actions/upload-artifact@v4
+        with:
+          name: android-apk-main-latest
+          path: app/build/outputs/apk/debug/app-debug.apk
+          retention-days: 30
+
+      - name: Upload Web WAR
+        uses: actions/upload-artifact@v4
+        with:
+          name: web-war-main-latest
+          path: web/build/libs/web.war
+          retention-days: 30
+
+      # Optional: Deploy to staging environment
+      - name: Deploy to Staging
+        if: vars.STAGING_DEPLOY_ENABLED == 'true'
+        run: |
+          echo "Deploying main branch to staging environment"
+          # Add your staging deployment commands here

README.md

@@ -25,6 +25,7 @@ anywhere. Our goal is to make a Verifier App with the widest possible verificati
 ### Project Documentation
 - [**Data Models**](docs/data-models.md) - Comprehensive documentation of all supported certificate data models (DDCC, DCC, DIVOC, SHC, ICAO, ICVP)
 - [**User Workflows**](docs/user-workflows.md) - User experience and technical workflow documentation
+- [**Deployment Guide**](docs/deployment.md) - Complete guide for preview branch and production deployments
 - [**Adding New Schemas**](NEW_SCHEMAS.md) - Guide for adding support for new certificate formats
 
 ### Reference Documentation
@@ -145,6 +146,10 @@ Android will connect with your local IP. Just make sure the phone is in the same
 
 ## How to Deploy
 
+> **📖 For comprehensive deployment documentation, see the [Deployment Guide](docs/deployment.md)**
+
+### Quick Start - Production Release
+
 1. Generate a new signing key 
 ```
 keytool -genkey -v -keystore <my-release-key.keystore> -alias <alias_name> -keyalg RSA -keysize 2048 -validity 10000
@@ -159,7 +164,17 @@ keytool -genkey -v -keystore <my-release-key.keystore> -alias <alias_name> -keya
 5. Tag the commit with `v{x.x.x}`
 6. Let the [Create Release GitHub Action](https://github.com/WorldHealthOrganization/gdhcn-validator/actions/workflows/create-release.yml) build a new `aab` file. 
 7. Add your CHANGE LOG to the description of the new release
-8. Download the `aab` file and upload it to the` PlayStore. 
+8. Download the `aab` file and upload it to the PlayStore.
+
+### Preview Branch Deployment
+
+For testing changes before production:
+
+- **Pull Requests**: Automatic preview deployment with artifacts and optional live preview
+- **Feature Branches**: Push to `preview/*` or `feature/*` branches for manual deployment
+- **Main Branch**: Automatic staging deployment on every push to main
+
+See the [Deployment Guide](docs/deployment.md) for detailed instructions on preview deployments, configuration options, and troubleshooting. 
 
 # Contributing
 

docs/deployment-quick-reference.md

@@ -0,0 +1,110 @@
+# Quick Deployment Reference
+
+> **📖 For complete documentation, see [docs/deployment.md](deployment.md)**
+
+## Preview Branch Deployment
+
+### Automatic (Pull Requests)
+- ✨ **Just create a PR** - deployment happens automatically
+- 📱 Get Android APK and Web WAR artifacts  
+- 🌐 Optional live preview on Heroku Review Apps
+- 💬 Automatic PR comment with download links
+
+### Manual (Feature Branches)
+```bash
+# Deploy any branch for testing
+git push origin feature/my-feature
+git push origin preview/my-feature
+
+# Triggers automatic build and artifact creation
+```
+
+## Main Branch Deployment
+```bash
+# Deploy to staging/latest
+git push origin main
+
+# Creates "latest" artifacts with 30-day retention
+```
+
+## Production Release
+```bash
+# 1. Update version in app/build.gradle
+# 2. Commit and tag
+git tag v1.2.3
+git push origin main && git push origin v1.2.3
+
+# Creates signed APK, AAB, and WAR files
+```
+
+## Quick Setup
+
+### Choose Your Deployment Method
+
+**Option 1: Web-Based Setup (No CLI required)**
+1. **Heroku**: Create app via [dashboard.heroku.com](https://dashboard.heroku.com) → Connect GitHub repository
+2. **Review Apps**: Enable via Dashboard → Deploy tab → Review Apps section  
+3. **GitHub**: Add secrets/variables via Settings → Secrets and variables → Actions
+
+**Option 2: CLI-Based Setup**
+1. **Heroku Setup**:
+   ```bash
+   heroku create your-app-name
+   heroku buildpacks:set heroku/java
+   ```
+2. **Enable Review Apps**: Go to Heroku Dashboard → Deploy → Enable Review Apps
+3. **GitHub Secrets** (Settings → Secrets and variables → Actions → Secrets):
+   - `HEROKU_API_KEY` = `heroku auth:token` output
+   - `HEROKU_EMAIL` = your Heroku account email
+4. **GitHub Variables** (Settings → Secrets and variables → Actions → Variables):
+   - `HEROKU_APP_NAME` = `your-app-name` (base name only)
+
+### GitHub Configuration (Detailed)
+```bash
+# Get required info
+heroku auth:token    # Copy this for HEROKU_API_KEY
+heroku auth:whoami   # Copy this for HEROKU_EMAIL
+
+# Repository Settings → Secrets and variables → Actions
+# Add Secrets:
+#   HEROKU_API_KEY = <token from above>
+#   HEROKU_EMAIL = <email from above>
+# Add Variables:
+#   HEROKU_APP_NAME = your-app-name
+```
+
+### Alternative: GitHub CLI Setup
+```bash
+gh secret set HEROKU_API_KEY --body "your-api-key"
+gh secret set HEROKU_EMAIL --body "your-email@example.com"
+gh variable set HEROKU_APP_NAME --body "your-app-name"
+```
+
+### Essential Heroku Commands
+```bash
+# Setup
+heroku login
+heroku create your-app-name
+heroku buildpacks:set heroku/java
+
+# Deploy manually
+git push heroku main
+
+# Monitor
+heroku logs --tail
+heroku ps
+heroku apps:info your-app-name
+
+# Review Apps
+heroku apps                    # List all apps
+heroku apps:destroy app-name   # Clean up old review apps
+```
+
+### For Signed Releases  
+Add these GitHub secrets:
+- `KEY_ALIAS`, `KEY_PASSWORD`, `KEY_STORE_PASSWORD`, `SIGNING_KEY`
+
+## Artifacts Location
+- **GitHub Actions** → Workflow runs → Artifacts section
+- **Releases** → GitHub Releases page  
+- **Live previews** → Check PR comments for links