# Build Scripts and Tools in the OpenShip Repository: Complete Technical Guide

> Explore the oblien/openship monorepo's build scripts and tools, featuring Bun, Turborepo, pnpm, and GitHub Actions for streamlined development and CI/CD.

- Repository: [oblien/openship](https://github.com/oblien/openship)
- Tags: how-to-guide
- Published: 2026-07-29

---

**TLDR:** The oblien/openship monorepo utilizes a sophisticated toolchain centered around Bun-executed TypeScript releases (**[`scripts/release.ts`](https://github.com/oblien/openship/blob/main/scripts/release.ts)**), Turborepo for parallel task execution, pnpm workspace management, and GitHub Actions CI/CD pipelines that handle everything from Docker image publishing to cross-platform desktop installer generation.

The oblien/openship project is a multi-package monorepo that relies on purpose-built **build scripts and tools** to automate compilation, packaging, and publishing across its distributed architecture. These utilities manage local development bootstrapping, semantic version bumping, and artifact generation for the API, web dashboard, email server, and edge routing services.

## Release Orchestration Scripts

At the heart of OpenShip's build system sits a custom release automation framework written in TypeScript and executed via the Bun runtime.

### scripts/release.ts: Central Release CLI

The **[`scripts/release.ts`](https://github.com/oblien/openship/blob/main/scripts/release.ts)** file serves as the primary release orchestrator—a Bun-executed CLI that automates version bumping, Git tagging, GitHub Release creation, Docker image publishing, and in-app update advisories. According to the oblien/openship source code, this script verifies a clean working tree, ensures the current branch is `main`, computes the next semantic version (e.g., `0.4.9` → `0.4.10`), updates every [`package.json`](https://github.com/oblien/openship/blob/main/package.json) in the monorepo, commits the changes, and watches the CI run for live status.

### scripts/release-args.ts: Interactive Argument Builder

Supporting the main release script, **[`scripts/release-args.ts`](https://github.com/oblien/openship/blob/main/scripts/release-args.ts)** supplies the interactive prompt used to build consistent `argv` lists for all release paths, standardizing inputs across patch, minor, and major version workflows.

## Development Environment Bootstrap

OpenShip provides platform-specific wrapper scripts to standardize local development setup across operating systems.

### Cross-Platform Install Scripts

The repository includes three bootstrap scripts in the `scripts/` directory:
- **[`scripts/install.sh`](https://github.com/oblien/openship/blob/main/scripts/install.sh)** – For Linux/macOS environments
- **`scripts/install.ps1`** – For Windows PowerShell
- **[`scripts/install-source.sh`](https://github.com/oblien/openship/blob/main/scripts/install-source.sh)** – For source-based installations

These scripts automate Bun installation, cache restoration, and dependency installation via `pnpm install`, ensuring reproducible development environments without manual configuration.

## Package Management and Build Orchestration

### Turborepo Task Runner

The monorepo leverages **Turborepo** (invoked via `turbo` in root [`package.json`](https://github.com/oblien/openship/blob/main/package.json) scripts) to execute parallel builds (`turbo run build`), development servers (`turbo run dev`), linting, testing, and cleaning tasks across all workspaces. This enables efficient task scheduling with proper dependency graphs between `apps/*` and `packages/*`.

### pnpm Workspace Configuration

Dependency management is handled by **pnpm**, configured through **[`pnpm-workspace.yaml`](https://github.com/oblien/openship/blob/main/pnpm-workspace.yaml)** at the repository root. This declares the workspace layout, linking local packages under `apps/*` and `packages/*` while maintaining strict version consistency across the monorepo.

### Bun Runtime Environment

All **build scripts and tools** execute using **Bun**, a fast JavaScript runtime. The repository pins the exact Bun version in **`.bun-version`**, ensuring deterministic behavior across development machines and CI pipelines.

## Desktop Build Tooling

### Electron-Forge Configuration

For desktop application builds, OpenShip utilizes **Electron-Forge** as configured in **[`apps/desktop/forge.config.js`](https://github.com/oblien/openship/blob/main/apps/desktop/forge.config.js)**. The build process is triggered via:

```bash
bun run --cwd apps/desktop make

```

This command produces platform-specific installers including AppImage, `.deb`, `.rpm`, Windows zip files, and macOS DMG packages. The [`release.ts`](https://github.com/oblien/openship/blob/main/release.ts) script integrates this step into the automated release pipeline, invoking the desktop build during CI execution as defined in [`.github/workflows/release.yml`](https://github.com/oblien/openship/blob/main/.github/workflows/release.yml).

## CI/CD and Container Automation

### GitHub Actions Workflows

The `.github/workflows/` directory contains comprehensive automation pipelines:
- **[`release.yml`](https://github.com/oblien/openship/blob/main/release.yml)** – Orchestrates API binary builds, email server compilation, dashboard bundling, desktop installer generation, NPM publishing, and GitHub Release creation
- **[`docker-images.yml`](https://github.com/oblien/openship/blob/main/docker-images.yml)** – Handles GHCR image publishing for the API, dashboard, and edge components

The `publish-npm` job specifically strips workspace-style dependencies, runs smoke tests, and publishes the CLI to the NPM registry using OIDC trusted publishing.

### Docker Compose Configurations

Container orchestration is managed through:
- **[`docker/docker-compose.yml`](https://github.com/oblien/openship/blob/main/docker/docker-compose.yml)** – For local development and testing
- **[`docker/docker-compose.build.yml`](https://github.com/oblien/openship/blob/main/docker/docker-compose.build.yml)** – For production image builds

The [`release.ts`](https://github.com/oblien/openship/blob/main/release.ts) script can dispatch the [`docker-images.yml`](https://github.com/oblien/openship/blob/main/docker-images.yml) workflow directly via the `docker` sub-command without requiring version bumps or Git tag creation.

## Utility Scripts

### GeoIP Data Updates

The **`scripts/update-geoip.mjs`** script maintains the edge routing service's geographic data by pulling the latest MaxMind GeoIP dumps (or fallbacks) and writing JSON files used for geographic request routing decisions.

## Practical Usage Examples

### Running a Full Release

To execute a patch version bump with user announcements:

```bash
bun run release patch publish

```

This command sequence:
- Verifies a clean working tree and `main` branch status
- Computes next version (e.g., `0.4.9` → `0.4.10`)
- Updates all [`package.json`](https://github.com/oblien/openship/blob/main/package.json) files and creates Git tags
- Writes update advisories for desktop client banners
- Triggers the GitHub Release workflow and monitors CI status

### Publishing Docker Images Only

For targeted container updates without version bumps:

```bash
bun run release docker v0.4.10

```

This dispatches the [`docker-images.yml`](https://github.com/oblien/openship/blob/main/docker-images.yml) workflow directly to build and push GHCR images for the specified version, leaving the `:latest` tag unchanged and skipping Git tagging entirely.

### Bootstrapping a Fresh Development Environment

On Linux or macOS:

```bash
./scripts/install.sh

```

This installs Bun (if missing), reads the pinned version from `.bun-version`, restores the Bun cache, and executes `pnpm install` to prepare the workspace.

### Building Desktop Installers Locally

```bash
bun run --cwd apps/desktop make

```

Invokes Electron-Forge's `make` target to generate OS-specific installers for the current architecture.

## Summary

- **Release Automation:** The [`scripts/release.ts`](https://github.com/oblien/openship/blob/main/scripts/release.ts) Bun script orchestrates version bumps, Git tagging, and multi-platform publishing via interactive CLI prompts
- **Development Bootstrap:** Shell and PowerShell scripts in `scripts/` standardize environment setup across Linux, macOS, and Windows
- **Build Orchestration:** Turborepo manages parallel task execution while pnpm handles workspace dependency linking via [`pnpm-workspace.yaml`](https://github.com/oblien/openship/blob/main/pnpm-workspace.yaml)
- **Desktop Builds:** Electron-Forge configured in [`apps/desktop/forge.config.js`](https://github.com/oblien/openship/blob/main/apps/desktop/forge.config.js) generates cross-platform installers (AppImage, .deb, .rpm, DMG, Windows zip)
- **CI/CD Integration:** GitHub Actions workflows in `.github/workflows/` automate artifact building, Docker publishing to GHCR, and NPM releases via OIDC trusted publishing
- **Utility Scripts:** `scripts/update-geoip.mjs` maintains edge routing data for geographic request handling

## Frequently Asked Questions

### How does OpenShip handle version bumping across the monorepo?

OpenShip uses [`scripts/release.ts`](https://github.com/oblien/openship/blob/main/scripts/release.ts), a Bun-executed TypeScript CLI that automatically calculates semantic versions, synchronizes all [`package.json`](https://github.com/oblien/openship/blob/main/package.json) files across workspaces, commits changes, creates Git tags, and triggers GitHub Releases. The script validates repository state—requiring a clean tree, `main` branch, and up-to-date remote—before executing any modifications.

### Can I build and publish Docker images without creating a new release tag?

Yes. The release script supports a `docker` sub-command: `bun run release docker v0.4.10`. This dispatches the [`docker-images.yml`](https://github.com/oblien/openship/blob/main/docker-images.yml) workflow directly to build and push GHCR images for the API, dashboard, and edge components without modifying version numbers or creating Git tags, leaving the `:latest` tag untouched.

### What runtime is required to execute OpenShip's build scripts?

All build scripts require **Bun**, with the specific version pinned in `.bun-version` at the repository root. The [`scripts/install.sh`](https://github.com/oblien/openship/blob/main/scripts/install.sh) and `scripts/install.ps1` files can automatically install Bun if not present, ensuring consistent runtime behavior across development and CI environments.

### How are desktop applications compiled for different operating systems?

Desktop builds use **Electron-Forge** as configured in [`apps/desktop/forge.config.js`](https://github.com/oblien/openship/blob/main/apps/desktop/forge.config.js). The command `bun run --cwd apps/desktop make` generates platform-specific installers—AppImage, `.deb`, `.rpm`, Windows zip, or macOS DMG—based on the host OS. This step is integrated into the CI pipeline via [`.github/workflows/release.yml`](https://github.com/oblien/openship/blob/main/.github/workflows/release.yml) for automated release builds.