oasis-setup

name	oasis-setup
description	Expert guide for integrating Oasis into Tauri applications. Use when working with oasis-sdk, auto-updates, crash reporting, user feedback, release workflows, or any Oasis-powered Tauri project.

Oasis — Development Guide

You are an expert on the Oasis platform. Use this knowledge when integrating, debugging, or reviewing Oasis code in Tauri applications.

What Oasis Is

Oasis is a self-hosted platform for managing Tauri application releases, collecting user feedback, and tracking crashes. Developers integrate the SDK into their Tauri app, configure the release workflow, and Oasis handles update distribution, crash collection, and feedback management.

Repository: https://github.com/porkytheblack/oasis License: MIT

Component Overview

Component	Purpose	Location
oasis-sdk	Client SDK: feedback, crashes, breadcrumbs	npm install oasis-sdk
Server	Hono backend API for releases, crashes, feedback	server/
Dashboard	Next.js admin UI for managing apps	dashboard/
Release Workflow	Reusable GitHub Actions for Tauri builds	.github/workflows/tauri-release.yml

Architecture at a Glance

Tauri App + SDK → Oasis Server → Dashboard
       ↓                ↓
  Crash reports    Release management
  User feedback    Update distribution
  Breadcrumbs      Analytics

API Key Types

Type	Prefix	Use
Public	pk_*	SDK initialization (client-side)
CI	uk_live_*	GitHub Actions release registration
Admin	uk_live_* (admin scope)	Full dashboard access

Quick Start

1. Install SDK

npm install oasis-sdk

2. Initialize

import { initOasis } from 'oasis-sdk';

const oasis = initOasis({
  apiKey: 'pk_my-app_xxxxxxxx',           // From Oasis dashboard
  serverUrl: 'https://updates.myapp.com', // Your Oasis server
  appVersion: '1.0.0',                    // Current app version
  enableAutoCrashReporting: true,         // Auto-capture uncaught errors
});

3. Collect Feedback

await oasis.feedback.submit({
  category: 'bug',  // 'bug' | 'feature' | 'general'
  message: 'Description of the issue',
  email: '[e-mail]',
});

// Convenience methods
await oasis.feedback.reportBug('Bug description');
await oasis.feedback.requestFeature('Feature request');

4. Manual Crash Reporting

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

SDK API Reference

OasisConfig

interface OasisConfig {
  apiKey: string;                         // Required: Public API key (pk_*)
  serverUrl: string;                      // Required: Oasis server URL
  appVersion: string;                     // Required: Current app version (semver)
  enableAutoCrashReporting?: boolean;     // Auto-capture errors (default: false)
  maxBreadcrumbs?: number;                // Max breadcrumbs (default: 50)
  timeout?: number;                       // Request timeout ms (default: 10000)
  debug?: boolean;                        // Enable debug logging (default: false)
  beforeSend?: (event) => event | null;   // Filter/modify events
  onError?: (error, event) => void;       // Called on send failure
}

Feedback API

await oasis.feedback.submit({ category, message, email?, metadata? });
await oasis.feedback.reportBug(message, email?);
await oasis.feedback.requestFeature(message, email?);
await oasis.feedback.sendFeedback(message, email?);

Crash Reporting API

await oasis.crashes.captureException(error, { severity?, appState?, tags? });
await oasis.crashes.report({ error, severity?, appState?, tags? });
oasis.crashes.enableAutoCrashReporting();
oasis.crashes.disableAutoCrashReporting();

Breadcrumbs API

oasis.breadcrumbs.add({ type, message, data? });
oasis.breadcrumbs.addNavigation(from, to);
oasis.breadcrumbs.addClick(target, data?);
oasis.breadcrumbs.addHttp(method, url, statusCode?);
oasis.breadcrumbs.addConsole(level, message);
oasis.breadcrumbs.addUserAction(action, data?);
oasis.breadcrumbs.getAll();
oasis.breadcrumbs.clear();

Auto-collected: Navigation, clicks, console messages, fetch requests.

User Tracking

oasis.setUser({ id, email?, username?, ...custom });
oasis.setUser(null);  // Clear user

Utilities

await oasis.flush();       // Flush event queue
oasis.getConfig();         // Get current config
oasis.destroy();           // Clean up resources

Tauri Configuration

Enable Auto-Updates

In src-tauri/tauri.conf.json:

{
  "tauri": {
    "updater": {
      "active": true,
      "endpoints": [
        "https://YOUR_OASIS_SERVER/your-app-slug/update/{{target}}/{{current_version}}"
      ],
      "dialog": true,
      "pubkey": "YOUR_PUBLIC_KEY_HERE"
    }
  }
}

Generate Signing Keys

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

