feat: add native wrappers and cross-platform packaging support [WIP]

.github/workflows/publish-apps.yml

@@ -0,0 +1,194 @@
+name: Publish Apps
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  desktop:
+    name: Electron (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      fail-fast: false
+      matrix:
+        os:
+          - windows-latest
+          - macos-latest
+          - ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "22"
+          cache: "npm"
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Install dependencies
+        working-directory: frontend
+        run: npm ci
+
+      - name: Resolve app version
+        id: app-version
+        shell: bash
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+          DISPATCH_VERSION: ${{ github.event.inputs.version }}
+          REF_NAME: ${{ github.ref_name }}
+        run: |
+          VERSION="${RELEASE_TAG:-${DISPATCH_VERSION:-$REF_NAME}}"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Set app version
+        working-directory: frontend
+        run: npm run app:version -- "${{ steps.app-version.outputs.version }}" "${{ github.run_number }}"
+
+      - name: Build Electron package
+        if: matrix.os != 'ubuntu-latest'
+        working-directory: frontend
+        run: npm run electron:dist
+        env:
+          CSC_IDENTITY_AUTO_DISCOVERY: "false"
+
+      - name: Build Linux x64 Electron packages
+        if: matrix.os == 'ubuntu-latest'
+        working-directory: frontend
+        run: npm run electron:dist -- --linux deb rpm --x64
+        env:
+          CSC_IDENTITY_AUTO_DISCOVERY: "false"
+
+      - name: Build Linux arm64 Electron packages
+        if: matrix.os == 'ubuntu-latest'
+        working-directory: frontend
+        run: npm run electron:dist -- --linux deb rpm --arm64
+        env:
+          CSC_IDENTITY_AUTO_DISCOVERY: "false"
+
+      - name: Rename Linux artifacts
+        if: matrix.os == 'ubuntu-latest'
+        working-directory: frontend
+        run: node packages/scripts/rename-linux-artifacts.cjs
+
+      - name: Upload Electron artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: mailflow-electron-${{ matrix.os }}
+          if-no-files-found: error
+          path: |
+            frontend/packages/release/*.deb
+            frontend/packages/release/*.dmg
+            frontend/packages/release/*.exe
+            frontend/packages/release/*.rpm
+
+  android:
+    name: Android
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "22"
+          cache: "npm"
+          cache-dependency-path: frontend/package-lock.json
+
+      - uses: actions/setup-java@v5
+        with:
+          distribution: temurin
+          java-version: "21"
+
+      - uses: android-actions/setup-android@v3
+
+      - name: Install dependencies
+        working-directory: frontend
+        run: npm ci
+
+      - name: Resolve app version
+        id: app-version
+        shell: bash
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+          DISPATCH_VERSION: ${{ github.event.inputs.version }}
+          REF_NAME: ${{ github.ref_name }}
+        run: |
+          VERSION="${RELEASE_TAG:-${DISPATCH_VERSION:-$REF_NAME}}"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Set app version
+        working-directory: frontend
+        run: npm run app:version -- "${{ steps.app-version.outputs.version }}" "${{ github.run_number }}"
+
+      - name: Prepare Android release signing
+        shell: bash
+        env:
+          MAILFLOW_ANDROID_KEYSTORE_BASE64: ${{ secrets.MAILFLOW_ANDROID_KEYSTORE_BASE64 }}
+        run: |
+          if [ -n "$MAILFLOW_ANDROID_KEYSTORE_BASE64" ]; then
+            mkdir -p "$RUNNER_TEMP/mailflow-signing"
+            echo "$MAILFLOW_ANDROID_KEYSTORE_BASE64" | base64 --decode > "$RUNNER_TEMP/mailflow-signing/release.keystore"
+            echo "MAILFLOW_ANDROID_STORE_FILE=$RUNNER_TEMP/mailflow-signing/release.keystore" >> "$GITHUB_ENV"
+          fi
+
+      - name: Build Android package
+        working-directory: frontend
+        run: npm run android:dist
+        env:
+          MAILFLOW_ANDROID_STORE_PASSWORD: ${{ secrets.MAILFLOW_ANDROID_STORE_PASSWORD }}
+          MAILFLOW_ANDROID_KEY_ALIAS: ${{ secrets.MAILFLOW_ANDROID_KEY_ALIAS }}
+          MAILFLOW_ANDROID_KEY_PASSWORD: ${{ secrets.MAILFLOW_ANDROID_KEY_PASSWORD }}
+
+      - name: List Android release artifacts
+        if: always()
+        working-directory: frontend
+        run: find packages/android/app/build -maxdepth 6 -type f | sort || true
+
+      - name: Upload Android artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: mailflow-android
+          if-no-files-found: error
+          path: frontend/packages/release/*.apk
+
+  release:
+    name: Attach to GitHub Release
+    needs:
+      - desktop
+      - android
+    if: startsWith(github.ref, 'refs/tags/') || github.event_name == 'release' || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Resolve app version
+        id: app-version
+        shell: bash
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+          DISPATCH_VERSION: ${{ github.event.inputs.version }}
+          REF_NAME: ${{ github.ref_name }}
+        run: |
+          VERSION="${RELEASE_TAG:-${DISPATCH_VERSION:-$REF_NAME}}"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: artifacts
+
+      - name: Publish release files
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ steps.app-version.outputs.version }}
+          files: |
+            artifacts/**/*.apk
+            artifacts/**/*.deb
+            artifacts/**/*.dmg
+            artifacts/**/*.exe
+            artifacts/**/*.rpm

.gitignore

@@ -8,6 +8,7 @@ node_modules/
 # Build output
 frontend/dist/
 frontend/.vite/
+frontend/packages/release/
 
 # TLS certs (generated locally or via Let's Encrypt)
 certs/

README.md

@@ -499,6 +499,67 @@ nginx  (frontend container — internal only)
   └── backend, PostgreSQL, Redis (internal network, unchanged)
 ```
 
+## Desktop and Android apps
+
+MailFlow remains a self-hosted web app, but release builds also publish native wrappers for users who prefer an installed desktop or mobile application.
+
+- Windows, macOS, and Linux use Electron-based packages.
+- Android uses a Capacitor WebView wrapper.
+- On first launch, the native wrapper prompts for the MailFlow server URL, such as `https://mail.your-domain.com`, stores it locally, and connects to that server.
+- Native package sources live under `frontend/packages`.
+
+Install release builds from the latest MailFlow release:
+
+- **Windows**: 
+  - Download the latest `.exe` installer and run it.
+- **macOS**: 
+  - Download the latest `Universal.dmg` release and install the app.
+    - On first launch, macOS may display:
+      - `"MailFlow" can't be opened because Apple cannot check it for malicious software`.
+    - Click OK, then open:
+      - Settings -> Privacy & Security.
+    - Click Open Anyway beside:
+      - `"MailFlow" was blocked from use because it is not from an identified developer`.
+    - Click Open on the second confirmation dialog.
+    - MailFlow will run normally afterward, including future updates.
+- **Ubuntu / Debian**
+  - Download the latest `.deb` release and install it:
+
+    ```bash
+    sudo dpkg -i MailFlow-<version>-amd64.deb
+    ```
+    or
+    ```bash
+    sudo dpkg -i MailFlow-<version>-arm64.deb
+    ```
+  - If dependencies are missing:
+      ```bash
+      sudo apt-get install -f
+      ```
+- **Fedora / Red Hat**
+  - Download the latest `.rpm` release and install it:
+
+    ```bash
+    sudo dnf install MailFlow-<version>-x86_64.rpm
+    ```
+    or
+    ```bash
+    sudo dnf install MailFlow-<version>-aarch64.rpm
+    ```
+
+- **Android**
+  - Download the latest Android `.apk` release and install it manually.
+
+Local Development Builds:
+
+```bash
+cd frontend
+npm ci
+npm run electron:dist
+npm run android:dist
+```
+---
+
 ## Star History
 
 [![Star History Chart](https://api.star-history.com/svg?repos=maathimself/mailflow&type=Date)](https://star-history.com/#maathimself/mailflow&Date)

frontend/.dockerignore

@@ -2,3 +2,6 @@ node_modules
 dist
 .git
 *.local
+packages/android
+packages/release
+packages/electron