|
| 1 | +# CommDesk Tauri Auto-Update (Production Guide) |
| 2 | + |
| 3 | +This guide documents a production-ready updater setup for CommDesk using: |
| 4 | + |
| 5 | +- Tauri v2 updater plugin |
| 6 | +- Signed update artifacts |
| 7 | +- GitHub Releases as update hosting |
| 8 | +- GitHub Actions for automated cross-platform builds and publishing |
| 9 | + |
| 10 | +--- |
| 11 | + |
| 12 | +## 1) Implemented project structure |
| 13 | + |
| 14 | +```text |
| 15 | +CommDesk/ |
| 16 | +├── .github/ |
| 17 | +│ └── workflows/ |
| 18 | +│ └── tauri-all-platforms.yml |
| 19 | +├── docs/ |
| 20 | +│ ├── Tauri_Auto_Update_Production_Guide.md |
| 21 | +│ └── latest.json.example |
| 22 | +├── src/ |
| 23 | +│ ├── App.tsx |
| 24 | +│ └── system/ |
| 25 | +│ └── updater/ |
| 26 | +│ └── autoUpdater.ts |
| 27 | +└── src-tauri/ |
| 28 | + ├── Cargo.toml |
| 29 | + ├── tauri.conf.json |
| 30 | + ├── src/ |
| 31 | + │ └── lib.rs |
| 32 | + └── capabilities/ |
| 33 | + └── default.json |
| 34 | +``` |
| 35 | + |
| 36 | +--- |
| 37 | + |
| 38 | +## 2) Updater plugin installation and configuration |
| 39 | + |
| 40 | +### JavaScript dependencies |
| 41 | + |
| 42 | +```bash |
| 43 | +pnpm add @tauri-apps/plugin-updater @tauri-apps/plugin-process |
| 44 | +``` |
| 45 | + |
| 46 | +### Rust dependencies (`src-tauri/Cargo.toml`) |
| 47 | + |
| 48 | +```toml |
| 49 | +[dependencies] |
| 50 | +tauri = { version = "2", features = [] } |
| 51 | +tauri-plugin-opener = "2" |
| 52 | +tauri-plugin-process = "2" |
| 53 | +tauri-plugin-updater = "2" |
| 54 | +``` |
| 55 | + |
| 56 | +### Rust plugin registration (`src-tauri/src/lib.rs`) |
| 57 | + |
| 58 | +```rust |
| 59 | +tauri::Builder::default() |
| 60 | + .plugin(tauri_plugin_opener::init()) |
| 61 | + .plugin(tauri_plugin_process::init()) |
| 62 | + .plugin(tauri_plugin_updater::init()) |
| 63 | + .run(tauri::generate_context!()) |
| 64 | + .expect("error while running tauri application"); |
| 65 | +``` |
| 66 | + |
| 67 | +### Tauri config (`src-tauri/tauri.conf.json`) |
| 68 | + |
| 69 | +```json |
| 70 | +{ |
| 71 | + "bundle": { |
| 72 | + "active": true, |
| 73 | + "targets": "all", |
| 74 | + "createUpdaterArtifacts": true |
| 75 | + }, |
| 76 | + "plugins": { |
| 77 | + "updater": { |
| 78 | + "pubkey": "REPLACE_WITH_TAURI_UPDATER_PUBLIC_KEY", |
| 79 | + "endpoints": [ |
| 80 | + "https://github.com/NexGenStudioDev/CommDesk/releases/latest/download/latest.json" |
| 81 | + ], |
| 82 | + "windows": { |
| 83 | + "installMode": "passive" |
| 84 | + } |
| 85 | + } |
| 86 | + } |
| 87 | +} |
| 88 | +``` |
| 89 | + |
| 90 | +### Tauri capability permissions (`src-tauri/capabilities/default.json`) |
| 91 | + |
| 92 | +```json |
| 93 | +{ |
| 94 | + "permissions": [ |
| 95 | + "core:default", |
| 96 | + "opener:default", |
| 97 | + "updater:default", |
| 98 | + "process:default" |
| 99 | + ] |
| 100 | +} |
| 101 | +``` |
| 102 | + |
| 103 | +--- |
| 104 | + |
| 105 | +## 3) Frontend auto-update implementation |
| 106 | + |
| 107 | +`src/system/updater/autoUpdater.ts` runs startup checks, downloads/install updates, and relaunches. |
| 108 | + |
| 109 | +`src/App.tsx` starts updater once with `useEffect()`. |
| 110 | + |
| 111 | +Key behavior: |
| 112 | + |
| 113 | +- Runs only in Tauri runtime (not plain browser) |
| 114 | +- Skips update checks in dev mode |
| 115 | +- Performs background checks every 6 hours |
| 116 | +- Automatically installs found updates |
| 117 | +- Relaunches app after install |
| 118 | + |
| 119 | +--- |
| 120 | + |
| 121 | +## 4) Generate signing keys securely |
| 122 | + |
| 123 | +Run once on a secure machine: |
| 124 | + |
| 125 | +```bash |
| 126 | +pnpm tauri signer generate -- -w ~/.tauri/commdesk.key |
| 127 | +``` |
| 128 | + |
| 129 | +This outputs: |
| 130 | + |
| 131 | +- Private key file: `~/.tauri/commdesk.key` (secret, never commit) |
| 132 | +- Public key text: put this into `tauri.conf.json` `plugins.updater.pubkey` |
| 133 | + |
| 134 | +### GitHub repository secrets |
| 135 | + |
| 136 | +Set these in **Settings → Secrets and variables → Actions**: |
| 137 | + |
| 138 | +- `TAURI_SIGNING_PRIVATE_KEY` → full private key content (or key path content) |
| 139 | +- `TAURI_SIGNING_PRIVATE_KEY_PASSWORD` → password if key is encrypted (can be empty) |
| 140 | + |
| 141 | +--- |
| 142 | + |
| 143 | +## 5) `latest.json` update manifest |
| 144 | + |
| 145 | +For GitHub Releases, `tauri-action` generates and uploads `latest.json` automatically when `uploadUpdaterJson: true` is set. |
| 146 | + |
| 147 | +Reference format is in `docs/latest.json.example`. |
| 148 | + |
| 149 | +Required fields are: |
| 150 | + |
| 151 | +- `version` |
| 152 | +- `platforms.<os>-<arch>.url` |
| 153 | +- `platforms.<os>-<arch>.signature` |
| 154 | + |
| 155 | +Platform keys usually include: |
| 156 | + |
| 157 | +- `linux-x86_64` (AppImage) |
| 158 | +- `windows-x86_64` (MSI/EXE) |
| 159 | +- `darwin-x86_64` or `darwin-aarch64` (macOS) |
| 160 | + |
| 161 | +--- |
| 162 | + |
| 163 | +## 6) Hosting updates on GitHub Releases |
| 164 | + |
| 165 | +Updater endpoint is configured as: |
| 166 | + |
| 167 | +```text |
| 168 | +https://github.com/NexGenStudioDev/CommDesk/releases/latest/download/latest.json |
| 169 | +``` |
| 170 | + |
| 171 | +Flow at runtime: |
| 172 | + |
| 173 | +1. App downloads `latest.json` |
| 174 | +2. Tauri selects matching platform entry |
| 175 | +3. App downloads bundle from release asset URL |
| 176 | +4. Signature verified against configured public key |
| 177 | +5. Install proceeds only if signature is valid |
| 178 | + |
| 179 | +--- |
| 180 | + |
| 181 | +## 7) GitHub Actions auto build + publish |
| 182 | + |
| 183 | +Workflow: `.github/workflows/tauri-all-platforms.yml` |
| 184 | + |
| 185 | +Capabilities: |
| 186 | + |
| 187 | +- Matrix build on Linux, Windows, macOS |
| 188 | +- Creates/updates release for tag |
| 189 | +- Uploads bundles and signatures |
| 190 | +- Uploads `latest.json` for updater |
| 191 | + |
| 192 | +### Release command flow |
| 193 | + |
| 194 | +```bash |
| 195 | +# 1) bump versions in package.json and src-tauri/tauri.conf.json |
| 196 | +git add . |
| 197 | +git commit -m "release: v0.1.1" |
| 198 | + |
| 199 | +# 2) tag + push |
| 200 | +git tag v0.1.1 |
| 201 | +git push origin master --tags |
| 202 | +``` |
| 203 | + |
| 204 | +Workflow can also run manually via `workflow_dispatch` with `tag_name`. |
| 205 | + |
| 206 | +--- |
| 207 | + |
| 208 | +## 8) Security best practices (production) |
| 209 | + |
| 210 | +1. Never commit private signing keys. |
| 211 | +2. Rotate keys only with a planned migration path (old clients trust old pubkey). |
| 212 | +3. Keep updater endpoint HTTPS-only. |
| 213 | +4. Keep `dangerousInsecureTransportProtocol` disabled. |
| 214 | +5. Restrict GitHub Actions permissions and protect release tags. |
| 215 | +6. Enable branch protection + required reviews for release branches. |
| 216 | +7. Verify release artifacts and signatures before publishing to users. |
| 217 | +8. Log updater failures (without leaking secrets) for diagnostics. |
| 218 | + |
| 219 | +--- |
| 220 | + |
| 221 | +## 9) Cross-platform update behavior |
| 222 | + |
| 223 | +- **Linux**: AppImage updater artifacts (`.AppImage` + `.sig`) |
| 224 | +- **Windows**: MSI/EXE artifacts with configurable install mode |
| 225 | + - `passive` = progress UI, minimal interaction |
| 226 | + - `quiet` = silent mode (works for non-admin/user-level installs) |
| 227 | +- **macOS**: updater package and signature per architecture |
| 228 | + |
| 229 | +For broad macOS coverage, publish both Intel and Apple Silicon builds. |
| 230 | + |
| 231 | +--- |
| 232 | + |
| 233 | +## 10) Optional improvements |
| 234 | + |
| 235 | +### Background checks |
| 236 | + |
| 237 | +Already enabled in `autoUpdater.ts` with interval checks. Adjust interval per your policy. |
| 238 | + |
| 239 | +### Silent updates |
| 240 | + |
| 241 | +- Set `silent: true` in updater startup logic (download + install without auto relaunch) |
| 242 | +- On Windows, set updater `installMode` to `quiet` for less UI (only where appropriate) |
| 243 | + |
| 244 | +### Delta updates |
| 245 | + |
| 246 | +Tauri updater is signature-first and bundle-based by default. Binary delta patching is not enabled out-of-the-box in this setup. |
| 247 | +If you need delta delivery, add a dedicated update backend/CDN strategy and keep signature validation unchanged. |
| 248 | + |
| 249 | +--- |
| 250 | + |
| 251 | +## 11) Open-source project best practices |
| 252 | + |
| 253 | +- Document release steps in CONTRIBUTING/README. |
| 254 | +- Publish checksums/signatures in release notes. |
| 255 | +- Keep reproducible builds (`pnpm-lock.yaml`, pinned toolchain versions). |
| 256 | +- Validate auto-update flow in CI on every tagged release. |
| 257 | +- Keep release notes clear about breaking changes and rollback plans. |
| 258 | + |
| 259 | +--- |
| 260 | + |
| 261 | +## 12) Verification checklist |
| 262 | + |
| 263 | +1. `pnpm tauri build` succeeds locally with signing env variables. |
| 264 | +2. Release workflow publishes bundles + `.sig` + `latest.json`. |
| 265 | +3. Installed older app detects update and downloads it. |
| 266 | +4. Signature verification passes. |
| 267 | +5. App restarts into new version. |
0 commit comments