Auto-Update System Guide

This guide covers the full setup and operation of the NuPOS auto-update mechanism for desktop and Android clients.

Architecture Overview

┌──────────────────────────────────────────────────────────────┐
│                     POS Terminal (Windows)                    │
│                                                              │
│  ┌─────────────┐    check()     ┌──────────────────────┐     │
│  │ React UI    │ ◄────────────► │ tauri-plugin-updater │     │
│  │ (UpdateGate │                │ (Rust side)          │     │
│  │  + Screen)  │                └──────────┬───────────┘     │
│  └─────────────┘                           │                 │
│                                            │ HTTPS GET       │
└────────────────────────────────────────────┼─────────────────┘
                                             │
                                             ▼
                              ┌──────────────────────────┐
                              │  Cloudflare Worker        │
                              │  pos-update-proxy         │
                              │                          │
                              │  GET /update/check       │
                              │  (no auth required)      │
                              └────────────┬─────────────┘
                                           │
                                           │ GitHub API
                                           │ (with PAT)
                                           ▼
                              ┌──────────────────────────┐
                              │  GitHub API               │
                              │                          │
                              │  /repos/.../releases     │
                              │  /repos/.../assets/{id}  │
                              │                          │
                              │  Returns pre-signed      │
                              │  CDN download URLs       │
                              └──────────────────────────┘
                                           ▲
                                           │ upload
                              ┌──────────────────────────┐
                              │  GitHub Actions           │
                              │  (release.yml)            │
                              │                          │
                              │  triggered by tag push    │
                              │  e.g. v1.0.0             │
                              └──────────────────────────┘

Desktop (Windows): Tauri updater plugin calls the Cloudflare Worker → Worker fetches release metadata from GitHub API with server-side PAT → returns pre-signed download URLs → Tauri downloads installer directly from CDN (no auth needed) → verifies Ed25519 signature → installs → relaunches. Fully automatic, no manual steps for operators. Why a proxy? The repo is private. GitHub Releases URLs return 404 without auth, and Tauri’s HTTP client (reqwest) strips Authorization headers on cross-origin redirects to GitHub’s CDN. The Worker solves this by resolving pre-signed CDN URLs server-side — no secrets in the app binary. Android (sideloaded): Frontend JS calls the Odoo backend endpoint, then opens the APK URL in the system browser for download and install. Web: No update mechanism — deploy new static files to your server.

1. Initial Setup (One-Time)

1.1 Generate a Signing Keypair

The signing key ensures update integrity — Tauri will not apply unsigned updates. A keypair is already generated (public key is in tauri.conf.json). If you need a new one:

npx @tauri-apps/cli signer generate -w ~/.tauri/nupos.key

This produces:

~/.tauri/nupos.key — private key (NEVER commit this)
~/.tauri/nupos.key.pub — public key (goes into tauri.conf.json)

The CLI prompts for a password. Store both the key file and the password securely — if lost, existing installations cannot receive updates.

1.2 Configure GitHub Repository Secrets

Set secrets via the CLI (not the web UI, which can corrupt base64 values):

gh secret set TAURI_SIGNING_PRIVATE_KEY < ~/.tauri/nupos.key
gh secret set TAURI_SIGNING_PRIVATE_KEY_PASSWORD

Secret Name	Value
`TAURI_SIGNING_PRIVATE_KEY`	Full contents of `~/.tauri/nupos.key`
`TAURI_SIGNING_PRIVATE_KEY_PASSWORD`	The password used during key generation

GITHUB_TOKEN is provided automatically by GitHub Actions — do not add it manually.

1.3 Configure the Cloudflare Worker

The Worker is already deployed at https://pos-update-proxy.jespinal.workers.dev. If you need to redeploy or reconfigure:

cd workers/update-proxy
npm install          # Install wrangler + types
wrangler login       # Authenticate with Cloudflare (opens browser)
wrangler deploy      # Deploy the Worker
wrangler secret put GITHUB_PAT  # Set the GitHub PAT (paste when prompted)

The GITHUB_PAT must be a fine-grained GitHub PAT with Contents: read permission on the repo.

1.4 Verify tauri.conf.json Configuration

The following should already be set in nu_pos_react/src-tauri/tauri.conf.json:

{
  "plugins": {
    "updater": {
      "endpoints": [
        "https://pos-update-proxy.jespinal.workers.dev/update/check"
      ],
      "pubkey": "<your public key>"   // Must match the private key in GitHub secrets
    }
  },
  "bundle": {
    "createUpdaterArtifacts": true,    // Generates .sig files
    "targets": ["nsis", ...]           // NSIS required for Windows auto-update
  }
}

If you regenerated the keypair, update plugins.updater.pubkey with the contents of the new .pub file. A mismatch causes “The signature was created with a different key than the one provided” errors.

