oasis-server-setup

name	oasis-server-setup
description	Expert guide for integrating Oasis update server with Tauri apps for auto-updates, crash reporting, and feedback collection.

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

Endpoint	Method	Purpose
/{app_slug}/update/{target}-{arch}/{version}	GET	Update manifest
/sdk/{app_slug}/feedback	POST	Submit feedback
/sdk/{app_slug}/crashes	POST	Report crashes
/api/releases/{app_slug}	POST	Register release (CI only)

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

Variable	Description	Example
{{target}}	Operating system	darwin, windows, linux
{{arch}}	CPU architecture	x86_64, aarch64
{{current_version}}	App version	0.1.0

API Keys

Key Type	Format	Purpose
Public Key	pk_{app-slug}_{random}	SDK operations (client-side)
CI Key	ci_{app-slug}_{random}	Release registration (server-side)

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: '[e-mail]',
  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: '[e-mail]',
  username: 'johndoe',
});

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

SDK Configuration Options

Option	Type	Default	Description
apiKey	string	required	Public API key
serverUrl	string	required	Oasis server URL
appVersion	string	required	Current app version
enableAutoCrashReporting	boolean	false	Catch uncaught errors
maxBreadcrumbs	number	50	Breadcrumb history limit
timeout	number	10000	Request timeout (ms)
debug	boolean	false	Enable debug logging
beforeSend	function	-	Filter/modify events
onError	function	-	Error callback

Required Secrets

Secret	Description
OASIS_SERVER_URL	Base URL (e.g., https://oasis.yourdomain.com)
OASIS_CI_KEY	CI key for release registration
NEXT_PUBLIC_OASIS_API_KEY	Public SDK key (exposed to client)
NEXT_PUBLIC_OASIS_SERVER_URL	Public server URL (exposed to client)
TAURI_SIGNING_PRIVATE_KEY	Update signing key
TAURI_SIGNING_PRIVATE_KEY_PASSWORD	Signing key password

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.