diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 00000000..a7a9ba5c --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "browser.wiki"] + path = browser.wiki + url = https://github.com/the-ora/browser.wiki.git diff --git a/browser.wiki b/browser.wiki new file mode 160000 index 00000000..51f57389 --- /dev/null +++ b/browser.wiki @@ -0,0 +1 @@ +Subproject commit 51f57389ef42c0d0fb7001224649bcad0830426a diff --git a/wiki/DATA_PERSISTENCE.md b/wiki/DATA_PERSISTENCE.md deleted file mode 100644 index efcd6b5c..00000000 --- a/wiki/DATA_PERSISTENCE.md +++ /dev/null @@ -1,56 +0,0 @@ -# Data and Persistence - -The app uses SwiftData with a single `ModelContainer` storing `TabContainer`, `History`, and `Download` models. The default store is under the app's Application Support directory as `OraData.sqlite`. - -## Database Location - -The SwiftData database is stored at: -``` -~/Library/Application Support/com.orabrowser.ora/OraData.sqlite -``` - -## Data Models - -### TabContainer -- Stores tab groups/containers (spaces) -- Manages tab organization and grouping - -### History -- Browsing history entries -- URL visits and timestamps - -### Download -- Download metadata and status -- File paths and progress tracking - -## Development: Resetting Local Store - -To reset the local store during development, you can delete the database file: - -```bash -rm -f "~/Library/Application Support/com.orabrowser.ora/OraData.sqlite"* -``` - -> **⚠️ Caution: Use with care—this permanently clears tabs/history/download metadata.** - -## Alternative Reset Method - -You can also find and delete the database manually: - -1. Open Finder -2. Press `Cmd+Shift+G` -3. Go to: `~/Library/Application Support/com.orabrowser.ora/` -4. Delete `OraData.sqlite` and related files (`OraData.sqlite-wal`, `OraData.sqlite-shm`) - -## Data Migration - -SwiftData handles schema migrations automatically, but major changes may require manual migration logic in the app code. - -## Backup Considerations - -The database contains: -- All tab states and organization -- Complete browsing history -- Download records - -Consider this when implementing backup/sync features or privacy modes. \ No newline at end of file diff --git a/wiki/HOSTING_SETUP.md b/wiki/HOSTING_SETUP.md deleted file mode 100644 index 3818cc0c..00000000 --- a/wiki/HOSTING_SETUP.md +++ /dev/null @@ -1,286 +0,0 @@ -# Ora Browser Hosting Setup Guide - -This guide explains how to set up hosting for Ora Browser's automatic update system using Sparkle. - -## Overview - -Ora Browser uses [Sparkle](https://sparkle-project.org/) for automatic updates. The system requires: - -1. **Appcast Feed** (`appcast.xml`) - Tells Sparkle about available updates -2. **App Distribution** (`Ora-Browser.dmg`) - The actual app download -3. **Digital Signatures** - Ensures update integrity and security - -## What Needs to Be Hosted - -### 1. Appcast XML File -**File:** `appcast.xml` -**Purpose:** Update feed that Sparkle reads to check for new versions -**Content:** Release information, download URLs, version numbers, and digital signatures - -### 2. App DMG File -**File:** `Ora-Browser.dmg` -**Purpose:** The actual application installer that users download -**Content:** Signed and notarized macOS application bundle - -## Hosting Options - -### Option A: GitHub Pages (Recommended) - -#### Step 1: Create GitHub Pages Branch -```bash -# Create and switch to gh-pages branch -git checkout -b gh-pages - -# Remove all files except what we need for hosting -git rm -rf . -git reset -- docs/ # Keep docs if you want - -# Copy appcast.xml -cp ../appcast.xml . - -# Commit and push -git add appcast.xml -git commit -m "Add appcast.xml for Sparkle updates" -git push origin gh-pages -``` - -#### Step 2: Enable GitHub Pages -1. Go to your GitHub repository -2. Navigate to **Settings** → **Pages** -3. Set **Source** to "Deploy from a branch" -4. Set **Branch** to `gh-pages` and folder to `/ (root)` -5. Click **Save** - -#### Step 3: Get Your URLs -- **Appcast URL:** `https://the-ora.github.io/browser/appcast.xml` -- **DMG URL:** `https://github.com/the-ora/browser/releases/download/v0.0.1/Ora-Browser.dmg` - -### Option B: Your Own Web Server - -#### Requirements -- Public web server with HTTPS -- Ability to upload files -- CORS headers configured (if needed) - -#### Setup Steps -1. Upload `appcast.xml` to your web server -2. Ensure it's accessible via HTTPS -3. Update the enclosure URL in `appcast.xml` to point to your DMG location - -#### Example URLs -- **Appcast URL:** `https://updates.yourdomain.com/appcast.xml` -- **DMG URL:** `https://downloads.yourdomain.com/Ora-Browser.dmg` - -### Option C: GitHub Releases Only - -#### Setup Steps -1. Upload both `appcast.xml` and `Ora-Browser.dmg` to GitHub Releases -2. Use raw GitHub URLs for both files - -#### URLs -- **Appcast URL:** `https://raw.githubusercontent.com/the-ora/browser/main/appcast.xml` -- **DMG URL:** `https://github.com/the-ora/browser/releases/download/v0.0.1/Ora-Browser.dmg` - -## Digital Signature Setup - -### Generate DSA Keys -```bash -# Install Sparkle -brew install --cask sparkle - -# Setup command-line tools -./setup-sparkle-tools.sh - -# Generate keys (run once) -./setup-sparkle.sh - -# This creates in build/: -# - build/dsa_priv.pem (private key - keep secure!) -# - build/dsa_pub.pem (public key - safe to share) -``` - -### Sign Your Release -```bash -# Sign the DMG with your private key -sign_update -f Ora-Browser.dmg -k dsa_priv.pem - -# Copy the signature output -``` - -### Update Appcast with Real Signature -Replace the placeholder in `appcast.xml`: -```xml - -sparkle:dsaSignature="PLACEHOLDER_SIGNATURE_REPLACE_WITH_ACTUAL_SIGNATURE" - - -``` - -## App Configuration - -### Update Info.plist -Add these keys to your `Info.plist` or `project.yml`: - -```xml -SUFeedURL -https://the-ora.github.io/browser/appcast.xml - -SUPublicEDKey -YOUR_PUBLIC_KEY_HERE -``` - -### XcodeGen Configuration -If using XcodeGen, update `project.yml`: -```yaml -settings: - base: - SUFeedURL: https://the-ora.github.io/browser/appcast.xml - SUPublicEDKey: YOUR_PUBLIC_KEY_HERE -``` - -## Release Process - -### Step 1: Build Release -```bash -# Build and package the app -./build-release.sh - -# Or use the comprehensive release script (auto-increments version) -./create-release.sh -``` - -### Step 2: Sign Release -```bash -# Sign with Sparkle -sign_update -f Ora-Browser.dmg -k dsa_priv.pem -``` - -### Step 3: Update Appcast -```bash -# Update version numbers, dates, and signature in appcast.xml -# Update enclosure URL to point to your hosted DMG -``` - -### Step 4: Host Files -1. Upload `appcast.xml` to your chosen hosting location -2. Upload `Ora-Browser.dmg` to GitHub Releases -3. Update your app's `SUFeedURL` if needed - -### Step 5: Test Updates -1. Build and run your app -2. Go to Settings → General → Updates -3. Click "Check for Updates" -4. Verify the update notification appears - -## File Structure - -``` -your-project/ -├── build/ # Build artifacts directory -│ ├── appcast.xml # Update feed (public) -│ ├── Ora-Browser.dmg # App installer -│ ├── dsa_priv.pem # Private key (keep secure!) -│ └── dsa_pub.pem # Public key -└── docs/ # Documentation - ├── HOSTING_SETUP.md # This guide - └── QUICK_START.md # Quick setup guide -``` - -## Security Considerations - -### Private Key Security -- **Never commit `dsa_priv.pem`** to version control -- Store securely (password manager, secure server) -- Use different keys for different environments if needed - -### HTTPS Requirement -- Always host `appcast.xml` over HTTPS -- GitHub Pages automatically provides HTTPS -- Custom servers must have valid SSL certificates - -### Signature Verification -- Sparkle automatically verifies signatures -- Users cannot install updates without valid signatures -- Invalid signatures will be rejected by macOS Gatekeeper - -## Troubleshooting - -### Update Not Detected -1. Check `SUFeedURL` in Info.plist is correct -2. Verify `appcast.xml` is accessible via browser -3. Check signature is valid (not placeholder) -4. Verify version numbers are incrementing - -### Download Fails -1. Check DMG URL in `appcast.xml` is correct -2. Verify DMG is publicly accessible -3. Check file permissions on hosting server -4. Ensure DMG is properly signed and notarized - -### Signature Invalid -1. Verify you're using the correct private key -2. Check the signature was copied correctly -3. Ensure no extra whitespace in signature -4. Test with a fresh signature generation - -## Maintenance - -### Regular Updates -1. Build new release with incremented version -2. Sign with private key -3. Update `appcast.xml` with new version info -4. Upload new DMG to releases -5. Update appcast on hosting server - -### Version Numbering -- Use semantic versioning (e.g., 1.0.0, 1.0.1, 1.1.0) -- Update both `CFBundleShortVersionString` and `CFBundleVersion` -- Ensure version numbers increment for each release - -## Support - -For issues with: -- **Sparkle framework:** https://sparkle-project.org/documentation/ -- **GitHub Pages:** https://docs.github.com/en/pages -- **App signing:** https://developer.apple.com/support/code-signing/ - -## Example Appcast - -```xml - - - - Ora Browser Changelog - Most recent changes with links to updates. - en - - Ora Browser 0.0.1 - - Initial Release -

