Forge - Deployment Guide

This guide covers building, signing, and distributing the Forge desktop application across all supported platforms.

Prerequisites

Development Tools

Platform-Specific Requirements

macOS

• Xcode Command Line Tools
• Apple Developer account (for signing)
• Valid Developer ID certificate

Windows

• Visual Studio Build Tools 2019+
• Windows SDK
• Code signing certificate (optional)

Linux

• build-essential package
• libwebkit2gtk-4.1-dev
• libappindicator3-dev

Building the Application

Development Build

# Install dependencies
pnpm install
 
# Run in development mode
pnpm tauri:dev

Production Build

# Build for current platform
pnpm tauri:build

Build artifacts are output to:

src-tauri/target/release/bundle/
├── macos/          # macOS .app and .dmg
├── msi/            # Windows installer
├── nsis/           # Windows NSIS installer
├── deb/            # Debian package
└── appimage/       # Linux AppImage

Platform-Specific Instructions

macOS

Building

# Build universal binary (Intel + Apple Silicon)
pnpm tauri:build -- --target universal-apple-darwin

Code Signing

For distribution outside the Mac App Store, you need a Developer ID certificate:

1. Export your certificate from Keychain Access
2. Set environment variables:

   export APPLE_SIGNING_IDENTITY="Developer ID Application: Your Name (TEAMID)"

3. Build with signing:

   pnpm tauri:build

Notarization

Apple requires notarization for apps distributed outside the App Store:

# Set notarization credentials
export APPLE_ID="your@email.com"
export APPLE_PASSWORD="app-specific-password"
export APPLE_TEAM_ID="YOURTEAMID"
 
# Build with notarization
pnpm tauri:build

Installation on macOS

When users download and install Forge, macOS may block the app due to Gatekeeper security:

For users installing from DMG or direct download:

# Remove quarantine attribute
xattr -cr /Applications/Forge.app

Or via System Settings:

1. Open System Settings → Privacy & Security
2. Scroll to Security section
3. Click Open Anyway next to the Forge message

Uninstalling on macOS

Run the uninstall script:

/Applications/Forge.app/Contents/Resources/scripts/uninstall-macos.sh

Or manually:

1. Drag Forge.app to Trash
2. Delete ~/Library/Application Support/com.forge.desktop/
3. Delete ~/Library/Caches/com.forge.desktop/
4. Delete ~/Library/Logs/com.forge.desktop/

Note: Settings are preserved by default in settings.json. To completely remove:

rm -rf ~/Library/Application\ Support/com.forge.desktop/

Windows

Building

# Build for Windows
pnpm tauri:build

This produces:

• Forge_x.x.x_x64-setup.exe (NSIS installer)
• Forge_x.x.x_x64_en-US.msi (MSI installer)

Code Signing (Optional)

For signed builds, configure your certificate:

# Set signing certificate
export TAURI_SIGNING_PRIVATE_KEY="path/to/private-key.pem"
export TAURI_SIGNING_PRIVATE_KEY_PASSWORD="your-password"

Installation on Windows

1. Download the installer (.exe or .msi)
2. Run the installer
3. If Windows SmartScreen appears:
   • Click More info
   • Click Run anyway

Windows Defender Warnings

If Windows Defender flags the app:

1. This is common for unsigned apps from unknown publishers
2. Add an exception in Windows Security if needed
3. Consider code signing for production distribution

Uninstalling on Windows

1. Open Settings → Apps → Installed apps
2. Find Forge and click Uninstall

Or use the uninstaller at:

C:\Program Files\Forge\uninstall.exe

Linux

Building

# Build AppImage and deb package
pnpm tauri:build

Produces:

• forge_x.x.x_amd64.AppImage
• forge_x.x.x_amd64.deb

Installation on Linux

AppImage:

# Make executable
chmod +x forge_x.x.x_amd64.AppImage
 
# Run directly
./forge_x.x.x_amd64.AppImage
 
# Or move to applications directory
mv forge_x.x.x_amd64.AppImage ~/.local/bin/forge

Debian/Ubuntu:

# Install deb package
sudo dpkg -i forge_x.x.x_amd64.deb
 
# Fix dependencies if needed
sudo apt-get install -f

Troubleshooting Linux

Missing libraries:

# Install required dependencies
sudo apt-get install libwebkit2gtk-4.1-0 libappindicator3-1

AppImage won’t run:

# Install FUSE
sudo apt-get install libfuse2

Uninstalling on Linux

AppImage:

rm ~/.local/bin/forge
rm -rf ~/.config/com.forge.desktop/

