diff --git a/.flatpak-builder/ccache/disabled/ccache.conf b/.flatpak-builder/ccache/disabled/ccache.conf deleted file mode 100644 index 4d6556c..0000000 --- a/.flatpak-builder/ccache/disabled/ccache.conf +++ /dev/null @@ -1 +0,0 @@ -disable = true diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..f55a586 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,407 @@ +name: Release - Build & Sign + +on: + push: + tags: + - 'v*' + +permissions: + contents: write + packages: write + +jobs: + build-tauri: + name: Build Tauri - ${{ matrix.platform }} + runs-on: ${{ matrix.os }} + strategy: + fail-fast: false + matrix: + include: + # Linux + - os: ubuntu-latest + platform: linux + target: x86_64-unknown-linux-gnu + arch: x86_64 + + # macOS + - os: macos-latest + platform: macos + target: universal-apple-darwin + arch: universal + + # Windows + - os: windows-latest + platform: windows + target: x86_64-pc-windows-msvc + arch: x86_64 + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Setup Rust + uses: dtolnay/rust-toolchain@stable + with: + targets: ${{ matrix.target }} + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '20' + cache: 'npm' + + - name: Install pnpm + run: npm install -g pnpm + + - name: Install dependencies (Linux) + if: matrix.os == 'ubuntu-latest' + run: | + sudo apt-get update + sudo apt-get install -y libssl-dev libgtk-3-dev libayatana-appindicator3-dev librsvg2-dev + + - name: Install Rust dependencies (Linux) + if: matrix.os == 'ubuntu-latest' + run: | + rustup target add x86_64-unknown-linux-gnu + + - name: Install frontend dependencies + run: pnpm install --frozen-lockfile + + - name: Build frontend + run: pnpm run build + + - name: Build Tauri (Linux) + if: matrix.platform == 'linux' + run: pnpm tauri build --target x86_64-unknown-linux-gnu + + - name: Build Tauri (macOS) + if: matrix.platform == 'macos' + run: pnpm tauri build + + - name: Build Tauri (Windows) + if: matrix.platform == 'windows' + run: pnpm tauri build + + - name: Upload build artifacts + uses: actions/upload-artifact@v4 + with: + name: tauri-${{ matrix.platform }} + path: | + src-tauri/target/release/bundle/ + !src-tauri/target/release/bundle/deps/ + retention-days: 7 + + sign-and-release: + name: Sign Binaries & Create Release + runs-on: ubuntu-latest + needs: build-tauri + if: startsWith(github.ref, 'refs/tags/v') + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '20' + + - name: Install pnpm + run: npm install -g pnpm + + - name: Install minisign + run: sudo apt-get install -y minisign + + - name: Download all artifacts + uses: actions/download-artifact@v4 + with: + path: artifacts/ + + - name: Prepare release files + run: | + mkdir -p release + + # Copy Linux artifacts + cp artifacts/tauri-linux/AppImage/CommDesk-*.AppImage.tar.gz* release/ 2>/dev/null || true + cp artifacts/tauri-linux/Rpm/commdesk-*.rpm* release/ 2>/dev/null || true + cp artifacts/tauri-linux/Deb/commdesk-*.deb* release/ 2>/dev/null || true + + # Copy macOS artifacts + cp artifacts/tauri-macos/Dmg/CommDesk-*.dmg* release/ 2>/dev/null || true + cp artifacts/tauri-macos/Macos/CommDesk-*.app.tar.gz* release/ 2>/dev/null || true + + # Copy Windows artifacts + cp artifacts/tauri-windows/Msi/CommDesk-*.msi.zip* release/ 2>/dev/null || true + cp artifacts/tauri-windows/Nsis/CommDesk-*-setup.exe* release/ 2>/dev/null || true + + - name: Setup minisign key + env: + MINISIGN_PRIVATE_KEY: ${{ secrets.MINISIGN_PRIVATE_KEY }} + run: | + mkdir -p ~/.minisign + echo "$MINISIGN_PRIVATE_KEY" > ~/.minisign/key.txt + chmod 600 ~/.minisign/key.txt + + - name: Sign binaries + run: | + cd release + + # Sign all binary files + for file in CommDesk-* commdesk-* *.exe *.dmg; do + if [ -f "$file" ] && [[ ! "$file" =~ \.sig$ ]]; then + echo "Signing: $file" + minisign -S -s ~/.minisign/key.txt \ + -t "CommDesk ${{ github.ref_name }}" \ + -x "${file}.sig" \ + -m "$file" + fi + done + + ls -lah + + - name: Generate latest.json + run: | + VERSION="${{ github.ref_name }}" + VERSION="${VERSION#v}" # Remove 'v' prefix + + cat > latest.json << EOF + { + "version": "${VERSION}", + "notes": "CommDesk ${VERSION}", + "pub_date": "$(date -u +%Y-%m-%dT%H:%M:%SZ)", + "platforms": { + "linux-x86_64": { + "signature": "$(cat release/CommDesk-*-linux-x86_64.AppImage.tar.gz.sig 2>/dev/null | tail -1 || echo '')", + "url": "https://github.com/${{ github.repository }}/releases/download/${{ github.ref_name }}/CommDesk-${VERSION}-linux-x86_64.AppImage.tar.gz" + }, + "darwin-aarch64": { + "signature": "$(cat release/CommDesk-*-macos-universal.tar.gz.sig 2>/dev/null | tail -1 || echo '')", + "url": "https://github.com/${{ github.repository }}/releases/download/${{ github.ref_name }}/CommDesk-${VERSION}-macos-universal.tar.gz" + }, + "darwin-x86_64": { + "signature": "$(cat release/CommDesk-*-macos-x86_64.tar.gz.sig 2>/dev/null | tail -1 || echo '')", + "url": "https://github.com/${{ github.repository }}/releases/download/${{ github.ref_name }}/CommDesk-${VERSION}-macos-x86_64.tar.gz" + }, + "windows-x86_64": { + "signature": "$(cat release/CommDesk-*-windows-x86_64.msi.zip.sig 2>/dev/null | tail -1 || echo '')", + "url": "https://github.com/${{ github.repository }}/releases/download/${{ github.ref_name }}/CommDesk-${VERSION}-windows-x86_64.msi.zip" + } + } + } + EOF + + cp latest.json release/latest.json + cat release/latest.json + + - name: Create Release Notes + run: | + cat > release/RELEASE_NOTES.md << 'EOF' + # CommDesk ${{ github.ref_name }} + + ## Changelog + + $(git log $(git describe --tags --abbrev=0)..HEAD --oneline | sed 's/^/- /') + + ## Platform Support + + - **Linux**: AppImage, Snap, Flathub + - **macOS**: Universal (Intel + Apple Silicon) + - **Windows**: NSIS Installer, MSI + + ## Installation + + ### Linux (Snap) + ```bash + snap install commdesk + ``` + + ### Linux (Flathub) + ```bash + flatpak install flathub org.commdesk.CommDesk + ``` + + ### macOS + Download DMG and drag to Applications + + ### Windows + Run MSI installer + + ## Auto-Update + + All versions have automatic updates enabled. The app will check for updates on startup and periodically. + + For Snap: `snap refresh` + For Flathub: `flatpak update` + For other platforms: Auto-update from within app + + ## Signatures + + Binaries are signed with minisign. Verify with: + ```bash + minisign -Vm binary.tar.gz.sig -p release.pub + ``` + + EOF + + - name: Upload to GitHub Release + uses: softprops/action-gh-release@v2 + with: + files: | + release/* + !release/latest.json + latest.json + draft: false + prerelease: false + generate_release_notes: false + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + - name: Verify release + run: | + echo "โœ… Release created: ${{ github.ref_name }}" + echo "๐Ÿ“ฆ Files:" + ls -lah release/ + echo "" + echo "๐Ÿ“‹ Latest.json:" + cat release/latest.json | jq . + + build-snap: + name: Build & Release Snap + runs-on: ubuntu-latest + if: startsWith(github.ref, 'refs/tags/v') + needs: build-tauri + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Install snapcraft + run: sudo apt-get install -y snapcraft + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '20' + + - name: Install pnpm + run: npm install -g pnpm + + - name: Setup Rust + uses: dtolnay/rust-toolchain@stable + + - name: Build snap + run: | + snapcraft --use-lxd + env: + SNAPCRAFT_STORE_CREDENTIALS: ${{ secrets.SNAPCRAFT_STORE_CREDENTIALS }} + + - name: Upload snap to candidate channel + run: | + echo "Uploading to Snap Store (candidate channel)..." + snapcraft upload commdesk_*.snap --release=candidate + env: + SNAPCRAFT_STORE_CREDENTIALS: ${{ secrets.SNAPCRAFT_STORE_CREDENTIALS }} + + - name: Publish to stable after testing + run: | + echo "๐Ÿ“ข Snap uploaded to candidate channel" + echo "After testing, run: snapcraft release commdesk stable" + + build-flatpak: + name: Test Flatpak Build + runs-on: ubuntu-latest + container: + image: ghcr.io/flathub/flatpak-github-actions:latest + options: --privileged + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Check manifest + run: | + if [ ! -f "org.commdesk.CommDesk.json" ]; then + echo "โŒ Flatpak manifest not found" + exit 1 + fi + echo "โœ… Manifest found" + + - name: Lint Flatpak manifest + uses: flathub/flatpak-github-actions/flatpak-builder-lint@v6 + with: + manifest: org.commdesk.CommDesk.json + cache: false + + - name: Build Flatpak + uses: flathub/flatpak-github-actions/flatpak-builder@v6 + with: + bundle: commdesk.flatpak + manifest-path: org.commdesk.CommDesk.json + cache: false + + - name: Upload test build + uses: actions/upload-artifact@v4 + with: + name: flatpak-test-build + path: commdesk.flatpak + retention-days: 7 + + notification: + name: Send Notifications + runs-on: ubuntu-latest + needs: [sign-and-release, build-snap, build-flatpak] + if: always() + + steps: + - name: Check release status + run: | + if [ "${{ needs.sign-and-release.result }}" == "success" ]; then + echo "โœ… Tauri release successful" + else + echo "โš ๏ธ Tauri release failed" + fi + + if [ "${{ needs.build-snap.result }}" == "success" ]; then + echo "โœ… Snap build successful (uploaded to candidate)" + else + echo "โš ๏ธ Snap build failed" + fi + + if [ "${{ needs.build-flatpak.result }}" == "success" ]; then + echo "โœ… Flatpak build successful" + else + echo "โš ๏ธ Flatpak build failed" + fi + + - name: Print next steps + run: | + cat << 'EOF' + + ๐Ÿ“‹ NEXT STEPS FOR RELEASE ${{ github.ref_name }}: + + 1๏ธโƒฃ TAURI (GitHub Releases) + โœ… Build complete and signed + โœ… Uploaded to https://github.com/${{ github.repository }}/releases + โœ… Latest.json created for auto-update + + 2๏ธโƒฃ SNAP + โญ๏ธ Build uploaded to candidate channel + ๐Ÿ“ After testing (usually 24h): + snapcraft release commdesk stable + + 3๏ธโƒฃ FLATHUB + ๐Ÿ“ Create PR to https://github.com/flathub/flathub + Update: org.commdesk.CommDesk/org.commdesk.CommDesk.json + Set source commit to: ${{ github.sha }} + + โœจ Once all channels publish: + - Linux users on Snap get update in ~24h + - Linux users on Flathub get update within hours + - macOS/Windows users get update notification in app + + EOF + +permissions: + contents: write + actions: read + packages: read diff --git a/.gitignore b/.gitignore index 99c9967..f5a32e4 100644 --- a/.gitignore +++ b/.gitignore @@ -12,6 +12,11 @@ dist dist-ssr *.local + +release.key +*.key +*.sec + # Editor directories and files .vscode/* !.vscode/extensions.json @@ -29,4 +34,6 @@ build-dir # Environment variables (local secrets) .env .env.* -!.env.example \ No newline at end of file +!.env.example + + diff --git a/Contributing.md b/Contributing.md new file mode 100644 index 0000000..c6e38f5 --- /dev/null +++ b/Contributing.md @@ -0,0 +1,181 @@ +# Contributing to CommDesk + +Thank you for your interest in contributing to CommDesk. + +***CommDesk*** is a desktop platform for *communities*, *clubs*, *organizations*, and *event teams*. Contributions that improve *usability*, *reliability*, *documentation*, *maintainability*, and *developer experience* are welcome. + +## Before You Start + +Before making changes, please review the **existing documentation** and **project structure** to understand the current scope of the repository. + +This repository includes: +- A *React* + *TypeScript* **frontend** +- A *Tauri* **desktop application** layer +- A *Rust* backend under `src-tauri` +- *Documentation* for project scope, implementation status, and release flow + +## Prerequisites + +To work on this project, you should have the following installed: + +- **Node.js 20** or later +- **pnpm 10** or later +- **Rust stable** (`rustup`, `cargo`) +- The platform-specific dependencies required by **Tauri** + +For *Linux*, *macOS*, and *Windows*, please ensure the appropriate system dependencies are installed before building the project. + +## Getting Started + +1. Fork the repository. +2. Clone your fork locally. +3. Install dependencies. +4. Start the development environment. +5. Make your changes in a feature branch. +6. Test thoroughly before opening a pull request. + +### Installation + +```git +git clone https://github.com/NexGenStudioDev/CommDesk.git +cd CommDesk +pnpm install +```` + +### Run the Application + +For local development: + +```bash +pnpm tauri dev +``` + +If you need to work on the frontend separately: + +```bash +pnpm dev +``` + +## Branch Naming + +Use a *descriptive branch name* for your work. + +Recommended formats: + +* `feature/` +* `fix/` +* `docs/` +* `refactor/` + +Examples: + +* `feature/member-search` +* `fix/login-error` +* `docs/update-readme` + +## Coding Standards + +Please follow the existing *code style* and *project conventions*. + +General expectations: + +* Keep changes focused and minimal +* Write clear, readable, and maintainable code +* Follow the current folder structure and architecture +* Avoid introducing unnecessary dependencies +* Prefer small, reusable components and functions +* Keep frontend and backend changes consistent with the existing design + +Before submitting, format and lint your code where applicable. + +## Testing + +All contributions should be tested locally before submission. + +At minimum, verify: + +* The application starts successfully +* The change works as intended +* Existing functionality is not broken +* The project passes linting and build checks where relevant + +Useful commands: + +```bash +pnpm lint +pnpm build +pnpm tauri dev +``` + +If your contribution affects desktop packaging or Rust functionality, test the relevant Tauri or `src-tauri` workflow as well. + +## Reporting Issues + +Before opening a new issue: + +* Search existing issues to avoid duplicates +* Use a clear and descriptive title +* Include steps to reproduce the problem +* Add screenshots, logs, or environment details when relevant + +A good bug report should explain: + +* What you expected to happen +* What actually happened +* How to reproduce the issue +* Which platform and version you used + +## Pull Request Guidelines + +When opening a pull request, please ensure that: + +* The pull request has a clear title +* The description explains what was changed and why +* Related issues are linked when applicable +* The changes are limited to a single purpose where possible +* The branch is up to date with the target branch before submission + +A strong pull request should include: + +* A short summary of the change +* Screenshots or recordings for UI updates +* Testing notes +* Any relevant context for reviewers + +## Commit Messages + +Use concise and meaningful commit messages. + +Recommended style: + +* `feat: add member search` +* `fix: resolve updater issue` +* `docs: improve contribution guide` +* `refactor: simplify event module` + +## Security and Secrets + +Do not commit secrets, private keys, or environment-specific credentials. + +If your change requires configuration values, update the example environment file or documentation instead of exposing sensitive data. + +## Community Standards + +Please keep discussions respectful, constructive, and professional. + +Be considerate in: + +* Issues +* Pull requests +* Code reviews +* Documentation discussions + +This project follows a [code of conduct](CODE_OF_CONDUCT.md). All contributors are expected to follow it. + +## Maintainers + +Maintainers may request changes before merging a pull request. Please respond to review feedback promptly and keep discussions focused on the proposed change. + +## License + +**By contributing to CommDesk, you agree that your contributions will be made under the same [License](LICENSE) as the project.** \ No newline at end of file diff --git a/docs/AUTO_UPDATE_SETUP_GUIDE.md b/docs/AUTO_UPDATE_SETUP_GUIDE.md new file mode 100644 index 0000000..81e8ca2 --- /dev/null +++ b/docs/AUTO_UPDATE_SETUP_GUIDE.md @@ -0,0 +1,821 @@ +# ๐Ÿš€ CommDesk Auto-Update System + +# Enterprise-Grade Auto-Update Infrastructure for Tauri, Snap, Flathub, AppImage, Windows & macOS + +This document is the complete source of truth for implementing, deploying, securing, testing, monitoring, and maintaining the CommDesk auto-update ecosystem. + +It covers: + +* Tauri auto-updater +* GitHub Releases integration +* Snap auto-updates +* Flathub auto-updates +* Release signing +* CI/CD automation +* Rollback systems +* Security verification +* Production deployment +* Monitoring & analytics +* Enterprise release workflows + +Reference architecture and implementation details: + + +--- + +# ๐Ÿง  What Is Auto-Update? + +Auto-update allows CommDesk to: + +* Detect new releases automatically +* Download updates securely +* Verify signatures +* Install updates safely +* Restart into the latest version + +without requiring users to manually reinstall the app. + +--- + +# ๐Ÿ— CommDesk Update Architecture + +```bash id="1j13c2" +CommDesk Update Architecture + +Users +โ”‚ +โ”œโ”€โ”€ Linux (Flatpak) +โ”‚ โ””โ”€โ”€ Flathub Updates +โ”‚ +โ”œโ”€โ”€ Linux (Snap) +โ”‚ โ””โ”€โ”€ Snap Store Updates +โ”‚ +โ”œโ”€โ”€ Linux (AppImage) +โ”‚ โ””โ”€โ”€ Tauri Updater +โ”‚ +โ”œโ”€โ”€ Windows (MSI/NSIS) +โ”‚ โ””โ”€โ”€ Tauri Updater +โ”‚ +โ””โ”€โ”€ macOS (DMG) + โ””โ”€โ”€ Tauri Updater +``` + +--- + +# ๐Ÿ“ฆ Update Systems Used + +| Platform | Update System | +| -------- | -------------- | +| AppImage | Tauri Updater | +| Windows | Tauri Updater | +| macOS | Tauri Updater | +| Snap | Snapd | +| Flatpak | Flathub/Ostree | + +--- + +# ๐ŸŽฏ Recommended Production Strategy + +## Official Strategy + +| Distribution | Purpose | +| ------------- | -------------------------- | +| Flatpak | Primary Linux Distribution | +| Snap | Ubuntu Ecosystem | +| AppImage | Portable Distribution | +| Tauri Updater | Windows/macOS/AppImage | + +--- + +# ๐Ÿ” Security Architecture + +# Core Security Principles + +Every update must be: + +* Signed +* Verified +* Version validated +* Integrity checked +* Securely downloaded + +--- + +# ๐Ÿ”‘ Release Signing System + +CommDesk uses: + +```bash id="h0z3fg" +Minisign +``` + +for cryptographic verification. + +--- + +# ๐Ÿ›  STEP 1 โ€” Install Minisign + +# Ubuntu/Debian + +```bash id="8gwrb4" +sudo apt install minisign +``` + +--- + +# macOS + +```bash id="f4nd4z" +brew install minisign +``` + +--- + +# Fedora + +```bash id="jlwm2u" +sudo dnf install minisign +``` + +--- + +# ๐Ÿ” STEP 2 โ€” Generate Signing Keys + +```bash id="jlwm3e" +minisign -G -p release.pub -s release.key +``` + +Generated files: + +| File | Purpose | +| ----------- | ----------- | +| release.pub | Public key | +| release.key | Private key | + +--- + +# ๐Ÿšจ CRITICAL SECURITY RULE + +## NEVER COMMIT + +```bash id="xql5n4" +release.key +``` + +to GitHub. + +--- + +# Add To .gitignore + +```bash id="jlwm9e" +release.key +*.key +*.sec +``` + +--- + +# Move Private Key + +```bash id="ywqz9s" +mkdir -p ~/.minisign +mv release.key ~/.minisign/release.key +chmod 600 ~/.minisign/release.key +``` + +--- + +# ๐ŸŸฆ STEP 3 โ€” Configure Tauri Updater + +# File + +```bash id="jlwm5h" +src-tauri/tauri.conf.json +``` + +--- + +# Add Updater Config + +```json id="jlwm7n" +"plugins": { + "updater": { + "pubkey": "YOUR_PUBLIC_KEY", + "endpoints": [ + "https://github.com/NexGenStudioDev/CommDesk/releases/latest/download/latest.json" + ], + "windows": { + "installMode": "passive" + } + } +} +``` + +--- + +# ๐Ÿ“ฆ STEP 4 โ€” Build Production Release + +```bash id="jlwm1m" +pnpm tauri build +``` + +Generated output: + +```bash id="w6h4a4" +src-tauri/target/release/bundle/ +``` + +--- + +# ๐Ÿ” STEP 5 โ€” Sign Release Files + +```bash id="jlwm0m" +minisign -S \ +-s ~/.minisign/release.key \ +-x file.sig \ +-m file +``` + +--- + +# Example + +```bash id="jlwm7v" +minisign -S \ +-s ~/.minisign/release.key \ +-x CommDesk.AppImage.sig \ +-m CommDesk.AppImage +``` + +--- + +# ๐Ÿ“„ STEP 6 โ€” Create latest.json + +# Required For Tauri Updater + +Create: + +```bash id="jlwm4f" +latest.json +``` + +This latest.json is responsible for telling the Tauri updater: + +* what version is available +* what notes to show the user +* when the release was published +* which download URL to use for each platform +* which signature file to verify before installation + +Before publishing latest.json, also create the matching signature file for each build artifact: + +```bash +minisign -S \ + -s ~/.minisign/release.key \ + -x CommDesk.AppImage.sig \ + -m CommDesk.AppImage +``` + +The resulting .sig file must be uploaded with the release and its signature content must be referenced inside latest.json. + + + +--- + +# Example + +```json +{ + "version": "1.0.0", + "notes": "Performance improvements and bug fixes", + "pub_date": "2026-05-10T10:00:00Z", + "platforms": { + "linux-x86_64": { + "signature": "SIGNATURE_HERE", + "url": "https://github.com/NexGenStudioDev/CommDesk/releases/download/v1.0.0/CommDesk.AppImage" + } + } +} +``` + +--- + +# ๐Ÿ“ค STEP 7 โ€” Create GitHub Release + +# Install GitHub CLI + +```bash id="6y4wfg" +gh auth login +``` + +--- + +# Create Release + +```bash id="jlwm2f" +gh release create v1.0.0 \ +CommDesk.AppImage \ +CommDesk.AppImage.sig \ +latest.json \ +--notes "CommDesk v1.0.0" +``` + +--- + +# ๐Ÿ”„ How Tauri Auto-Update Works + +```bash id="b7v4cu" +App Starts + โ†“ +Check latest.json + โ†“ +Compare versions + โ†“ +Download update + โ†“ +Verify signature + โ†“ +Install update + โ†“ +Restart app +``` + +--- + +# ๐Ÿ–ฅ Frontend Update UI + +# React Example + +```tsx id="jlwm8g" +const { shouldUpdate, manifest } = +await checkForUpdates(); + +if (shouldUpdate) { + await installUpdate(); + await relaunch(); +} +``` + +--- + +# Recommended Features + +* Update notification dialog +* Release notes +* Progress bar +* Retry support +* Restart button + +--- + +# ๐Ÿ“ฆ Snap Auto-Update + +# How Snap Updates Work + +Snapd automatically: + +* Checks every few hours +* Downloads updates +* Installs safely +* Allows rollback + +--- + +# Install Snapcraft + +```bash id="jlwm1b" +sudo apt install snapcraft +``` + +--- + +# Configure snapcraft.yaml + +```yaml id="jlwm5c" +name: commdesk +version: '1.0.0' + +grade: stable +confinement: strict +``` + +--- + +# Build Snap + +```bash id="jlwm2b" +snapcraft +``` + +--- + +# Login + +```bash id="jlwm0f" +snapcraft login +``` + +--- + +# Upload + +```bash id="9wz7p9" +snapcraft upload commdesk.snap --release=candidate +``` + +--- + +# Release To Stable + +```bash id="0q2xqt" +snapcraft release commdesk 1 stable +``` + +--- + +# Snap Update Flow + +```bash id="jlwm4v" +Snap Store + โ†“ +snapd checks updates + โ†“ +Download update + โ†“ +Install automatically +``` + +--- + +# Snap Channels + +| Channel | Purpose | +| --------- | ----------------- | +| edge | Experimental | +| beta | Beta | +| candidate | Release candidate | +| stable | Production | + +--- + +# ๐Ÿง Flathub Auto-Update + +# How Flathub Updates Work + +Flathub uses: + +```bash id="jlwm8k" +Ostree +``` + +for secure transactional updates. + +--- + +# Create Manifest + +```bash id="jlwm7k" +org.commdesk.CommDesk.json +``` + +--- + +# Example Config + +```json id="jlwm1y" +{ + "app-id": "org.commdesk.CommDesk", + "runtime": "org.freedesktop.Platform", + "runtime-version": "25.08" +} +``` + +--- + +# Build Flatpak + +```bash id="jlwm3n" +flatpak-builder \ +--force-clean \ +--user \ +--install-deps-from=flathub \ +--repo=repo \ +builddir \ +org.commdesk.CommDesk.json +``` + +--- + +# Submit To Flathub + +1. Fork Flathub repo +2. Add manifest +3. Create PR +4. Pass CI checks +5. Flathub publishes app + +--- + +# Flathub Update Flow + +```bash id="jlwm7e" +Flathub + โ†“ +Detect new release + โ†“ +Build package + โ†“ +Publish update + โ†“ +User receives update +``` + +--- + +# โšก GitHub Actions Automation + +# Create Workflow + +```bash id="9thx0f" +.github/workflows/release.yml +``` + +--- + +# Responsibilities + +GitHub Actions should: + +* Build app +* Sign binaries +* Generate latest.json +* Upload GitHub release +* Upload Snap +* Build Flatpak + +--- + +# Example Pipeline + +```yaml id="jlwm5p" +- pnpm install +- pnpm build +- pnpm tauri build +- minisign signing +- gh release upload +``` + +--- + +# ๐Ÿ”„ Release Workflow + +# Production Workflow + +```bash id="jlwm8m" +Update version + โ†“ +Commit changes + โ†“ +Create git tag + โ†“ +Push tag + โ†“ +GitHub Actions starts + โ†“ +Build all platforms + โ†“ +Sign releases + โ†“ +Upload releases + โ†“ +Users receive updates +``` + +--- + +# Example Release Commands + +```bash id="jlwm2q" +git tag v1.0.0 +git push origin v1.0.0 +``` + +--- + +# ๐Ÿงช Auto-Update Testing + +# Test Tauri Updates + +## Local Server + +```bash id="jlwm5u" +python3 -m http.server 3000 +``` + +--- + +# Validate latest.json + +```bash id="jlwm8y" +curl http://localhost:3000/latest.json +``` + +--- + +# Test Signature + +```bash id="jlwm6g" +minisign -Vm file.sig -p release.pub +``` + +--- + +# Test Snap + +```bash id="jlwm4m" +snap refresh commdesk +``` + +--- + +# Test Flatpak + +```bash id="jlwm7m" +flatpak update +``` + +--- + +# ๐Ÿง  Rollback System + +# Snap Rollback + +```bash id="jlwm0v" +snap revert commdesk +``` + +--- + +# Flatpak Rollback + +```bash id="jlwm6v" +flatpak repair +``` + +--- + +# Manual Rollback + +Keep previous builds: + +```bash id="jlwm9b" +CommDesk.old.AppImage +``` + +--- + +# ๐Ÿ“Š Monitoring & Analytics + +Track: + +* Update success rate +* Failed installs +* Download stats +* Adoption rate +* Crash reports + +--- + +# Example Analytics Event + +```ts id="jlwm4y" +trackUpdate("installed", { + version: "1.0.0" +}); +``` + +--- + +# ๐Ÿ“ˆ Recommended Enterprise Infrastructure + +| Component | Recommended | +| --------------- | ---------------- | +| Release Hosting | GitHub Releases | +| Linux Store | Flathub | +| Ubuntu Store | Snap Store | +| Signing | Minisign | +| CI/CD | GitHub Actions | +| Monitoring | Custom analytics | + +--- + +# ๐Ÿ”ฅ Production Best Practices + +# DO + +โœ… Sign every binary +โœ… Test every release +โœ… Use stable channels +โœ… Monitor failures +โœ… Keep rollback support +โœ… Use semantic versioning +โœ… Keep release notes detailed + +--- + +# DO NOT + +โŒ Commit private keys +โŒ Disable signature verification +โŒ Ship untested releases +โŒ Force updates +โŒ Use unrestricted permissions +โŒ Skip rollback planning + +--- + +# ๐Ÿ“‹ Production Release Checklist + +## Before Release + +* [ ] Version updated +* [ ] CHANGELOG updated +* [ ] Tests passing +* [ ] Binaries signed +* [ ] latest.json generated +* [ ] GitHub release ready + +--- + +## After Release + +* [ ] GitHub release verified +* [ ] Snap uploaded +* [ ] Flathub updated +* [ ] Update notification tested +* [ ] Metrics monitored + +--- + +# ๐Ÿšจ Common Problems + +# Tauri Update Failed + +## Causes + +* Invalid latest.json +* Wrong signature +* Incorrect version format +* Broken URLs + +--- + +# Snap Not Updating + +## Fix + +```bash id="jlwm8b" +snap refresh commdesk +``` + +--- + +# Flathub Build Failed + +## Fix + +```bash id="jlwm5b" +flatpak-builder --verbose +``` + +--- + +# Signature Verification Failed + +## Fix + +Re-sign using same private key. + +--- + +# ๐ŸŽฏ Final Production Architecture + +```bash id="jlwm9m" +GitHub Actions + โ†“ +Build CommDesk + โ†“ +Sign Releases + โ†“ +Publish GitHub Release + โ†“ +Publish Snap + โ†“ +Publish Flathub + โ†“ +Users Receive Secure Updates +``` + +--- + diff --git a/docs/FLATPAK_BUILD_GUIDE.md b/docs/FLATPAK_BUILD_GUIDE.md new file mode 100644 index 0000000..4121549 --- /dev/null +++ b/docs/FLATPAK_BUILD_GUIDE.md @@ -0,0 +1,721 @@ +# ๐Ÿš€ CommDesk Linux Distribution Guide + +# Production-Ready Packaging for Flatpak, Snap, AppImage & Enterprise Linux Distribution + +CommDesk is designed as a modern large-scale desktop platform built using: + +* Tauri +* Rust +* React +* TypeScript +* Vite + +This guide explains how to package, test, optimize, and distribute CommDesk for Linux using: + +* Flatpak +* Snap +* AppImage +* Native Linux bundles +* Enterprise-grade release workflows + +--- + +# ๐Ÿ“ฆ Supported Linux Distribution Formats + +| Format | Best For | Sandbox | Auto Update | Store Support | +| -------- | ---------------------------- | -------- | ----------- | --------------- | +| Flatpak | Universal Linux Distribution | โœ… Strong | โœ… | Flathub | +| Snap | Ubuntu Ecosystem | โœ… Strong | โœ… | Snap Store | +| AppImage | Portable Distribution | โŒ | โŒ Manual | Direct Download | +| DEB | Debian/Ubuntu | โŒ | Manual/APT | Native | +| RPM | Fedora/RHEL | โŒ | Manual/DNF | Native | + +--- + +# ๐Ÿ— Recommended Production Distribution Strategy + +## Primary Distribution + +### โœ… Flatpak + +Best for: + +* Security +* Sandboxing +* Enterprise deployment +* Cross-distro support +* Flathub visibility + +--- + +## Secondary Distribution + +### โœ… AppImage + +Best for: + +* Portable usage +* No installation required +* Quick testing +* Offline environments + +--- + +## Optional Distribution + +### โœ… Snap + +Best for: + +* Ubuntu ecosystem +* Auto updates +* Canonical Store distribution + +--- + +# ๐Ÿงฑ System Requirements + +## Minimum + +| Resource | Requirement | +| -------- | --------------------- | +| RAM | 4GB | +| CPU | Dual Core | +| Storage | 500MB | +| GPU | OpenGL/Vulkan Support | + +--- + +## Recommended + +| Resource | Requirement | +| -------- | --------------------- | +| RAM | 8GB+ | +| CPU | Quad Core | +| Storage | SSD | +| GPU | Hardware acceleration | + +--- + +# ๐Ÿ”ง Required Dependencies + +--- + +# Ubuntu / Debian + +```bash +sudo apt update + +sudo apt install -y \ +flatpak \ +flatpak-builder \ +curl \ +wget \ +fuse \ +libwebkit2gtk-4.1-dev \ +build-essential \ +pkg-config \ +libssl-dev \ +libgtk-3-dev \ +librsvg2-dev \ +patchelf +``` + +--- + +# Fedora + +```bash +sudo dnf install \ +flatpak \ +flatpak-builder \ +webkit2gtk4.1-devel \ +openssl-devel \ +gtk3-devel \ +librsvg2-devel \ +patchelf +``` + +--- + +# Arch Linux + +```bash +sudo pacman -S \ +flatpak \ +flatpak-builder \ +webkit2gtk \ +base-devel \ +openssl \ +gtk3 \ +librsvg \ +patchelf +``` + +--- + +# ๐Ÿฆ€ Rust Setup + +Install Rust: + +```bash +curl https://sh.rustup.rs -sSf | sh +``` + +Verify: + +```bash +rustc --version +cargo --version +``` + +--- + +# ๐ŸŸฆ Node.js Setup + +Recommended: + +* Node.js 20+ +* pnpm latest + +Install: + +```bash +npm install -g pnpm +``` + +--- + +# ๐Ÿ“ Project Structure + +```bash +commdesk/ +โ”œโ”€โ”€ src/ +โ”œโ”€โ”€ src-tauri/ +โ”œโ”€โ”€ flatpak/ +โ”œโ”€โ”€ snap/ +โ”œโ”€โ”€ scripts/ +โ”œโ”€โ”€ dist/ +โ”œโ”€โ”€ package.json +โ”œโ”€โ”€ pnpm-lock.yaml +โ”œโ”€โ”€ org.commdesk.CommDesk.json +โ””โ”€โ”€ README.md +``` + +--- + +# ๐Ÿš€ Flatpak Packaging Guide + +# Why Flatpak? + +Flatpak provides: + +* Sandboxed execution +* Cross-distribution support +* Secure permissions +* Runtime dependency isolation +* Enterprise deployment compatibility + +--- + +# Step 1 โ€” Install Flathub + +```bash +flatpak remote-add --if-not-exists \ +--user flathub \ +https://dl.flathub.org/repo/flathub.flatpakrepo +``` + +--- + +# Step 2 โ€” Install Required SDK Extensions + +```bash +flatpak install flathub \ +org.freedesktop.Platform//25.08 \ +org.freedesktop.Sdk//25.08 \ +org.freedesktop.Sdk.Extension.rust-stable//25.08 \ +org.freedesktop.Sdk.Extension.node20//25.08 +``` + +--- + +# Step 3 โ€” Flatpak Manifest + +Create: + +```bash +org.commdesk.CommDesk.json +``` + +--- + +# Example Manifest + +```json +{ + "app-id": "org.commdesk.CommDesk", + "runtime": "org.freedesktop.Platform", + "runtime-version": "25.08", + "sdk": "org.freedesktop.Sdk", + "command": "commdesk", + "finish-args": [ + "--share=network", + "--share=ipc", + "--socket=x11", + "--socket=wayland", + "--device=dri", + "--filesystem=home" + ], + "modules": [ + { + "name": "commdesk", + "buildsystem": "simple", + "build-commands": [ + "pnpm install", + "pnpm build", + "cargo build --release" + ], + "sources": [ + { + "type": "dir", + "path": "." + } + ] + } + ] +} +``` + +--- + +# Step 4 โ€” Build Flatpak + +```bash +flatpak-builder \ +--force-clean \ +--user \ +--install-deps-from=flathub \ +--repo=repo \ +builddir \ +org.commdesk.CommDesk.json +``` + +--- + +# Step 5 โ€” Install Local Build + +```bash +flatpak install --user local org.commdesk.CommDesk +``` + +--- + +# Step 6 โ€” Run + +```bash +flatpak run org.commdesk.CommDesk +``` + +--- + +# ๐Ÿ“ฆ Create Flatpak Bundle + +```bash +flatpak build-bundle \ +repo \ +commdesk.flatpak \ +org.commdesk.CommDesk \ +--runtime-repo=https://flathub.org/repo/flathub.flatpakrepo +``` + +--- + +# ๐Ÿงช Flatpak Production Testing + +--- + +# Sandbox Testing + +```bash +flatpak run --no-documents org.commdesk.CommDesk +``` + +--- + +# Performance Testing + +```bash +flatpak run \ +--command=bash \ +org.commdesk.CommDesk \ +-c "time /app/bin/commdesk" +``` + +--- + +# Debug Logs + +```bash +G_MESSAGES_DEBUG=all \ +flatpak run org.commdesk.CommDesk +``` + +--- + +# ๐Ÿ” Flatpak Security Recommendations + +## Recommended Permissions + +| Permission | Reason | +| ----------- | --------------------- | +| network | API communication | +| wayland/x11 | GUI rendering | +| dri | GPU acceleration | +| home | User workspace access | + +--- + +## Avoid + +โŒ Full filesystem access +โŒ Unnecessary DBus access +โŒ System device permissions + +--- + +# ๐Ÿš€ Snap Packaging Guide + +# Why Snap? + +Snap provides: + +* Automatic updates +* Ubuntu ecosystem integration +* Canonical Store support +* Sandboxing +* Rollback support + +--- + +# Install Snapcraft + +## Ubuntu + +```bash +sudo apt install snapcraft +``` + +--- + +# Create Snap Directory + +```bash +mkdir snap +``` + +--- + +# Create snapcraft.yaml + +```yaml +name: commdesk +base: core24 +version: '1.0.0' +summary: CommDesk Community Management Platform +description: | + CommDesk is a modern community and event management platform. + +grade: stable +confinement: strict + +apps: + commdesk: + command: bin/commdesk + plugs: + - network + - home + - desktop + - wayland + - x11 + - opengl + +parts: + commdesk: + plugin: rust + source: . + build-packages: + - build-essential + - pkg-config + - libssl-dev + - libgtk-3-dev + - libwebkit2gtk-4.1-dev +``` + +--- + +# Build Snap + +```bash +snapcraft +``` + +--- + +# Install Local Snap + +```bash +sudo snap install commdesk_1.0.0_amd64.snap --dangerous +``` + +--- + +# Run + +```bash +snap run commdesk +``` + +--- + +# ๐ŸŸจ AppImage Packaging Guide + +# Why AppImage? + +Best for: + +* Portable distribution +* No installation +* Easy testing +* Direct downloads + +--- + +# Install Dependencies + +```bash +sudo apt install appimagekit +``` + +--- + +# Build Using Tauri + +```bash +pnpm tauri build +``` + +Generated output: + +```bash +src-tauri/target/release/bundle/appimage/ +``` + +--- + +# Make Executable + +```bash +chmod +x CommDesk.AppImage +``` + +--- + +# Run + +```bash +./CommDesk.AppImage +``` + +--- + +# ๐Ÿ“ฆ Native Linux Packages + +# DEB Build + +```bash +pnpm tauri build --bundles deb +``` + +--- + +# RPM Build + +```bash +pnpm tauri build --bundles rpm +``` + +--- + +# ๐Ÿ“ˆ Production Optimization + +# Release Build + +Always use: + +```bash +cargo build --release +``` + +--- + +# Rust Optimization + +## Cargo.toml + +```toml +[profile.release] +lto = true +codegen-units = 1 +panic = "abort" +strip = true +opt-level = "z" +``` + +--- + +# Frontend Optimization + +## vite.config.ts + +```ts +build: { + sourcemap: false, + minify: "esbuild", +} +``` + +--- + +# ๐Ÿงช Enterprise QA Checklist + +# Build Validation + +* [ ] TypeScript passes +* [ ] Rust build passes +* [ ] Flatpak launches +* [ ] Snap launches +* [ ] AppImage launches +* [ ] GPU acceleration works +* [ ] Network APIs work +* [ ] File system permissions work + +--- + +# Security Validation + +* [ ] Sandbox tested +* [ ] No unnecessary permissions +* [ ] Production env variables secured +* [ ] Secrets removed from frontend + +--- + +# Performance Validation + +* [ ] Cold start benchmark +* [ ] Memory profiling +* [ ] CPU usage profiling +* [ ] Large dataset rendering test + +--- + +# ๐Ÿ”„ CI/CD Pipeline + +# GitHub Actions Example + +```yaml +name: Linux Builds + +on: + push: + branches: + - main + +jobs: + build: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + + - uses: pnpm/action-setup@v4 + + - uses: actions/setup-node@v4 + with: + node-version: 20 + + - name: Install Rust + uses: dtolnay/rust-toolchain@stable + + - name: Install dependencies + run: pnpm install + + - name: Type Check + run: pnpm tsc --noEmit + + - name: Build Frontend + run: pnpm build + + - name: Build Tauri + run: pnpm tauri build +``` + +--- + +# ๐Ÿš€ Flathub Submission Guide + +## Before Submission + +Ensure: + +* App icons added +* Metadata complete +* Screenshots prepared +* License included +* Permissions minimized +* Stable builds verified + +--- + +# Required Assets + +| Asset | Required | +| ------------ | -------- | +| App Icon | โœ… | +| Screenshots | โœ… | +| AppData XML | โœ… | +| LICENSE | โœ… | +| Desktop File | โœ… | + +--- + +# Submit To + +[Flathub Submission Docs](https://docs.flathub.org/docs/for-app-authors/submission/?utm_source=chatgpt.com) + +--- + +# ๐Ÿ“š Useful Resources + +* [Flatpak Documentation](https://docs.flatpak.org/?utm_source=chatgpt.com) +* [Snapcraft Docs](https://snapcraft.io/docs?utm_source=chatgpt.com) +* [Tauri Distribution Guide](https://tauri.app/distribute/?utm_source=chatgpt.com) +* [AppImage Docs](https://docs.appimage.org/?utm_source=chatgpt.com) +* [Flathub](https://flathub.org/?utm_source=chatgpt.com) + +--- + +# โœ… Recommended Final Production Stack + +## Best Combination For CommDesk + +| Distribution | Priority | +| ------------ | ---------- | +| Flatpak | Primary | +| AppImage | Secondary | +| Snap | Optional | +| DEB/RPM | Enterprise | + +--- + diff --git a/docs/FLATPAK_COMMANDS.sh b/docs/FLATPAK_COMMANDS.sh new file mode 100644 index 0000000..e22da3e --- /dev/null +++ b/docs/FLATPAK_COMMANDS.sh @@ -0,0 +1,179 @@ +#!/usr/bin/env bash +# CommDesk Flatpak Quick Reference & Commands + +# ============================================================================ +# SETUP & INSTALLATION +# ============================================================================ + +# 1. Install flatpak tools (run once) +# Ubuntu/Debian: +sudo apt install flatpak flatpak-builder gnome-software-plugin-flatpak + +# Fedora: +sudo dnf install flatpak flatpak-builder + +# Arch: +sudo pacman -S flatpak flatpak-builder + +# 2. Add Flathub repository (run once) +flatpak remote-add --if-not-exists --user flathub https://dl.flathub.org/repo/flathub.flatpakrepo + + +# ============================================================================ +# BUILD & INSTALL +# ============================================================================ + +# Clean build (removes old artifacts) +flatpak-builder --force-clean --user --install-deps-from=flathub --repo=repo builddir org.commdesk.CommDesk.json + +# Incremental build (keeps cached artifacts) +flatpak-builder --user --install-deps-from=flathub --repo=repo builddir org.commdesk.CommDesk.json + +# Install after building +flatpak install --user --from-file=repo/appstream/org.commdesk.CommDesk.flatpakref + +# One-liner: build and install +flatpak-builder --force-clean --user --install-deps-from=flathub --repo=repo builddir org.commdesk.CommDesk.json && \ + flatpak install --user --from-file=repo/appstream/org.commdesk.CommDesk.flatpakref + + +# ============================================================================ +# RUNNING & TESTING +# ============================================================================ + +# Run the app +flatpak run org.commdesk.CommDesk + +# Run with verbose logging +G_MESSAGES_DEBUG=all flatpak run org.commdesk.CommDesk + +# Run with a bash shell (for debugging) +flatpak run --command=bash org.commdesk.CommDesk + +# Test without document access +flatpak run --no-documents org.commdesk.CommDesk + +# Run shell as app user +flatpak run --command=sh org.commdesk.CommDesk + + +# ============================================================================ +# DEBUGGING & INFO +# ============================================================================ + +# View installed version +flatpak info org.commdesk.CommDesk + +# Check permissions +flatpak info --show-permissions org.commdesk.CommDesk + +# List all installed flatpaks +flatpak list --app + +# View app data location +flatpak info --mode=user --show-location org.commdesk.CommDesk + + +# ============================================================================ +# PACKAGE CREATION & DISTRIBUTION +# ============================================================================ + +# Create single-file bundle for distribution +flatpak build-bundle repo commdesk.flatpak org.commdesk.CommDesk \ + --runtime-repo=https://flathub.org/repo/flathub.flatpakrepo + +# Users can install the bundle with: +# flatpak install --user commdesk.flatpak + + +# ============================================================================ +# MAINTENANCE & UPDATES +# ============================================================================ + +# Update flatpak runtime +flatpak update + +# Remove the app +flatpak remove org.commdesk.CommDesk + +# Uninstall and remove data +flatpak remove --delete-data org.commdesk.CommDesk + +# Clean up unused runtimes +flatpak remove --unused + + +# ============================================================================ +# BUILD ENVIRONMENT +# ============================================================================ + +# Enter the build sandbox to debug +flatpak run --command=bash --develop-mode builddir + +# View build logs (while building) +tail -f /tmp/flatpak-builder-*.log + + +# ============================================================================ +# KEY FILES +# ============================================================================ + +# Manifest (main configuration) +# org.commdesk.CommDesk.json + +# Desktop entry (app integration) +# org.commdesk.CommDesk.desktop + +# Build documentation +# docs/FLATPAK_BUILD_GUIDE.md +# docs/FLATPAK_SETUP_SUMMARY.md + +# Application icon +# public/logo.png + + +# ============================================================================ +# USEFUL ENVIRONMENT VARIABLES +# ============================================================================ + +# Enable debug logging +export G_MESSAGES_DEBUG=all + +# Show Flatpak internal operations +export FLATPAK_DEBUG=1 + +# Offline mode (for testing without dependencies) +export CARGO_NET_OFFLINE=true + + +# ============================================================================ +# COMMON ISSUES & SOLUTIONS +# ============================================================================ + +# Issue: Build fails with "No matching version" +# Solution: Update runtime-version in org.commdesk.CommDesk.json + +# Issue: Permission denied errors +# Solution: Add required permissions to finish-args in manifest + +# Issue: Rust compilation errors +# Solution: Install Rust extension: +flatpak install flathub org.freedesktop.Sdk.Extension.rust-stable//25.08 + +# Issue: Node/pnpm not found +# Solution: Install Node extension: +flatpak install flathub org.freedesktop.Sdk.Extension.node20//25.08 + +# Issue: App won't start +# Solution: Check logs: +G_MESSAGES_DEBUG=all flatpak run org.commdesk.CommDesk 2>&1 + + +# ============================================================================ +# RESOURCES +# ============================================================================ + +# Official Flatpak docs: https://docs.flatpak.org/ +# Manifest reference: https://docs.flatpak.org/en/latest/reference.html +# Flathub submit: https://docs.flathub.org/docs/for-app-authors/submission/ +# Tauri Flatpak: https://tauri.app/develop/distributing-packages/#flatpak diff --git a/docs/PRODUCTION_DEPLOYMENT.md b/docs/PRODUCTION_DEPLOYMENT.md new file mode 100644 index 0000000..296437e --- /dev/null +++ b/docs/PRODUCTION_DEPLOYMENT.md @@ -0,0 +1,449 @@ +# ๐Ÿง CommDesk Linux Packaging & Production Deployment Documentation System + +## Overview + + +The goal is to transform CommDesk into a fully production-ready desktop platform capable of large-scale Linux distribution through: + +* Flatpak +* Snap +* AppImage +* DEB +* RPM +* GitHub Releases +* Flathub +* Snap Store + +Reference documentation: + +--- + +# ๐Ÿš€ Objectives + +## Primary Goals + +* Add professional Linux distribution support +* Introduce production deployment workflows +* Add enterprise-grade release architecture +* Standardize build systems +* Implement secure auto-update infrastructure +* Create scalable CI/CD pipelines +* Add cross-platform packaging strategy +* Improve release maintainability +* Prepare CommDesk for public distribution + +--- + +# ๐Ÿ“ฆ Distribution Targets + +## Linux + +* Flatpak +* Snap +* AppImage +* DEB +* RPM + +## Windows + +* NSIS +* MSI +* Portable EXE + +## macOS + +* DMG +* App Bundle + +--- + + + +# ๐ŸŸฆ Flatpak Infrastructure + +## Add Flatpak Manifest + +Create: + +```bash +org.commdesk.CommDesk.json +``` + +## Required Features + +* Sandboxed runtime +* Flathub compatibility +* GPU acceleration support +* Network permissions +* Wayland + X11 support +* Rust SDK extensions +* Node.js SDK extensions + +--- + +## Required Build Commands + +```bash +flatpak-builder \ +--force-clean \ +--user \ +--install-deps-from=flathub \ +--repo=repo \ +builddir \ +org.commdesk.CommDesk.json +``` + +--- + +# ๐Ÿ“ฆ Snap Infrastructure + +## Create Snap Support + +Create: + +```bash +snap/snapcraft.yaml +``` + +## Required Features + +* Strict confinement +* Network permissions +* OpenGL support +* Wayland/X11 support +* Auto-update compatibility + +--- + +# ๐ŸŸจ AppImage Support + +## Add Portable Linux Distribution + +Support: + +```bash +pnpm tauri build +``` + +Output: + +```bash +src-tauri/target/release/bundle/appimage/ +``` + +--- + +# ๐Ÿ”„ Auto-Update Infrastructure + +## Required System + +Implement: + +* Tauri updater +* GitHub Releases integration +* Signed updates +* Release manifests +* Version verification +* Secure update validation + +--- + +## Required Files + +```bash +src-tauri/tauri.conf.json +latest.json +release.pub +``` + +--- + +## Required Features + +* Silent background downloads +* Update notifications +* Signature verification +* Rollback safety +* Cross-platform updates + +--- + +# ๐Ÿ” Security & Signing + +## Required Security Features + +### Linux + +* Flatpak sandboxing +* Snap confinement +* Minimal filesystem access + +### Updates + +* Minisign signatures +* Binary verification +* Release integrity validation + +### Windows + +* Code signing support + +### macOS + +* Apple notarization preparation + +--- + +# ๐Ÿ“ˆ CI/CD Pipeline + +## Create GitHub Actions Workflows + +### Required Workflows + +```bash +.github/workflows/ +โ”œโ”€โ”€ ci.yml +โ”œโ”€โ”€ release.yml +โ”œโ”€โ”€ flatpak.yml +โ”œโ”€โ”€ snap.yml +โ””โ”€โ”€ production-build.yml +``` + +--- + +## CI Requirements + +### Validation + +* TypeScript checks +* ESLint checks +* Rust checks +* Build verification +* Packaging verification + +### Build Matrix + +* Ubuntu +* Windows +* macOS + +### Artifacts + +Upload: + +* AppImage +* Flatpak bundle +* Snap package +* DEB +* RPM +* MSI +* DMG + +--- + +# ๐Ÿท Version Management System + +## Standardize SemVer + +Format: + +```bash +MAJOR.MINOR.PATCH +``` + +--- + +## Synchronize Versions Across + +```bash +package.json +src-tauri/Cargo.toml +src-tauri/tauri.conf.json +snap/snapcraft.yaml +``` + +--- + +## Create Automation Script + +```bash +scripts/update-version.sh +``` + +Capabilities: + +* Update all version files +* Validate consistency +* Prevent release mismatch + +--- + +# ๐ŸŽจ Branding & Icon System + +## Standardize Icon Pipeline + +Required Sizes: + +* 32x32 +* 64x64 +* 128x128 +* 256x256 +* ICO +* ICNS + +--- + +## Required Directories + +```bash +public/ +src-tauri/icons/ +``` + +--- + +## Add Documentation + +Include: + +* Logo generation workflow +* Export best practices +* Platform-specific icon requirements + +--- + +# ๐Ÿงช Enterprise QA System + +## Required Testing Layers + +### Unit Testing + +```bash +pnpm test +``` + +### E2E Testing + +```bash +playwright +``` + +### Production Validation + +* Flatpak sandbox tests +* AppImage runtime tests +* Snap permission tests +* Auto-update tests + +--- + +# โšก Performance Optimization + +## Rust Optimization + +Add: + +```toml +[profile.release] +lto = true +codegen-units = 1 +panic = "abort" +strip = true +opt-level = "z" +``` + +--- + +## Frontend Optimization + +Add: + +* Code splitting +* Lazy loading +* Vendor chunking +* Production minification + +--- + +# ๐Ÿ“Š Monitoring & Analytics + +## Add Optional Infrastructure + +### Crash Reporting + +* Rust panic reporting +* Frontend error tracking + +### Update Analytics + +* Update adoption rate +* Failed update tracking +* Release stability metrics + +--- + +# ๐Ÿ“š Documentation Requirements + +All deployment docs must include: + +* Prerequisites +* Installation +* Build commands +* Release workflow +* Security recommendations +* Troubleshooting +* CI/CD examples +* Production best practices + +--- + +# ๐Ÿง  Important Requirements + +## DO NOT + +* Hardcode secrets +* Commit private signing keys +* Disable security checks +* Use unrestricted filesystem permissions +* Skip binary verification + +--- + +# โœ… Acceptance Criteria + +## Packaging + +* [ ] Flatpak builds successfully +* [ ] Snap builds successfully +* [ ] AppImage builds successfully +* [ ] DEB builds successfully +* [ ] RPM builds successfully + +--- + +## Security + +* [ ] Auto-update signing works +* [ ] Signature verification works +* [ ] Sandboxing validated +* [ ] Minimal permissions enforced + +--- + +## CI/CD + +* [ ] Multi-platform builds work +* [ ] Release workflows automated +* [ ] Artifact uploads work +* [ ] Release tagging works + +--- + +## Documentation + +* [ ] Linux packaging docs completed +* [ ] Production deployment docs completed +* [ ] Auto-update docs completed +* [ ] Troubleshooting docs completed +* [ ] Release workflow documented + diff --git a/docs/TESTING_AND_QA.md b/docs/TESTING_AND_QA.md new file mode 100644 index 0000000..7f25638 --- /dev/null +++ b/docs/TESTING_AND_QA.md @@ -0,0 +1,652 @@ +# ๐Ÿงช CommDesk Enterprise Testing & QA Guide + +# Production-Ready โ€ข Enterprise QA โ€ข Large Scale Testing Infrastructure + +This document defines the complete testing architecture, QA workflows, automation strategy, performance validation, security testing, and release validation system for CommDesk. + +Reference guide: + +--- + +# ๐ŸŽฏ Testing Goals + +CommDesk is a large-scale desktop application built using: + +* React +* TypeScript +* Tauri +* Rust +* Vite + +The testing system must guarantee: + +* Stability +* Scalability +* Security +* Performance +* Cross-platform reliability +* Release confidence + +--- + +# ๐Ÿ— Testing Architecture + +# Testing Pyramid + +```bash id="7b5r0h" + End-to-End Tests (5%) + Integration Tests (20%) + Unit Tests (75%) +``` + +--- + +# ๐Ÿงฑ Testing Layers + +| Layer | Purpose | +| ----------------- | --------------------------------------- | +| Unit Tests | Component and function validation | +| Integration Tests | Feature/system interaction validation | +| E2E Tests | Real user workflow testing | +| Performance Tests | Benchmarking and optimization | +| Security Tests | Vulnerability and permission validation | +| Platform Tests | OS-specific verification | +| Regression Tests | Existing feature protection | + +--- + +# โš™๏ธ Unit Testing Setup + +## Install Dependencies + +```bash id="lnq6np" +pnpm add -D \ +vitest \ +@testing-library/react \ +@testing-library/user-event \ +jsdom +``` + +--- + +# Configure Vitest + +Create: + +```bash id="m5j3a7" +vitest.config.ts +``` + +--- + +# Example Configuration + +```ts id="7dx6yo" +import { defineConfig } from "vitest/config"; +import react from "@vitejs/plugin-react"; + +export default defineConfig({ + plugins: [react()], + test: { + globals: true, + environment: "jsdom", + + coverage: { + provider: "v8", + reporter: ["text", "json", "html"], + + lines: 80, + functions: 80, + branches: 75, + statements: 80, + }, + }, +}); +``` + +--- + +# ๐Ÿงช Unit Test Example + +```tsx id="p20mfm" +describe("EventCard", () => { + it("should render title", () => { + render(); + + expect( + screen.getByText("Hackathon 2026") + ).toBeInTheDocument(); + }); +}); +``` + +--- + +# Run Unit Tests + +```bash id="wjlwm9" +pnpm test +``` + +--- + +# Watch Mode + +```bash id="jlwmti" +pnpm test --watch +``` + +--- + +# Coverage Report + +```bash id="y2d4xk" +pnpm test --coverage +``` + +--- + +# ๐Ÿ”„ Integration Testing + +# Goals + +Validate: + +* API interaction +* State management +* React Query behavior +* IPC communication +* Feature coordination + +--- + +# Example Integration Test + +```tsx id="q50ezn" +describe("Dashboard Integration", () => { + it("should load events", async () => { + render(); + + await waitFor(() => { + expect( + screen.getByText("Event 1") + ).toBeInTheDocument(); + }); + }); +}); +``` + +--- + +# ๐ŸŒ End-to-End Testing + +# Framework + +Use: + +```bash id="jlwm7j" +Playwright +``` + +--- + +# Install + +```bash id="d6jtzg" +pnpm add -D @playwright/test +``` + +--- + +# Initialize Browsers + +```bash id="tjlwmm" +pnpm exec playwright install +``` + +--- + +# Configure Playwright + +Create: + +```bash id="xymu12" +playwright.config.ts +``` + +--- + +# Required Browser Targets + +* Chromium +* Firefox +* WebKit + +--- + +# E2E Test Goals + +Validate: + +* Authentication +* Navigation +* Event creation +* Community workflows +* Dashboard interaction +* Permissions +* Error handling + +--- + +# Example E2E Test + +```ts id="rf1s6m" +test("should create event", async ({ page }) => { + await page.goto("/"); + + await page.click("[data-testid='btn-create-event']"); + + await page.fill( + "[data-testid='input-title']", + "Hackathon" + ); + + await page.click("[data-testid='btn-submit']"); + + await expect( + page.locator("text=Hackathon") + ).toBeVisible(); +}); +``` + +--- + +# Run E2E Tests + +```bash id="e4v3b9" +pnpm exec playwright test +``` + +--- + +# UI Mode + +```bash id="nhyw1z" +pnpm exec playwright test --ui +``` + +--- + +# Debug Mode + +```bash id="9f0wmt" +pnpm exec playwright test --debug +``` + +--- + +# ๐Ÿง Linux Platform Testing + +# Flatpak Testing + +--- + +# Build + +```bash id="31s31s" +flatpak-builder \ +--force-clean \ +--user \ +--install-deps-from=flathub \ +--repo=repo \ +builddir \ +org.commdesk.CommDesk.json +``` + +--- + +# Install + +```bash id="4s7v52" +flatpak install \ +--user \ +--from-file=repo/appstream/org.commdesk.CommDesk.flatpakref +``` + +--- + +# Validate Runtime + +```bash id="fsry1o" +flatpak run org.commdesk.CommDesk +``` + +--- + +# Permission Testing + +```bash id="r1fq4i" +flatpak info --show-permissions org.commdesk.CommDesk +``` + +--- + +# Sandbox Validation + +```bash id="1ysvbm" +flatpak run --filesystem=none org.commdesk.CommDesk +``` + +--- + +# Log Inspection + +```bash id="jlwm9w" +journalctl --user \ +-u flatpak-org.commdesk.CommDesk \ +--lines=50 +``` + +--- + +# ๐ŸชŸ Windows Testing + +# Required Validation + +* Installer works +* Desktop shortcut created +* Start menu integration works +* Taskbar icon renders +* Auto-update works +* Uninstall works cleanly + +--- + +# Build + +```bash id="sjmc67" +pnpm tauri build --target x86_64-pc-windows-gnu +``` + +--- + +# ๐ŸŽ macOS Testing + +# Required Validation + +* DMG mounts correctly +* App bundle launches +* Dock icon renders +* Code signing valid +* Notarization ready + +--- + +# Verify Signature + +```bash id="d0bjlwm" +codesign -v /Applications/CommDesk.app +``` + +--- + +# Security Validation + +```bash id="wt0jlwm" +spctl -a -v /Applications/CommDesk.app +``` + +--- + +# โšก Performance Testing + +# Startup Benchmark + +Target: + +```bash id="x0rm4s" +< 3 seconds +``` + +--- + +# Measure Startup Time + +```bash id="jlwm6m" +time flatpak run org.commdesk.CommDesk +``` + +--- + +# CPU Profiling + +```bash id="wrv2mw" +perf record flatpak run org.commdesk.CommDesk +perf report +``` + +--- + +# Memory Usage + +```bash id="jlwm91" +/usr/bin/time -v flatpak run org.commdesk.CommDesk +``` + +--- + +# Real-Time Monitoring + +```bash id="3g0lkh" +watch -n 1 'ps aux | grep commdesk' +``` + +--- + +# ๐Ÿ”ฅ Large Dataset Testing + +# Validate + +* 10,000+ tasks +* 5,000+ events +* Massive dashboards +* Large activity feeds +* Infinite scrolling +* Search performance + +--- + +# Example Benchmark + +```ts id="jlwm2s" +bench("search 10000 events", () => { + searchEvents(events, "Hackathon"); +}); +``` + +--- + +# ๐Ÿ” Security Testing + +# Dependency Audit + +```bash id="9jlwmc" +pnpm audit --prod +``` + +--- + +# OWASP Validation + +```bash id="jlwm4u" +npm audit --audit-level=moderate +``` + +--- + +# Required Security Checks + +* Sandbox validation +* Permission minimization +* IPC validation +* Unsafe eval prevention +* CSP verification +* Dependency vulnerabilities +* Rust unsafe block review + +--- + +# ๐Ÿ”„ Regression Testing + +Before every release validate: + +* Existing workflows still work +* No UI regressions +* No performance regressions +* Database compatibility maintained +* Auto-update compatibility maintained + +--- + +# ๐Ÿ“ˆ Coverage Goals + +| Type | Minimum | Target | +| ---------- | ------- | ------ | +| Statements | 80% | 90% | +| Branches | 75% | 85% | +| Functions | 80% | 90% | +| Lines | 80% | 90% | + +--- + +# ๐Ÿš€ CI/CD Testing Pipeline + +Create: + +```bash id="jlwmj1" +.github/workflows/test.yml +``` + +--- + +# Required Pipeline Steps + +```yaml id="jlwm0q" +- pnpm install +- pnpm lint +- pnpm test +- pnpm test --coverage +- playwright test +- pnpm build +- pnpm tauri build +``` + +--- + +# Required CI Validation + +| Validation | Required | +| ----------------- | -------- | +| TypeScript | โœ… | +| ESLint | โœ… | +| Unit Tests | โœ… | +| Integration Tests | โœ… | +| E2E Tests | โœ… | +| Production Build | โœ… | +| Linux Packaging | โœ… | + +--- + +# ๐Ÿง  Testing Best Practices + +## Rules + +### DO + +โœ… Test behavior +โœ… Test error states +โœ… Test edge cases +โœ… Test permissions +โœ… Test offline states +โœ… Test loading states +โœ… Test accessibility + +--- + +### DO NOT + +โŒ Test implementation details +โŒ Overuse mocks +โŒ Skip error testing +โŒ Ignore performance +โŒ Ignore accessibility + +--- + +# โ™ฟ Accessibility Testing + +Validate: + +* Keyboard navigation +* Screen reader support +* Focus management +* ARIA labels +* Contrast ratios +* Reduced motion support + +--- + +# ๐Ÿงช Release QA Checklist + +# Before Production Release + +## Core Validation + +* [ ] Unit tests pass +* [ ] Integration tests pass +* [ ] E2E tests pass +* [ ] TypeScript passes +* [ ] ESLint passes + +--- + +## Platform Validation + +* [ ] Flatpak works +* [ ] Snap works +* [ ] AppImage works +* [ ] Windows installer works +* [ ] macOS DMG works + +--- + +## Performance Validation + +* [ ] Startup < 3 sec +* [ ] No memory leaks +* [ ] No major CPU spikes +* [ ] Large datasets render smoothly + +--- + +## Security Validation + +* [ ] No high vulnerabilities +* [ ] Sandboxing works +* [ ] Auto-update signatures valid +* [ ] No unsafe permissions + +--- + +# ๐Ÿ“š Recommended Tooling + +| Tool | Purpose | +| --------------- | ------------------------- | +| Vitest | Unit testing | +| Testing Library | Component testing | +| Playwright | E2E testing | +| Lighthouse | Performance/accessibility | +| Perf | Linux profiling | +| Valgrind | Memory validation | +| Codecov | Coverage reporting | + diff --git a/latest.json b/latest.json new file mode 100644 index 0000000..e2e2f46 --- /dev/null +++ b/latest.json @@ -0,0 +1,23 @@ +{ + "version": "0.1.0", + "notes": "Initial production release", + "pub_date": "2026-05-10T00:00:00Z", + "platforms": { + "linux-x86_64": { + "signature": "", + "url": "" + }, + "darwin-aarch64": { + "signature": "", + "url": "" + }, + "darwin-x86_64": { + "signature": "", + "url": "" + }, + "windows-x86_64": { + "signature": "", + "url": "" + } + } +} \ No newline at end of file diff --git a/org.commdesk.CommDesk.desktop b/org.commdesk.CommDesk.desktop new file mode 100644 index 0000000..980b4f1 --- /dev/null +++ b/org.commdesk.CommDesk.desktop @@ -0,0 +1,9 @@ +[Desktop Entry] +Type=Application +Name=CommDesk +Comment=Community communication desktop application +Exec=commdesk +Icon=org.commdesk.CommDesk +Categories=Utility; +Terminal=false +StartupNotify=true diff --git a/org.commdesk.CommDesk.json b/org.commdesk.CommDesk.json index 367d553..6d6ca43 100644 --- a/org.commdesk.CommDesk.json +++ b/org.commdesk.CommDesk.json @@ -1,7 +1,7 @@ { "app-id": "org.commdesk.CommDesk", "runtime": "org.freedesktop.Platform", - "runtime-version": "23.08", + "runtime-version": "25.08", "sdk": "org.freedesktop.Sdk", "sdk-extensions": [ "org.freedesktop.Sdk.Extension.rust-stable", @@ -13,7 +13,9 @@ "--socket=x11", "--socket=wayland", "--share=ipc", - "--filesystem=home" + "--filesystem=home", + "--device=dri", + "--env=LIBVA_DRIVER_NAME=iHD" ], "build-options": { "append-path": "/usr/lib/sdk/rust-stable/bin:/usr/lib/sdk/node20/bin" @@ -22,11 +24,19 @@ { "name": "commdesk", "buildsystem": "simple", + "build-options": { + "env": { + "CARGO_NET_OFFLINE": "true" + } + }, "build-commands": [ - "npm install", - "npm run build", + "npm install -g pnpm", + "pnpm install --frozen-lockfile", + "pnpm run build", "cargo build --manifest-path src-tauri/Cargo.toml --release", - "install -Dm755 src-tauri/target/release/apex-circle-dasktop-application /app/bin/commdesk" + "install -Dm755 src-tauri/target/release/apex-circle-dasktop-application /app/bin/commdesk", + "install -Dm644 org.commdesk.CommDesk.desktop /app/share/applications/org.commdesk.CommDesk.desktop", + "install -Dm644 public/logo.png /app/share/icons/hicolor/256x256/apps/org.commdesk.CommDesk.png" ], "sources": [ { diff --git a/release.pub b/release.pub new file mode 100644 index 0000000..196d4cb --- /dev/null +++ b/release.pub @@ -0,0 +1,2 @@ +untrusted comment: minisign public key 7BCD4862EDE01123 +RWQjEeDtYkjNe7hdKeyXez1ugL2oioQymSO2IWLvoZ2aFUWyiWoOK18u diff --git a/src-tauri/tauri.conf.json b/src-tauri/tauri.conf.json index 83cb428..3e25ebb 100644 --- a/src-tauri/tauri.conf.json +++ b/src-tauri/tauri.conf.json @@ -65,7 +65,7 @@ "plugins": { "updater": { - "pubkey": "dW50cnVzdGVkIGNvbW1lbnQ6IG1pbmlzaWduIHB1YmxpYyBrZXk6IDc3MjdGODk5Q0JBREJCMkMKUldRc3U2M0xtZmduZDh5QkVrdW8zd25wYllnN2tWR1RGalpLMFhtZ01vRVhtU0VPRVNxcHNqbWQK", + "pubkey": "7BCD4862EDE01123RWQjEeDtYkjNe7hdKeyXez1ugL2oioQymSO2IWLvoZ2aFUWyiWoOK18u", "endpoints": [ "https://github.com/NexGenStudioDev/CommDesk/releases/latest/download/latest.json"