Skip to content

single-binary.md

Latest commit

 

History

History
150 lines (116 loc) · 7 KB

single-binary.md

File metadata and controls

150 lines (116 loc) · 7 KB
Raw

Single Binary

OpenConnector can be compiled into one self-contained executable per platform with Bun. The binary embeds the runtime, the generated provider catalog, the database migrations, and the built web console, so it runs from any directory without a Node.js installation, a checkout, or node_modules. Nothing is extracted to disk at runtime.

Provider code is split into chunks inside the executable, and each provider's chunk is loaded the first time that provider is used, so the process only parses the server itself at startup. This is what keeps the binary's resident memory well under what a single bundle needs, and it is invisible to clients: the same routes, responses, and ETags.

Download

Every release attaches the six executables uncompressed, built and smoke-tested on each platform by CI, plus a SHA256SUMS file:

Asset Platform
open-connector-linux-x64 Linux x86_64
open-connector-linux-arm64 Linux ARM64
open-connector-darwin-arm64 macOS Apple Silicon
open-connector-darwin-x64 macOS Intel
open-connector-windows-x64.exe Windows x86_64
open-connector-windows-arm64.exe Windows ARM64

The names are stable across releases, so releases/latest/download/ always resolves to the newest release. A plain download does not keep the executable bit, so chmod +x after it:

curl -fsSLO https://github.com/oomol-lab/open-connector/releases/latest/download/open-connector-linux-x64
curl -fsSLO https://github.com/oomol-lab/open-connector/releases/latest/download/SHA256SUMS
sha256sum --ignore-missing -c SHA256SUMS
chmod +x open-connector-linux-x64
./open-connector-linux-x64

Replace latest with a tag such as v1.4.1 to pin a release. The macOS binaries were re-signed on a macOS runner, so they run without the codesign step described below.

Build

Building requires Node.js for the npm scripts and the Bun version pinned in .bun-version; the build script exits with an error under any other Bun version. Compile on Linux or macOS. Cross-compiling on a Windows host fails upstream (oven-sh/bun#11198).

npm install
npm run build:binary

npm run build:binary regenerates the catalog, builds the web console, and then writes six files under dist/:

dist/open-connector-linux-x64
dist/open-connector-linux-arm64
dist/open-connector-darwin-x64
dist/open-connector-darwin-arm64
dist/open-connector-windows-x64.exe
dist/open-connector-windows-arm64.exe

Each file is roughly 150 to 175 MiB. To build a subset, pass one or more target names after --:

npm run build:binary -- linux-x64 darwin-arm64

Bun downloads a runtime for every target that differs from the host (about 80 MB each, from registry.npmjs.org) into ~/.bun/install/cache on first use. These downloads are not integrity checked by Bun; TLS is the only protection.

npm run build:web also fetches the provider icon map from https://oomol.com/en/apps/catalog.json and fails when it is unreachable.

.bun-version and the @types/bun devDependency pin in package.json are bumped together.

Run

The binary takes the same environment variables as npm start; see configuration.md for the full reference. The ones you will usually set:

Variable Default Meaning
OOMOL_CONNECT_DATA_DIR ./data SQLite database, transit files, and upload staging.
PORT 3000 HTTP port.
HOST 127.0.0.1 Bind address.
OOMOL_CONNECT_DATABASE_URL unset PostgreSQL connection URL. When unset, SQLite under the data dir. 
OOMOL_CONNECT_DATA_DIR="$HOME/open-connector-data" \
PORT=3000 \
./dist/open-connector-linux-x64

With SQLite, migrations are applied automatically when the database opens, exactly as with npm start.

PostgreSQL Migrations

PostgreSQL migrations are explicit. The binary has a migrate subcommand that applies the embedded migrations and exits without starting the server. Run it before the first start and before starting a newer binary that contains pending migrations:

OOMOL_CONNECT_DATABASE_URL="postgresql://open_connector:password@db.example.com:5432/open_connector?sslmode=verify-full" \
./dist/open-connector-linux-x64 migrate

OOMOL_CONNECT_DATABASE_URL="postgresql://open_connector:password@db.example.com:5432/open_connector?sslmode=verify-full" \
./dist/open-connector-linux-x64

The server only checks schema readiness at startup and refuses to start when migrations are missing; it never applies PostgreSQL DDL itself. Without OOMOL_CONNECT_DATABASE_URL, migrate prints a notice that SQLite migrations are applied automatically and exits.

Differences From npm start

  • NODE_ENV is fixed to production inside the binary, so logs are always JSON (no pretty printing). OOMOL_CONNECT_LOG_LEVEL and every other environment variable are read at runtime as usual.

  • macOS: binaries built on macOS are ad-hoc signed by the build script, and the release binaries are re-signed on a macOS runner. Binaries built on another operating system carry an invalid ad-hoc signature, and macOS 27 and newer refuses to run them until you re-sign them:

    codesign --force --sign - dist/open-connector-darwin-arm64

    codesign --verify --verbose=2 <file> prints "valid on disk" for a usable binary and "invalid signature" for one that still needs re-signing.

Notes

  • Like npm start, the binary does not load .env files (Bun's automatic loading is disabled at build time).
  • On Windows, stopping the process from a process manager or taskkill terminates it immediately; the graceful shutdown hook that closes the HTTP server and the database on Linux and macOS does not run. This matches node src/server/index.ts on Windows.
  • The binary exits with code 1 when it cannot listen (for example when PORT is already in use) and when an uncaught exception is thrown while serving, as node src/server/index.ts always has. Earlier binaries printed the error and kept running; after a listen failure they hung without a server.
  • On Linux, Bun releases the pages of the embedded bundle and catalog once startup has finished, so resident memory after startup is lower than the startup peak. Pages touched later, such as a provider's first use or an on-demand schema read, fault back in, bounded by the size of the embedded section. BUN_FEATURE_FLAG_DISABLE_STANDALONE_MADVISE=1 disables the release.