Deb package:

sudo apt remove forge
rm -rf ~/.config/com.forge.desktop/

External Services Setup

Turso Database

1. Create a Turso account at turso.tech 

2. Create a database:

   turso db create forge-production

3. Get the connection URL:

   turso db show forge-production --url
   # Output: libsql://forge-production-yourname.turso.io

4. Create an auth token:

   turso db tokens create forge-production
   # Output: your-auth-token

5. Initialize the schema: The app automatically creates tables on first connection.

Azure AD (Microsoft OAuth)

1. Register an application in Azure Portal:

   • Go to Azure Active Directory → App registrations
   • Click New registration
   • Name: Forge Desktop
   • Supported account types: Accounts in this organizational directory only
   • Redirect URI: forge://oauth/callback (Custom URI scheme)

2. Configure authentication:

   • Go to Authentication
   • Add platform: Mobile and desktop applications
   • Custom redirect URI: forge://oauth/callback
   • Enable Allow public client flows

3. Note the credentials:

   • Application (client) ID - Used in the app
   • Directory (tenant) ID - For single-tenant apps

4. Configure API permissions:

   • User.Read - Sign in and read user profile
   • offline_access - Maintain access (refresh tokens)

LiveKit (Voice/Video)

1. Create a LiveKit Cloud account at livekit.io 

2. Create a new project

3. Get credentials from Settings:

   • URL - Your LiveKit server URL
   • API Key - For authentication
   • API Secret - For token generation

4. Configure in Forge:

   • Go to Settings in the app
   • Enter LiveKit URL, API Key, and API Secret
   • Save settings

Environment Configuration

Production Checklist

Before deploying to production:

• Turso database created and URL/token obtained
• Azure AD app registered with correct redirect URI
• LiveKit project created (if using calling features)
• App code signed (macOS/Windows)
• App notarized (macOS)
• Tested on all target platforms
• Update mechanism configured (if applicable)

Configuration Files

tauri.conf.json - Key production settings:

{
  "productName": "Forge",
  "version": "1.0.0",
  "identifier": "com.forge.desktop",
  "app": {
    "windows": [
      {
        "title": "Forge",
        "width": 1200,
        "height": 800,
        "visible": false
      }
    ],
    "security": {
      "csp": "default-src 'self'; connect-src 'self' ipc: http://ipc.localhost wss: https:; ..."
    }
  }
}

Distribution

Direct Download

Host the installers on your website or file server:

https://your-domain.com/downloads/
├── Forge-1.0.0-universal.dmg     # macOS
├── Forge-1.0.0-x64-setup.exe     # Windows
├── Forge-1.0.0-amd64.AppImage    # Linux
└── Forge-1.0.0-amd64.deb         # Debian/Ubuntu

GitHub Releases

1. Create a new release on GitHub
2. Upload all platform installers
3. Add release notes with:
   • What’s new
   • Platform-specific installation instructions
   • Known issues

Auto-Updates

Tauri supports auto-updates via the updater plugin. Configure in tauri.conf.json:

{
  "plugins": {
    "updater": {
      "endpoints": ["https://your-domain.com/releases/{{target}}/{{arch}}/{{current_version}}"],
      "pubkey": "your-public-key"
    }
  }
}

Troubleshooting Deployment

Build Fails

Rust compilation errors:

# Clean and rebuild
cargo clean
pnpm tauri:build

Node modules issues:

# Clear and reinstall
rm -rf node_modules
pnpm install

Signing Issues

macOS - “Certificate not found”:

# List available certificates
security find-identity -v -p codesigning

macOS - “Notarization failed”:

• Check Apple ID credentials
• Verify team ID is correct
• Ensure app-specific password is valid

Runtime Issues

App crashes on launch:

• Check logs at ~/Library/Logs/com.forge.desktop/ (macOS)
• Check logs at %APPDATA%\com.forge.desktop\logs\ (Windows)
• Run from terminal to see error output

Database connection fails:

• Verify Turso URL format: libsql://your-db.turso.io
• Check auth token hasn’t expired
• Test connection with Turso CLI

Version Management

Semantic Versioning

Follow semver for releases:

• Major (1.0.0 → 2.0.0): Breaking changes
• Minor (1.0.0 → 1.1.0): New features, backward compatible
• Patch (1.0.0 → 1.0.1): Bug fixes

Updating Version

1. Update version in tauri.conf.json
2. Update version in package.json
3. Update version in src-tauri/Cargo.toml
4. Create git tag: git tag v1.0.0
5. Build release artifacts