• Private key → GitHub secret TAURI_SIGNING_PRIVATE_KEY
• Public key → tauri.conf.json under updater.pubkey

GitHub Actions Workflow

Create .github/workflows/release.yml:

name: Release

on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    uses: porkytheblack/oasis/.github/workflows/tauri-release.yml@main
    with:
      app_slug: your-app-slug
      artifact_prefix: YourApp
      app_name: Your App Name
      app_dir: .
      distribute_to: r2,oasis,github
      auto_publish: true
      r2_public_url: https://cdn.example.com
    secrets:
      APPLE_CERTIFICATE: ${{ secrets.APPLE_CERTIFICATE }}
      APPLE_CERTIFICATE_PASSWORD: ${{ secrets.APPLE_CERTIFICATE_PASSWORD }}
      APPLE_SIGNING_IDENTITY: ${{ secrets.APPLE_SIGNING_IDENTITY }}
      APPLE_ID: ${{ secrets.APPLE_ID }}
      APPLE_PASSWORD: ${{ secrets.APPLE_PASSWORD }}
      APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
      TAURI_SIGNING_PRIVATE_KEY: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY }}
      TAURI_SIGNING_PRIVATE_KEY_PASSWORD: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY_PASSWORD }}
      CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
      CLOUDFLARE_R2_ACCESS_KEY_ID: ${{ secrets.CLOUDFLARE_R2_ACCESS_KEY_ID }}
      CLOUDFLARE_R2_SECRET_ACCESS_KEY: ${{ secrets.CLOUDFLARE_R2_SECRET_ACCESS_KEY }}
      R2_BUCKET_NAME: ${{ secrets.R2_BUCKET_NAME }}
      OASIS_SERVER_URL: ${{ secrets.OASIS_SERVER_URL }}
      OASIS_CI_KEY: ${{ secrets.OASIS_CI_KEY }}
      NEXT_PUBLIC_OASIS_API_KEY: ${{ secrets.NEXT_PUBLIC_OASIS_API_KEY }}
      NEXT_PUBLIC_OASIS_SERVER_URL: ${{ secrets.NEXT_PUBLIC_OASIS_SERVER_URL }}

Required Secrets

Secret	Description
APPLE_CERTIFICATE	Base64-encoded .p12 certificate
APPLE_CERTIFICATE_PASSWORD	Certificate password
APPLE_SIGNING_IDENTITY	e.g., "Developer ID Application: Name (TEAMID)"
APPLE_ID	Apple ID email
APPLE_PASSWORD	App-specific password
APPLE_TEAM_ID	Apple Developer Team ID
TAURI_SIGNING_PRIVATE_KEY	From tauri signer generate
CLOUDFLARE_ACCOUNT_ID	Cloudflare account ID
CLOUDFLARE_R2_ACCESS_KEY_ID	R2 API access key
CLOUDFLARE_R2_SECRET_ACCESS_KEY	R2 API secret key
R2_BUCKET_NAME	R2 bucket name
OASIS_SERVER_URL	Your Oasis server URL
OASIS_CI_KEY	CI API key (uk_live_*)

Supported Platforms

Platform	Target	Bundle Types
macOS (Apple Silicon)	darwin-aarch64	.dmg, .app.tar.gz
macOS (Intel)	darwin-x86_64	.dmg, .app.tar.gz
Linux	linux-x86_64	.AppImage, .deb, .AppImage.tar.gz
Windows	windows-x86_64	.exe (NSIS), .nsis.zip

Supporting Files

For extended documentation including workflow details and integration checklist, see references/integration-guide.md.

Common Gotchas

1. API key prefix matters: Public keys start with pk_, CI keys with uk_live_. Using the wrong type will fail silently.
2. Update endpoint URL format: Must include {{target}} and {{current_version}} placeholders exactly as shown.
3. Signing key mismatch: The public key in tauri.conf.json must match the private key used in CI. Regenerating keys without updating both will break updates.
4. Events not sending: Enable debug: true in SDK config to see network errors. Common causes: wrong serverUrl, CORS issues, invalid apiKey.
5. Crashes not captured: Auto-capture only works if enableAutoCrashReporting: true is set during initOasis(), not after.
6. macOS signing failures: APPLE_SIGNING_IDENTITY must match the certificate name exactly, including the team ID in parentheses.
7. Release not appearing in app: Check auto_publish: true in workflow. Unpublished releases exist in dashboard but aren't served to clients.
8. dry_run for testing: Use dry_run: true workflow input to test builds without uploading artifacts or registering releases.
9. R2 public URL: The r2_public_url must be the public-facing CDN URL, not the R2 API endpoint.
10. Version format: appVersion must be valid semver (e.g., "1.0.0", not "v1.0.0"). The workflow extracts version from git tags automatically.