2. Release Process

Step-by-Step

2a. Bump the Version

Edit version.json at the repo root:

{ "version": "1.1.0" }

Or use the bump skill:

# From nu_pos_react/
npm run version:sync   # Stamps package.json, tauri.conf.json, Cargo.toml

The sync script runs automatically during desktop:dev and desktop:build, but run it manually if you want to verify or commit the stamped files.

2b. Commit and Tag

git add version.json nu_pos_react/package.json nu_pos_react/src-tauri/tauri.conf.json nu_pos_react/src-tauri/Cargo.toml
git commit -m "release: v1.1.0"
git tag v1.1.0
git push origin main --tags

2c. GitHub Actions Runs Automatically

The release.yml workflow triggers on the v* tag push. It:

Validates (Ubuntu): lint, typecheck, unit tests
Builds (Windows): Compiles the Tauri app with NSIS installer, signs it, creates a draft GitHub Release with:
- NuPOS-Restaurant_1.1.0_x64-setup.exe — NSIS installer
- NuPOS-Restaurant_1.1.0_x64-setup.exe.sig — Ed25519 signature
- NuPOS-Restaurant_1.1.0_x64_en-US.msi — MSI installer
- NuPOS-Restaurant_1.1.0_x64_en-US.msi.sig — MSI signature

2d. Review and Publish the Release

Go to GitHub → Releases — you’ll see a new Draft release
Edit the release notes if needed (add changelog, known issues, etc.)
Click Publish release

2e. Clients Detect the Update

The Worker caches responses for 5 minutes. After publishing, wait up to 5 minutes for the Worker cache to expire, then existing POS installations will detect the update on next launch.

Manual Trigger (Testing)

You can also trigger the build manually via GitHub Actions → Release POS → Run workflow, without pushing a tag. This is useful for testing the CI pipeline.

3. How the Update Flow Works

On App Launch

App starts
    │
    ▼
UpdateGate checks platform
    │
    ├── Web ──────────► Pass through (no update check)
    │
    ├── Desktop ──────► Plugin check() calls Worker /update/check
    │                      │
    │                      ├── Same version ──► Proceed to app
    │                      │
    │                      ├── check() fails ──► Fallback to Odoo endpoint
    │                      │                       (only if POS_API_BASE_URL set)
    │                      │
    │                      └── Update found
    │                            │
    │                            ▼
    │                         Full-screen overlay
    │                         "Version X.Y.Z available"
    │                            │
    │                            ├── "Install Update" ──► Download → Verify sig → Install → Relaunch
    │                            │     (overlay stays, non-dismissable during download)
    │                            │
    │                            └── "Later" ──► Proceed to app
    │                                  (overlay returns on next launch)
    │
    └── Android ──────► JS calls Odoo endpoint
                           │
                           ├── 204 ──► Proceed to app
                           │
                           └── 200 ──► "Download Update" opens APK URL in browser

Download Flow (Private Repo)

The Worker solves the private repo download problem:

Worker calls GitHub API /releases/assets/{id} with PAT and Accept: application/octet-stream, using redirect: "manual"
GitHub returns 302 with a pre-signed CDN URL in the Location header
Worker returns this pre-signed URL in the Tauri JSON response
Tauri downloads directly from the pre-signed CDN URL — no auth headers needed

Pre-signed URLs expire in ~10 minutes. Since the update check and download happen in sequence, this is sufficient.

Fallback Behavior

If the Worker endpoint is unreachable (no internet, DNS failure, etc.):

If POS_API_BASE_URL is set, falls back to the Odoo update endpoint
If that also fails, shows a brief error with “Continue Anyway”
The POS never gets stuck — operators can always reach the order screen
The min_client_version Odoo system parameter serves as a hard backstop at bootstrap time

4. CI Cost Budget

Per-Release (Windows Only)

Runner	Real Minutes	Multiplier	Billed Minutes
Ubuntu (validate)	~2 min	1x	~2
Windows (build)	~8 min (cached)	2x	~16
Total			~18

First build may take ~15-20 real minutes (no Rust cache). Subsequent builds benefit from the cache-warm.yml workflow that runs cargo check on main pushes to warm the Rust cache. Budget: 2,000 free minutes / 18 per release ≈ ~110 releases/month — effectively unlimited. The release workflow only triggers on tag pushes (v*), so normal development pushes consume zero release CI minutes.

Build performance optimizations

Rust cache warming: cache-warm.yml runs on main pushes (when Tauri source changes), saving the Rust compilation cache so tag-triggered release builds can restore from it
LLD linker: RUSTFLAGS: "-C link-arg=-fuse-ld=lld" for faster linking
cache-on-failure: true: Saves partial build cache even on failures

