Skip to main content

Installing on macOS or Linux

James Herring
Updated

Installing on macOS or Linux

Precision Bridge ships an install.sh script for macOS and Linux that wraps docker compose with sensible defaults: it loads the container images, lays down the deployment files, sets up a pb management CLI, and starts the application. Everything happens in a terminal — there is no GUI installer for these platforms.

Windows users: This article does not apply to you. See Windows Native Build Quick Start for the fastest trial path, or Installing on Windows (Docker Build) for the full production install.

Prerequisites

Platform Prerequisite Notes
macOS Docker Desktop or Rancher Desktop Must be installed and running before you run install.sh. Automated Docker install (--install-docker) is not supported on macOS.
Linux (desktop) A container runtime — Docker Desktop, Rancher Desktop, or Podman Optional: pass --install-docker on a fresh machine to have the installer set up Docker Engine for you.
Linux (server / VM) None — --install-docker handles it Supported distributions: Ubuntu, Debian, RHEL, Rocky Linux, AlmaLinux, Fedora, Amazon Linux. Other distributions need Docker Engine installed manually first.

You also need a working bash, curl (or wget), and unzip. All three are present by default on macOS and on most Linux distributions; if unzip is missing on Linux, install it with your package manager (sudo apt-get install unzip, sudo dnf install unzip, etc.).

One-Line Install (Online)

On a machine with internet access, run the one-line installer. It downloads the installer, fetches the latest container images and deployment package from the Precision Bridge release CDN, loads the images, lays down the deployment files, generates the pb CLI, and starts the application:

curl -fsSL https://pub-1083f1834c6c4f81be06861875e276bb.r2.dev/releases/prod/latest/scripts/install.sh | bash

To pin a specific version, pass --version:

curl -fsSL https://pub-1083f1834c6c4f81be06861875e276bb.r2.dev/releases/prod/latest/scripts/install.sh | bash -s -- --version 10.0.24

Every artifact — install.sh itself, the container tarballs, their SHA256 checksums and Cosign signatures, and the deployment zip — is served from the Precision Bridge release CDN (Cloudflare R2). The installer does not download anything from GitHub.

For an air-gapped or pre-staged install, follow the Offline Install section below instead.

Download (Offline Package)

For an air-gapped install, download the deployment package on a machine with internet access, then transfer it to the target. The package contains:

File Purpose
install.sh The installer script
pb-deployment-{version}.zip Docker compose files, default .env, upgrade script
pb-app-{version}.tar.gz Precision Bridge application image
pb-license-{version}.tar.gz License service image
pb-prefect-{version}.tar.gz Prefect server image (powers scheduling)
pb-postgres-{version}.tar.gz PostgreSQL image
pb-redis-{version}.tar.gz Redis image
Matching .sha256 files SHA256 integrity checksum for each tarball
Matching .sig and .pem files Cosign signature and certificate for each tarball
sbom.spdx.json Software Bill of Materials (SPDX) for the application image

Every artifact is served from the Precision Bridge release CDN (Cloudflare R2) under the stable releases/prod/latest/ path — the same CDN the online installer uses. The following downloads the complete set into a pb-offline directory. It reads the current version from current-version.json so you never need to hard-code a version number:

BASE=https://pub-1083f1834c6c4f81be06861875e276bb.r2.dev/releases/prod/latest
VERSION=$(curl -fsSL ${BASE}/current-version.json | sed -E 's/.*"version":"([^"]+)".*/\1/')
mkdir -p pb-offline && cd pb-offline

# Installer, deployment package, and SBOM
curl -fLO ${BASE}/install.sh
curl -fLO ${BASE}/container/pb-deployment-${VERSION}.zip
curl -fLO ${BASE}/container/pb-deployment-${VERSION}.zip.sha256
curl -fLO ${BASE}/container/sbom.spdx.json

# Each image tarball with its checksum, signature, and certificate
for img in pb-app pb-license pb-prefect pb-postgres pb-redis; do
  for ext in .tar.gz .tar.gz.sha256 .tar.gz.sig .tar.gz.pem; do
    curl -fLO ${BASE}/container/${img}-${VERSION}${ext}
  done
done

Keep every file in the same directory — install.sh --offline expects the tarballs, checksums, and deployment zip side-by-side. To pin an earlier release instead of the latest, replace latest in BASE with the version number (for example releases/prod/10.0.24). The package is also available directly from Precision Bridge; contact help@precisionbridge.net if you cannot reach the CDN.

Scan and Verify the Images

For environments that require the images to be vetted before deployment, verify and scan the downloaded files on the connected machine — before transferring them across the air gap. All three checks below are independent; run as many as your security policy requires.

Verify checksums confirms the files arrived intact:

for img in pb-app pb-license pb-prefect pb-postgres pb-redis; do
  sha256sum -c "${img}-${VERSION}.tar.gz.sha256"   # use 'shasum -a 256 -c' on macOS
done

Verify Cosign signatures confirms the tarballs were produced by the Precision Bridge release pipeline. This requires the cosign binary and outbound access to Sigstore, so run it on the connected machine:

