Refactor documentation structure and dependencies for migration to Fumadocs

- Updated `.gitignore` to include new build and generated content directories. - Removed outdated Mintlify configuration files and documentation. - Introduced new `MIGRATION.md` to outline the transition from Mintlify to Fumadocs. - Added `mdx-components.tsx` for MDX component configuration and compatibility. - Updated `package.json` and `next.config.mjs` for new dependencies and Next.js configuration. - Created `source.config.ts` for content source configuration. - Added OpenAPI specification in `openapi.json` for API documentation. - Removed legacy files and adjusted project structure to align with Fumadocs conventions.
2026-09-15 21:00:42 -07:00 · 2026-02-02 23:29:35 -08:00
parent 788a04f265
commit 2e6efa00a2
145 changed files with 355 additions and 11214 deletions
@@ -0,0 +1,270 @@
+---
+title: "Building"
+description: "Build Voicebox for production"
+---
+
+## Overview
+
+Voicebox uses a multi-step build process to create platform-specific installers.
+
+## Quick Build
+
+```bash
+# Build for your current platform (automatically builds server binary first)
+make build
+
+# Or manually
+bun run build
+```
+
+This automatically:
+1. Builds the Python server binary (`bun run build:server`)
+2. Builds the Tauri app (`cd tauri && bun run tauri build`)
+
+## Build Process
+
+The build process consists of two steps, but `bun run build` handles both automatically:
+
+### 1. Server Binary Build (Automatic)
+
+The Python backend is compiled into a standalone executable using PyInstaller. This happens automatically when you run `bun run build`.
+
+**Platform-specific binaries:**
+- macOS (Apple Silicon): `voicebox-server-aarch64-apple-darwin` (includes MLX backend)
+- macOS (Intel): `voicebox-server-x86_64-apple-darwin` (PyTorch backend)
+- Windows: `voicebox-server-x86_64-pc-windows-msvc.exe` (PyTorch backend)
+- Linux: `voicebox-server-x86_64-unknown-linux-gnu` (PyTorch backend)
+
+<Note>
+  The build script automatically detects your platform and includes the appropriate backend (MLX for Apple Silicon, PyTorch for others).
+</Note>
+
+**Manual build (if needed):**
+```bash
+bun run build:server
+```
+
+### 2. Tauri App Build (Automatic)
+
+The Tauri app build is also handled automatically, which:
+1. Builds the React frontend (Vite)
+2. Compiles the Rust backend
+3. Bundles the server binary as a sidecar
+4. Creates platform-specific installers
+
+**Manual build (if needed):**
+```bash
+cd tauri && bun run tauri build
+```
+
+### 3. Output
+
+Installers are created in `tauri/src-tauri/target/release/bundle/`:
+
+**macOS:**
+- `dmg/` - Disk image installer
+- `macos/` - App bundle
+
+**Windows:**
+- `msi/` - MSI installer
+- `nsis/` - NSIS installer
+
+**Linux:**
+- `deb/` - Debian package
+- `appimage/` - AppImage
+
+## Advanced Options
+
+### Building for Specific Platform
+
+```bash
+# Build for macOS (Apple Silicon)
+bun run tauri build -- --target aarch64-apple-darwin
+
+# Build for macOS (Intel)
+bun run tauri build -- --target x86_64-apple-darwin
+
+# Build for Windows
+bun run tauri build -- --target x86_64-pc-windows-msvc
+
+# Build for Linux
+bun run tauri build -- --target x86_64-unknown-linux-gnu
+```
+
+### Using Local Qwen3-TTS
+
+If you're developing Qwen3-TTS locally:
+
+```bash
+export QWEN_TTS_PATH=~/path/to/Qwen3-TTS
+bun run build:server  # Build server binary only
+# or
+bun run build  # Build everything
+```
+
+This makes PyInstaller use your local version instead of the pip package.
+
+### Debug Build
+
+```bash
+cd tauri
+bun run tauri build --debug
+```
+
+Creates a debug build with symbols and logging.
+
+## Build Configuration
+
+### Tauri Config
+
+Edit `tauri/src-tauri/tauri.conf.json`:
+
+```json
+{
+  "bundle": {
+    "identifier": "com.voicebox.app",
+    "icon": [
+      "icons/32x32.png",
+      "icons/128x128.png",
+      "icons/icon.icns",
+      "icons/icon.ico"
+    ]
+  }
+}
+```
+
+### Sidecar Configuration
+
+The Python server is bundled as a sidecar:
+
+```json
+{
+  "tauri": {
+    "bundle": {
+      "externalBin": [
+        "binaries/voicebox-server"
+      ]
+    }
+  }
+}
+```
+
+## Code Signing
+
+### macOS
+
+To sign the app for distribution:
+
+```bash
+# Set signing identity
+export APPLE_SIGNING_IDENTITY="Developer ID Application: Your Name"
+
+# Build with signing
+bun run tauri build
+```
+
+For notarization:
+
+```bash
+# Set credentials
+export APPLE_ID="[email protected]"
+export APPLE_PASSWORD="app-specific-password"
+
+# Build and notarize
+bun run tauri build
+```
+
+### Windows
+
+For Windows code signing:
+
+```bash
+# Set certificate
+export WINDOWS_CERTIFICATE_PATH="/path/to/cert.pfx"
+export WINDOWS_CERTIFICATE_PASSWORD="password"
+
+# Build with signing
+bun run tauri build
+```
+
+## Release Process
+
+The full release process is automated:
+
+```bash
+# 1. Bump version
+bumpversion patch  # or minor/major
+
+# 2. Build all platforms (CI/CD handles this)
+git push --tags
+
+# 3. GitHub Actions creates releases
+```
+
+See [CONTRIBUTING.md](/development/contributing) for the full release workflow.
+
+## Troubleshooting
+
+<AccordionGroup>
+  <Accordion title="Server Binary Build Fails">
+    **Common issues:**
+    - Missing Python dependencies: `pip install -r requirements.txt`
+    - PyInstaller not found: `pip install pyinstaller`
+    - Qwen3-TTS not installed: `pip install git+https://github.com/QwenLM/Qwen3-TTS.git`
+
+    **Solution:**
+    ```bash
+    cd backend
+    source venv/bin/activate
+    pip install -r requirements.txt
+    pip install pyinstaller
+    ```
+  </Accordion>
+
+  <Accordion title="Tauri Build Fails">
+    **Common issues:**
+    - Rust not installed: `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`
+    - Server binary missing: Usually auto-built, but can run manually: `./scripts/build-server.sh`
+    - Node modules outdated: `bun install`
+
+    **Solution:**
+    ```bash
+    # Clean and rebuild
+    cd tauri/src-tauri
+    cargo clean
+    cd ../..
+    bun run build  # Automatically builds server binary first
+    ```
+  </Accordion>
+
+  <Accordion title="App Won't Launch After Build">
+    **Check:**
+    - Server binary has execute permissions
+    - All dependencies are bundled
+    - Check logs in the app's data directory
+
+    **macOS:**
+    ```bash
+    tail -f ~/Library/Application\ Support/com.voicebox.app/logs/server.log
+    ```
+
+    **Windows:**
+    ```bash
+    type %APPDATA%\com.voicebox.app\logs\server.log
+    ```
+  </Accordion>
+</AccordionGroup>
+
+## CI/CD
+
+GitHub Actions automatically builds releases when tags are pushed:
+
+```yaml
+# .github/workflows/release.yml
+on:
+  push:
+    tags:
+      - 'v*'
+```
+
+See the [repository](https://github.com/jamiepine/voicebox) for the full CI/CD configuration.