5. Signing Key Management

Key	Location	Purpose
Private key	`~/.tauri/nupos.key` + GitHub secret	Signs release artifacts during CI build. Keep secret.
Public key	`tauri.conf.json` → `plugins.updater.pubkey`	Embedded in the app binary. Verifies signatures at update time.

Key Rotation

If the private key is compromised:

Generate a new keypair: npx @tauri-apps/cli signer generate -w ~/.tauri/nupos-v2.key
Update tauri.conf.json with the new public key
Update the GitHub secrets via CLI: gh secret set TAURI_SIGNING_PRIVATE_KEY < ~/.tauri/nupos-v2.key
Build and ship a release signed with the old key (so existing clients can verify it)
That release now contains the new public key in its binary
All subsequent releases are signed with the new private key

6. Android Update Strategy

The tauri-plugin-updater does not support Android. Android updates use a separate path:

The Odoo backend serves update check responses at GET /pos-api/v1/updates/check/android/aarch64/{version}
On launch, the frontend calls this endpoint and compares versions
If an update is available, the same blocking overlay appears
“Download Update” opens the APK URL in the system browser
Requires “Install from unknown sources” enabled on the tablet (one-time setup)

Adding Android APK to Releases

To also distribute Android APKs via GitHub Releases:

Build the APK: cd nu_pos_react && npm run tauri android build
Attach the APK to the same GitHub Release as the Windows artifacts
Update the Odoo release record to point to the GitHub Release APK URL

7. Testing the Updater Locally

Without GitHub Releases

You can test the update flow with a local HTTP server:

Build the app with version 0.0.1 (set in version.json)
Create a latest.json for version 0.0.2:

{
  "version": "0.0.2",
  "notes": "Test update",
  "pub_date": "2026-03-31T00:00:00Z",
  "platforms": {
    "windows-x86_64": {
      "signature": "<contents of .sig file>",
      "url": "http://localhost:8080/NuPOS-Restaurant_0.0.2_x64-setup.exe"
    }
  }
}

Serve the directory: npx serve -l 8080 ./test-update-server
Temporarily change the endpoint in tauri.conf.json to http://localhost:8080/latest.json
Run the 0.0.1 build — it should detect and offer the 0.0.2 update

Verifying the Worker

After publishing a release, verify the Worker endpoint:

curl -s https://pos-update-proxy.jespinal.workers.dev/update/check | python3 -m json.tool

Expected output:

{
  "version": "1.1.0",
  "notes": "...",
  "pub_date": "2026-03-31T...",
  "platforms": {
    "windows-x86_64": {
      "url": "https://release-assets.githubusercontent.com/...",
      "signature": "dW50cnVzdGVkIGNvbW1lbnQ6..."
    },
    "windows-x86_64-nsis": { "..." },
    "windows-x86_64-msi": { "..." }
  }
}

The url fields should be pre-signed CDN URLs (not api.github.com URLs).

Health check

curl -s https://pos-update-proxy.jespinal.workers.dev/health
# {"ok":true}

8. Troubleshooting

Client doesn’t check for updates

Web: Expected — web has no update mechanism.
Desktop: Verify the app is a Tauri build (check window title shows version). The plugin reads endpoints from tauri.conf.json which is baked into the binary at build time.
Android: Verify POS_API_BASE_URL is set and the Odoo endpoint is reachable from the device.

Worker returns 204 (no releases)

Check the GitHub Release is published (not draft)
Check the GITHUB_PAT secret is set: cd workers/update-proxy && wrangler secret list
Check the PAT has Contents: read permission on the repo

Worker returns 502

The GitHub API returned an error. Check the PAT hasn’t expired.
Verify with: curl -s -H "Authorization: token <PAT>" https://api.github.com/repos/josespinal/rost_pos_restaurant/releases/latest

Update found but download fails

Pre-signed URLs expire in ~10 minutes. If the user waited too long, retry the update check.
Check the release has both .exe and .sig files uploaded

Signature verification fails

The public key in tauri.conf.json must match the private key in the TAURI_SIGNING_PRIVATE_KEY GitHub secret
If you regenerated keys, both must be updated together
Set secrets via CLI (gh secret set), not the web UI (which can corrupt base64)
Don’t manually re-upload a modified binary without re-signing

CI build fails

Missing secrets: Verify TAURI_SIGNING_PRIVATE_KEY and TAURI_SIGNING_PRIVATE_KEY_PASSWORD are set in GitHub repo settings
Rust compilation errors: Check Cargo.toml dependencies match the Tauri version
Version mismatch: Ensure version.json, tauri.conf.json, Cargo.toml, and package.json all have the same version (run npm run version:sync)

“Later” defers but update appears every launch