Ora Browser is a fast, secure, and beautiful browser built for macOS.

-
    -
  • Native macOS UI built with SwiftUI
  • -
  • Fast browsing powered by WebKit
  • -
  • Privacy-first with built-in content blocker
  • -
- ]]> -
- Thu, 04 Sep 2025 14:51:08 +0000 - -
-
-
-``` - ---- - -**Last Updated:** September 4, 2025 -**Ora Browser Version:** 0.0.1 - -/Users/keni/code/ora/browser/docs/HOSTING_SETUP.md \ No newline at end of file diff --git a/wiki/Home.md b/wiki/Home.md deleted file mode 100644 index 35465c47..00000000 --- a/wiki/Home.md +++ /dev/null @@ -1,22 +0,0 @@ -# Welcome to the Ora Wiki - -This wiki contains comprehensive documentation for Ora development, deployment, and maintenance. - -## What is Ora? - -Ora is a fast, secure, and beautiful browser built for macOS. Inspired by Safari and Arc, it delivers a clean, native experience that feels at home on macOS—without unnecessary bloat. - -## What's in This Wiki - -**For Users & Contributors:** -- **Getting Started** - Quick setup guides for development and deployment -- **Development** - Technical documentation for contributors and maintainers -- **Deployment & Updates** - Guides for hosting, releases, and the update system - -## Need Help? - -- **New to contributing?** Start with our [main README](../README.md) and [Contributing Guidelines](../CONTRIBUTING.md) -- **Having issues?** Check the [Troubleshooting](TROUBLESHOOTING.md) guide -- **Questions?** Join our [Discord community](https://discord.gg/9aZWH52Zjm) - ---- diff --git a/wiki/KEYBOARD_SHORTCUTS.md b/wiki/KEYBOARD_SHORTCUTS.md deleted file mode 100644 index 23dc1b42..00000000 --- a/wiki/KEYBOARD_SHORTCUTS.md +++ /dev/null @@ -1,76 +0,0 @@ -# Keyboard Shortcuts - -Ora Browser includes various keyboard shortcuts for efficient navigation and control. - -## Tabs - -| Action | Shortcut | -|--------|----------| -| New Tab | ⌘T | -| Close Tab | ⌘W | -| Restore | ⌘Z | -| Reopen Closed Tab | ⇧⌘T | -| Next Tab | ^⇥ | -| Previous Tab | ^⇧⇥ | -| Move Tab Right | ⌥⌘→ | -| Move Tab Left | ⌥⌘← | -| Pin Tab | ⌘D | -| Switch to Tab 1-9 | ⌘1 - ⌘9 | - -## Navigation - -| Action | Shortcut | -|--------|----------| -| Back | ⌘[ or Mouse Button 4 | -| Forward | ⌘] or Mouse Button 5 | -| Reload | ⌘R | -| Hard Reload | ⇧⌘R | - -## Window - -| Action | Shortcut | -|--------|----------| -| New Window | ⌘N | -| Close Window | ⇧⌘W | -| Fullscreen | ⌃⌘F | - -## Address & Search - -| Action | Shortcut | -|--------|----------| -| Focus Address Bar | ⌘L | -| Copy Address Bar URL | ⇧⌘C | -| Find | ⌘F | -| Find Next | ⌘G | -| Find Previous | ⇧⌘G | - -## Zoom - -| Action | Shortcut | -|--------|----------| -| Zoom In | ⌘+ | -| Zoom Out | ⌘- | -| Reset Zoom | ⌘0 | - -## Developer - -| Action | Shortcut | -|--------|----------| -| Toggle DevTools | ⌥⌘I | -| Reload Ignoring Cache | ⇧⌘R | - -## Privacy - -| Action | Shortcut | -|--------|----------| -| New Private Window | ⇧⌘N | - -## App - -| Action | Shortcut | -|--------|----------| -| Quit | ⌘Q | -| Hide | ⌘H | -| Preferences | ⌘, | -| Toggle Sidebar | ⌘S | -| Show History | ⌘Y | \ No newline at end of file diff --git a/wiki/QUICK_START.md b/wiki/QUICK_START.md deleted file mode 100644 index 7055b6f9..00000000 --- a/wiki/QUICK_START.md +++ /dev/null @@ -1,92 +0,0 @@ -# Ora Browser Quick Start - Hosting Setup - -## 🚀 Quick Setup (5 minutes) - -**Note:** The release script now auto-increments version numbers. Just run `./create-release.sh` without arguments for patch releases. - -### 1. Setup Sparkle Tools -```bash -brew install --cask sparkle -./setup-sparkle-tools.sh -./setup-sparkle.sh -``` - -### 2. Build & Sign Release -```bash -# Auto-increment version (recommended) -./create-release.sh - -# Or specify version manually -./create-release.sh 0.0.1 -``` - -### 3. Host Files - -#### Option A: GitHub Pages (Easiest) -```bash -# Create gh-pages branch -git checkout -b gh-pages -git rm -rf . -cp ../appcast.xml . -git add appcast.xml -git commit -m "Add appcast for updates" -git push origin gh-pages - -# Enable in GitHub: Settings → Pages → Source: gh-pages -``` - -#### Option B: GitHub Releases -- Upload `Ora-Browser.dmg` to GitHub Releases -- Upload `appcast.xml` to any web host - -### 4. Update App Config -Edit `project.yml`: -```yaml -settings: - base: - SUFeedURL: https://the-ora.github.io/browser/appcast.xml - SUPublicEDKey: YOUR_PUBLIC_KEY_HERE -``` - -### 5. Test -```bash -xcodegen -# Build and run app -# Go to Settings → General → Check for Updates -``` - -## 📋 What Gets Hosted Where - -| File | Location | Purpose | -|------|----------|---------| -| `build/appcast.xml` | Public web server | Update feed for Sparkle | -| `build/Ora-Browser.dmg` | GitHub Releases | App installer download | -| `build/dsa_pub.pem` | App bundle | Public key for verification | - -## 🔗 URLs You'll Need - -- **Appcast:** `https://the-ora.github.io/browser/appcast.xml` -- **DMG:** `https://github.com/the-ora/browser/releases/download/v{VERSION}/Ora-Browser.dmg` -- **Public Key:** Copy from `dsa_pub.pem` - -## ✅ Checklist - -- [ ] DSA keys generated (`dsa_priv.pem`, `dsa_pub.pem`) -- [ ] Release built and signed (`Ora-Browser.dmg`) -- [ ] Appcast updated with real signature -- [ ] Appcast hosted at public URL -- [ ] DMG uploaded to GitHub Releases -- [ ] `SUFeedURL` updated in app -- [ ] `SUPublicEDKey` added to app -- [ ] Xcode project regenerated - -## 🆘 Need Help? - -- **Keys not working:** Run `./setup-sparkle.sh` again -- **Signature invalid:** Use `sign_update` command output exactly -- **Update not found:** Check `SUFeedURL` in Info.plist -- **DMG won't download:** Verify GitHub release is public - -See `docs/HOSTING_SETUP.md` for detailed instructions. - -/Users/keni/code/ora/browser/docs/QUICK_START.md \ No newline at end of file diff --git a/wiki/RELEASES_UPDATES.md b/wiki/RELEASES_UPDATES.md deleted file mode 100644 index 45ad5311..00000000 --- a/wiki/RELEASES_UPDATES.md +++ /dev/null @@ -1,40 +0,0 @@ -# Releases and Updates - -Ora uses [Sparkle](https://sparkle-project.org/) for automatic updates to provide users with seamless, secure updates. - -## How It Works - -### Update System Architecture -- **Sparkle Framework**: Handles automatic update checking and installation -- **Cryptographic Signing**: Updates are signed with Ed25519 keys for security -- **Appcast Feed**: XML feed that tells the app about available updates -- **Background Checks**: App periodically checks for updates automatically - -### User Experience -- Updates are checked automatically in the background -- Users see update notifications when new versions are available -- Updates can be triggered manually in Settings > General -- Installation is seamless - users just click "Install and Restart" - -### Security -- All updates are cryptographically signed to prevent tampering -- Users can't install unsigned or malicious updates -- The signing process ensures updates come from trusted sources - -## File Structure - -Updates involve these key files: -- `appcast.xml` - Update feed (hosted publicly) -- `Ora-Browser.dmg` - App installer (hosted on GitHub Releases) -- `ora_public_key.pem` - Public key for verification (in app bundle) -- Private key - Signs updates (kept secure, never committed) - -## For Developers - -See the [Release Process section in CONTRIBUTING.md](../CONTRIBUTING.md#release-process) for technical details on creating releases. - -## Related Documentation - -- [Hosting Setup Guide](HOSTING_SETUP.md) - Complete guide for update hosting -- [Quick Start Guide](QUICK_START.md) - 5-minute setup for releases -- [Security Guide](../SECURITY.md) - Key management and security practices \ No newline at end of file diff --git a/wiki/TROUBLESHOOTING.md b/wiki/TROUBLESHOOTING.md deleted file mode 100644 index a119913c..00000000 --- a/wiki/TROUBLESHOOTING.md +++ /dev/null @@ -1,61 +0,0 @@ -# Troubleshooting - -Common issues and solutions when working with Ora. - -## Development Issues - -### XcodeGen, SwiftFormat, or SwiftLint not found -**Solution**: Run the setup script or install manually via Homebrew: -```bash -./setup.sh -# OR -brew install xcodegen swiftformat swiftlint -``` - -### Code signing issues (CLI builds) -**Solution**: The helper script disables signing for Debug builds. In Xcode, use automatic signing or adjust target settings. - -### Missing `Ora.xcodeproj` -**Solution**: Run XcodeGen to regenerate from `project.yml`: -```bash -xcodegen -# OR -./setup.sh -``` - -### CLI build output is hard to read -**Solution**: Install `xcbeautify` to get prettier build output: -```bash -brew install xcbeautify -# The pipe is already configured in xcbuild-debug.sh -``` - -## Runtime Issues - -### App won't start -- Check minimum macOS version (14.0+) -- Try deleting derived data in Xcode -- Clean build folder (⌘⇧K in Xcode) - -### Database errors -- Try resetting the local database (see [Data Persistence](DATA_PERSISTENCE.md)) -- Check Application Support directory permissions - -## Build Issues - -### Dependencies won't resolve -- Check internet connection -- Try deleting Package.resolved and re-resolving in Xcode -- Verify Sparkle package URL is accessible - -### Git hooks not working -- Re-run setup script: `./setup.sh` -- Check git hooks permissions: `ls -la .githooks/` -- Manually install hooks if needed - -## Getting Help - -If these solutions don't work: -1. Check existing [GitHub Issues](https://github.com/the-ora/browser/issues) -2. Search the [Discord community](https://discord.gg/9aZWH52Zjm) -3. Open a new issue with detailed information \ No newline at end of file diff --git a/wiki/_sidebar.md b/wiki/_sidebar.md deleted file mode 100644 index a8c37c1c..00000000 --- a/wiki/_sidebar.md +++ /dev/null @@ -1,15 +0,0 @@ -# Ora Wiki - -## 🚀 Getting Started -- [Quick Start](QUICK_START.md) - -## 📦 Deployment & Updates -- [Hosting Setup](HOSTING_SETUP.md) -- [Releases & Updates](RELEASES_UPDATES.md) - -## 📊 Data & Storage -- [Data & Persistence](DATA_PERSISTENCE.md) - -## 🆘 Help & Support -- [Troubleshooting](TROUBLESHOOTING.md) -- [Keyboard Shortcuts](KEYBOARD_SHORTCUTS.md) \ No newline at end of file