Oasis Server Setup

Oasis Server Setup — Development Guide

You are an expert on the Oasis update server. Use this knowledge when configuring auto-updates, crash reporting, or feedback collection for Tauri applications.

What It Is

Oasis is a self-hosted release management and analytics server for Tauri applications. It provides update manifests, crash reporting, and feedback collection.

Server repo: https://github.com/porkytheblack/oasis Reusable workflow: porkytheblack/oasis/.github/workflows/tauri-release.yml@main

Architecture at a Glance

┌─────────────────────────────────────────────────────────────────┐
│                      Tauri Desktop App                           │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │
│  │ Auto-Update │  │ Crash SDK   │  │ Feedback SDK            │  │
│  └──────┬──────┘  └──────┬──────┘  └───────────┬─────────────┘  │
└─────────┼────────────────┼─────────────────────┼────────────────┘
          │                │                     │
          ▼                ▼                     ▼
┌─────────────────────────────────────────────────────────────────┐
│                        Oasis Server                              │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │
│  │ /update     │  │ /crashes    │  │ /feedback               │  │
│  │ manifests   │  │ collection  │  │ collection              │  │
│  └──────┬──────┘  └─────────────┘  └─────────────────────────┘  │
└─────────┼───────────────────────────────────────────────────────┘
          │
          ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Cloudflare R2 (CDN)                           │
│         Artifact storage: .dmg, .exe, .AppImage                  │
└─────────────────────────────────────────────────────────────────┘

Quick Start

1. Generate signing keys

npx @tauri-apps/cli signer generate -w ~/.tauri/keys/your-app.key
# Output: Public key + private key file

2. Configure tauri.conf.json

{
  "plugins": {
    "updater": {
      "pubkey": "dW50cnVzdGVkIGNvbW1lbnQ6...",
      "endpoints": [
        "https://oasis.yourdomain.com/your-app/update/{{target}}-{{arch}}/{{current_version}}"
      ],
      "windows": {
        "installMode": "passive"
      }
    }
  }
}

3. Add updater capabilities

// capabilities/default.json
{
  "permissions": [
    "updater:default",
    "updater:allow-check",
    "updater:allow-download-and-install",
    "process:default",
    "process:allow-restart"
  ]
}

4. Install Oasis SDK

pnpm add @oasis/sdk

5. Initialize SDK

// lib/oasis.ts
import { initOasis } from '@oasis/sdk';

export const oasis = initOasis({
  apiKey: process.env.NEXT_PUBLIC_OASIS_API_KEY!,
  serverUrl: process.env.NEXT_PUBLIC_OASIS_SERVER_URL!,
  appVersion: '0.1.0',
  enableAutoCrashReporting: true,
});

6. Check for updates

import { check } from '@tauri-apps/plugin-updater';
import { relaunch } from '@tauri-apps/plugin-process';

async function checkForUpdates() {
  const update = await check();
  if (update?.available) {
    await update.downloadAndInstall();
    await relaunch();
  }
}

API Endpoints

Update Manifest Response

{
  "version": "0.2.0",
  "notes": "Bug fixes and improvements",
  "pub_date": "2024-01-15T10:00:00Z",
  "platforms": {
    "darwin-aarch64": {
      "signature": "dW50cnVzdGVkIGNvbW1lbnQ6...",
      "url": "https://cdn.example.com/app/v0.2.0/App_aarch64.app.tar.gz"
    },
    "darwin-x86_64": {
      "signature": "...",
      "url": "https://cdn.example.com/app/v0.2.0/App_x64.app.tar.gz"
    },
    "windows-x86_64": {
      "signature": "...",
      "url": "https://cdn.example.com/app/v0.2.0/App_x64-setup.nsis.zip"
    },
    "linux-x86_64": {
      "signature": "...",
      "url": "https://cdn.example.com/app/v0.2.0/App_amd64.AppImage.tar.gz"
    }
  }
}

No update available returns HTTP 204 No Content.

Template Variables

API Keys

Example: pk_coco_a1b2c3d4e5f6g7h8

SDK Usage Patterns

Feedback Submission

// Categorized feedback
await oasis.feedback.submit({
  category: 'bug',        // 'bug' | 'feature' | 'general'
  message: 'Save button not working',
  email: 'user@example.com',
  metadata: { screen: 'settings' },
});

// Convenience methods
await oasis.feedback.reportBug('Description');
await oasis.feedback.requestFeature('Description');
await oasis.feedback.sendFeedback('Description');

Crash Reporting

// Manual capture
try {
  riskyOperation();
} catch (error) {
  await oasis.crashes.captureException(error, {
    appState: { screen: 'checkout' },
    severity: 'error',  // 'warning' | 'error' | 'fatal'
  });
}

// Toggle auto-capture
oasis.crashes.enableAutoCrashReporting();
oasis.crashes.disableAutoCrashReporting();

Breadcrumbs

oasis.breadcrumbs.addNavigation('/home', '/settings');
oasis.breadcrumbs.addClick('Save Button');
oasis.breadcrumbs.addHttp('POST', '/api/save', 200);
oasis.breadcrumbs.addCustom('wallet', 'Connected', { address: '0x...' });

User Context

// Set after authentication
oasis.setUser({
  id: 'user-123',
  email: 'user@example.com',
  username: 'johndoe',
});

// Clear on logout
oasis.setUser(null);

SDK Configuration Options

Required Secrets

Common Gotchas

1. Public key in tauri.conf.json must match private key — If you regenerate keys, update both the config and the GitHub secret.
2. Endpoint URL uses double braces — {{target}} not {target}. Single braces are for workflow variables.
3. App slug must be consistent — Use the same slug in workflow config, SDK init, and server registration.
4. NEXT_PUBLIC_ prefix exposes to client — Oasis public keys are safe to expose; CI keys are not.
5. Version string must match semver — Use 0.1.0, not v0.1.0 in code. Tags use v prefix.
6. SDK init before crash reporting — Call initOasis() early in app lifecycle to catch startup crashes.
7. HTTP 204 means no update — Don't treat this as an error; it's the expected response when current.
8. Signature verification happens client-side — Tauri verifies signatures using the embedded pubkey.
9. R2 URLs must be publicly accessible — The CDN URL in manifests must be reachable without auth.
10. beforeSend can drop events — Return null to filter sensitive data from crash reports.