This is by design. The operator can defer with “Later”, but the update check runs on every app launch. Once an update is available, the overlay will appear each time until the update is installed. During download/install, the overlay cannot be dismissed.

Android download doesn’t trigger install

Verify REQUEST_INSTALL_PACKAGES permission is in AndroidManifest.xml
The user may need to enable “Install from unknown sources” in Android settings
Some Android versions require: Settings → Apps → Browser → Install unknown apps

9. Rollback

Tauri does not include a built-in rollback mechanism. If a bad update is deployed:

Fastest: Publish a new release with the fix (bump patch version)
Manual: Reinstall the previous version from the GitHub Releases page
Prevention: Use releaseDraft: true in CI (current setting) to review builds before publishing

For critical POS deployments, keep the last 2-3 release installers downloaded locally as a safety net.

10. Worker Proxy Reference

Source

workers/update-proxy/ in the repo root.

Configuration

wrangler.toml:

name = "pos-update-proxy"
main = "src/index.ts"
compatibility_date = "2024-01-01"

# GITHUB_PAT must be set via: wrangler secret put GITHUB_PAT

[vars]
GITHUB_REPO = "josespinal/rost_pos_restaurant"

Platform key mapping

The Worker maps release asset filenames to Tauri platform keys:

Asset filename pattern	Platform key
`*_x64-setup.exe`	`windows-x86_64`, `windows-x86_64-nsis`
`*_x64_en-US.msi`	`windows-x86_64-msi`
`*_aarch64.AppImage`	`linux-aarch64`
`*_amd64.AppImage`	`linux-x86_64`
`*.dmg` (aarch64)	`darwin-aarch64`
`*.dmg` (x86_64)	`darwin-x86_64`

Assets without a matching .sig file are excluded from the response (Tauri requires signatures).

Deploying Worker changes

cd workers/update-proxy
npm install     # If dependencies changed
wrangler deploy

11. File Reference

File	Purpose
`version.json`	Single source of truth for app version
`scripts/sync-version.mjs`	Stamps version into package.json, tauri.conf.json, Cargo.toml
`workers/update-proxy/src/index.ts`	Cloudflare Worker: proxies GitHub API, returns Tauri-format JSON
`workers/update-proxy/wrangler.toml`	Worker config (name, repo var, GITHUB_PAT secret)
`.github/workflows/release.yml`	CI/CD: build, sign, create GitHub Release
`.github/workflows/cache-warm.yml`	CI: warm Rust build cache on main pushes
`nu_pos_react/src-tauri/tauri.conf.json`	Updater endpoint URL (Worker), public key, bundle config
`nu_pos_react/src-tauri/Cargo.toml`	Rust deps: updater, process plugins
`nu_pos_react/src-tauri/src/lib.rs`	Plugin registration, fallback `check_for_update` command
`nu_pos_react/src-tauri/capabilities/default.json`	Tauri permissions for updater/process
`nu_pos_react/src/lib/updater.ts`	Platform detection, version comparison, update check logic
`nu_pos_react/src/features/updates/UpdateGate.tsx`	App-level gate (wraps all providers)
`nu_pos_react/src/features/updates/UpdateScreen.tsx`	Full-screen update UI (i18n, progress bar)
`nu_pos_react/src/i18n/locales/{en,es}.json`	`updateScreen` namespace translations
`~/.tauri/nupos.key`	Signing private key (local only, also in GitHub secrets)

​Auto-Update System Guide

​Architecture Overview

​1. Initial Setup (One-Time)

​1.1 Generate a Signing Keypair

​1.2 Configure GitHub Repository Secrets

​1.3 Configure the Cloudflare Worker

​1.4 Verify tauri.conf.json Configuration

​2. Release Process

​Step-by-Step

​2a. Bump the Version

​2b. Commit and Tag

​2c. GitHub Actions Runs Automatically

​2d. Review and Publish the Release

​2e. Clients Detect the Update

​Manual Trigger (Testing)

​3. How the Update Flow Works

​On App Launch

​Download Flow (Private Repo)

​Fallback Behavior

​4. CI Cost Budget

​Per-Release (Windows Only)

​Build performance optimizations

​5. Signing Key Management

​Key Rotation

​6. Android Update Strategy

​Adding Android APK to Releases

​7. Testing the Updater Locally

​Without GitHub Releases

​Verifying the Worker

​Health check

​8. Troubleshooting

​Client doesn’t check for updates

​Worker returns 204 (no releases)

​Worker returns 502

​Update found but download fails

​Signature verification fails

​CI build fails

​“Later” defers but update appears every launch

​Android download doesn’t trigger install

​9. Rollback

​10. Worker Proxy Reference

​Source

​Configuration

​Platform key mapping

​Deploying Worker changes

​11. File Reference

​12. Release Checklist