Deployment & Build Processes
Relevant source files
The following files were used as context for generating this wiki page:
The Coral project employs a multi-faceted deployment strategy encompassing desktop applications for macOS, Windows, and Linux, as well as containerized web services and shared servers. The build process integrates Rust-based runtimes with Electron-hosted frontends (Reef), utilizing automated signing, notarization, and End-to-End (E2E) validation gates to ensure release integrity.
Sources: apps/desktop/README.md:1-10, apps/reef/e2e/README.md:5-15
Desktop Application Build Process
The desktop build process manages the compilation of the coral runtime and the packaging of the Reef frontend into a unified Electron application. Packaging is handled by electron-builder and orchestrated by xtask for release-specific requirements.
Staging and Packaging
The build follows a two-stage approach:
- Staging (
npm run stage): This command populates theresources/directory with the release runtime binary and the bundled Reef client/server files. - Packaging (
npm run package): This command builds the main process and executeselectron-builder. It produces an Apple silicon DMG/Zip for macOS, an x64 NSIS installer for Windows, and an AppImage for Linux.
Sources: apps/desktop/README.md:91-106, apps/desktop/electron-builder.config.ts:60-70
The diagram shows the flow from compiled assets through the staging resources into the final platform-specific packages.
Release Security and Signing
Release builds (CORAL_DESKTOP_RELEASE=1) enforce strict code signing and notarization requirements:
- macOS: Uses Hardened Runtime and JIT entitlements. All binaries are signed and notarized via App Store Connect API keys.
- Windows: Signatures are applied using Azure Trusted Signing for the app, runtime, and installer.
- Linux: AppImages remain unsigned as there is no standard platform signature.
Sources: apps/desktop/README.md:129-145, apps/desktop/electron-builder.config.ts:37-55, xtask/src/desktop_release.rs:114-140
Continuous Integration and Validation
Validation occurs through a series of "required gates" that must be passed before merging or releasing changes. These gates cover different scopes of the project.
| Change Type | Required Gate | Description |
|---|---|---|
| Rust | make rust-checks | Standard Rust linting and unit tests. |
| Reef | npm run build --prefix apps/reef | Verifies the web frontend build. |
| Desktop | npm run test:e2e --suite desktop | Drives the packaged app in Electron. |
| Postgres | make postgres-tests | Validates database-backed behavior. |
Sources: AGENTS.md:183-195, apps/reef/e2e/README.md:21-30
Reel E2E Framework
Reel is a standalone tool for recording browser-test scenarios. It builds a Linux container containing Coral, Reef, Chromium, and ffmpeg to provide a consistent test environment. It proves cross-process journeys and local/remote parity.
Sources: apps/reef/e2e/README.md:5-20
The sequence diagram illustrates the lifecycle of an E2E test run within the Reel containerized environment.
Deployment Configurations
Update Channels
Coral Desktop uses a v1 update feed hosted on a dedicated GitHub repository (withcoral/coral-releases). This is distinct from the 0.x feed to prevent incompatible automatic upgrades. The app checks for updates at launch and every four hours.
Sources: apps/desktop/README.md:120-128, apps/desktop/electron-builder.config.ts:13-20
Web Frontend Deployment (Reef)
Reef can be deployed as a hosted service. It requires explicit authentication configuration in production to avoid unauthenticated exposure.
| Variable | Description |
|---|---|
CORAL_WEB_AUTH_MODE | Set to required for hosted production. |
CORAL_WEB_PUBLIC_URL | The canonical HTTPS origin of the Reef UI. |
CORAL_WEB_AUTH_ISSUER | The URL of the Coral authorization server. |
CORAL_ENDPOINT | The gRPC data-plane address of the Coral runtime. |
Sources: apps/reef/README.md:19-45
Development Environment Setup
Developers use the ./dev setup script to configure a local stack. This wizard automates:
- Checking prerequisites (Node.js, Tailscale).
- Configuring WorkOS environment credentials.
- Generating private configuration and signing keys.
- Configuring HTTPS mappings via Tailscale Serve.
Sources: scripts/dev/setup.sh:163-220
Summary
Coral's deployment infrastructure relies on strong isolation between development and production environments. Desktop releases are strictly signed and notarized, while web deployments are secured via mandatory OAuth configurations. All changes are guarded by containerized E2E tests (Reel) to ensure cross-platform compatibility and functional correctness.