for img in pb-app pb-license pb-prefect pb-postgres pb-redis; do
  cosign verify-blob \
    --signature   "${img}-${VERSION}.tar.gz.sig" \
    --certificate "${img}-${VERSION}.tar.gz.pem" \
    --certificate-identity-regexp "https://github.com/precision-bridge/pb/" \
    --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
    "${img}-${VERSION}.tar.gz"
done

Scan for vulnerabilities with your image scanner. Load the tarballs, then scan the resulting images by name:

for img in pb-app pb-license pb-prefect pb-postgres pb-redis; do
  docker load -i "${img}-${VERSION}.tar.gz"
done

# Loaded image names:
#   ghcr.io/precision-bridge/pb:${VERSION}
#   ghcr.io/precision-bridge/pb-license:latest
#   prefecthq/prefect:3.6.18-python3.12
#   postgres:14
#   redis:7

trivy image ghcr.io/precision-bridge/pb:${VERSION}   # or: grype ghcr.io/precision-bridge/pb:${VERSION}

The included sbom.spdx.json can also be fed directly into SPDX-aware tooling (Trivy, Grype, Dependency-Track) for component and vulnerability analysis without loading the images:

trivy sbom sbom.spdx.json

Install (Offline Package)

From a terminal in the directory containing the downloaded files:

chmod +x install.sh
./install.sh --offline

The script:

  1. Runs pre-flight checks (Docker daemon, Docker Compose v2, disk space, port availability).
  2. Loads the container images from the local tarballs.
  3. Extracts pb-deployment-{version}.zip into ./precision-bridge/.
  4. Creates a pb management CLI in the install directory.
  5. Starts the application with docker compose up -d.
  6. Optionally installs pb globally to /usr/local/bin so you can run it from any directory.

When the installer finishes, open http://localhost:7502 in your browser and proceed to Licensing and Setup.

Common Options

Option Description
--version VERSION Install a specific version (default: latest, resolved from releases/prod/latest/current-version.json on the release CDN).
--port PORT Host port for the web UI (default: 7502). Use this if 7502 is taken.
--install-dir DIR Installation directory (default: ./precision-bridge).
--offline Skip all downloads and use local tarballs and deployment zip in the current directory (or --tarball-dir DIR).
--install-docker Linux only — install Docker Engine if it's not already present.
--no-start Lay down all files but do not start the service. Use when you want to review configuration first.
--yes, -y Skip confirmation prompts. Useful in scripted / automated installs.
--help Show the full option list.

Examples:

# Install to a custom directory
./install.sh --install-dir ~/apps/precision-bridge

# Use a different host port
./install.sh --port 8502

# Fresh Linux VM with no Docker installed
./install.sh --install-docker

# Install without starting the service
./install.sh --no-start

Fully Air-Gapped Install

If the target machine has no internet access at all, the same flow works — install.sh does not download anything when the tarballs are already present locally. Use --offline to make this explicit (it skips the version-check call to the public release index):

  1. On a machine with internet access, download the package per Download (Offline Package).
  2. Verify and scan the images per Scan and Verify the Images. Checksum and signature verification rely on Sigstore and your scanner's vulnerability database, so complete them here — the air-gapped machine only loads the pre-vetted tarballs.
  3. Transfer the pb-offline directory to the air-gapped machine (USB stick, internal artefact server, etc.).
  4. On the air-gapped machine: bash chmod +x install.sh ./install.sh --offline

The --offline flag still requires docker and docker compose to be available on the target machine. If you also need Docker Engine installed in an air-gapped environment, install it manually from your distribution's package mirror before running install.sh.

Management CLI

The installer creates a pb command in the install directory and offers to symlink it to /usr/local/bin so you can run it from anywhere.

Command Action
pb start Start all services
pb stop Stop all services (preserves data)
pb restart Restart all services
pb status Show running container status
pb logs Follow logs (pass a service name to filter, e.g. pb logs pb)
pb url Print the application URL
pb upgrade Upgrade using a newer set of tarballs
pb backup Create a backup archive of the data volume
pb uninstall Remove containers (data volume is preserved)

Upgrading

Request a newer deployment package from Precision Bridge and run:

pb upgrade /path/to/new-tarballs-directory

pb upgrade loads the new images, brings the service down, applies any compose changes, and brings it back up. The data volume is preserved across upgrades.

macOS Notes

  • Docker Desktop must be running before you run install.sh — the menu-bar whale icon should be solid (not animated).
  • Apple Silicon (M1/M2/M3/M4) and Intel Macs are both supported.
  • The pb global symlink is created in /usr/local/bin, which is on the default PATH for both architectures.

Linux Notes

  • The installer auto-detects your distribution from /etc/os-release when --install-docker is passed. If your distribution is not in the supported list, install Docker Engine manually from the Docker docs before running install.sh.
  • If your user account is not yet in the docker group, the installer falls back to running docker commands with sudo. Add yourself to the group (sudo usermod -aG docker $USER) and either log out / back in or run newgrp docker to remove the sudo requirement.
  • On Linux servers without a desktop GUI, you can run the same script over SSH — the installer detects non-interactive sessions and skips confirmation prompts automatically.
  • For VM-based installs, see Running in a Virtual Machine for nested-virtualisation guidance.

Next Steps

Related articles

Comments

0 comments

Please sign in to leave a comment.

Powered by Zendesk