Skip to content

Prerequisites macOS

This page lists the tools and dependencies required to build and run OpenAEV from source on macOS (Intel and Apple Silicon).

Backend

Homebrew

Install Homebrew if it is not already present:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Java 21

Install OpenJDK 21 and Maven (3.9 or later) with Homebrew:

brew install openjdk@21 maven

openjdk@21 is keg-only. Add it to your PATH and JAVA_HOME (for example in ~/.zshrc):

export PATH="/opt/homebrew/opt/openjdk@21/bin:$PATH"
export JAVA_HOME="/opt/homebrew/opt/openjdk@21"

On Intel Macs, Homebrew uses /usr/local/opt/openjdk@21 instead of /opt/homebrew/opt/openjdk@21.

Verify the installation:

java -version
mvn -version

Both commands must report Java 21. If java -version still prints Unable to locate a Java Runtime, the PATH / JAVA_HOME exports above are missing from the current shell.

Docker

Development services (PostgreSQL, Elasticsearch, RabbitMQ, Silo) run in containers. Use either Docker Desktop or Colima.

Option A — Docker Desktop

  1. Download and install Docker Desktop for Mac.
  2. Start Docker Desktop and wait until the engine is running.
  3. Verify the installation:
docker --version
docker compose version

Option B — Colima

Colima is a lightweight Docker runtime that works well on Apple Silicon:

brew install colima docker docker-compose

Start a VM with enough memory for Elasticsearch (the compose stack sets a 2 GB heap):

colima start --cpu 4 --memory 8 --disk 40

If Homebrew installed Compose as a Docker CLI plugin, add this to ~/.docker/config.json so docker compose is discovered:

{
  "cliPluginsExtraDirs": [
    "/opt/homebrew/lib/docker/cli-plugins"
  ]
}

Verify the installation:

docker --version
docker compose version

Tip

If docker compose pull fails with docker-credential-desktop: executable file not found, a leftover Docker Desktop credsStore entry is still in ~/.docker/config.json. Remove the "credsStore": "desktop" line, or point DOCKER_HOST at Colima (unix://$HOME/.colima/default/docker.sock) and use a config file that does not reference that helper.

Apple Silicon

The Elasticsearch and OpenSearch services in openaev-dev/docker-compose.yml already set -XX:UseSVE=0 for M-series compatibility. You do not need to change that flag.

Git

macOS includes Git through Xcode Command Line Tools:

xcode-select --install

Or install a current Git with Homebrew:

brew install git

Frontend

Node.js

Install Node.js 24.11.0 or later with nvm:

nvm install 24
nvm use 24
nvm alias default 24

Verify:

node -v

Yarn

OpenAEV uses Yarn 4, pinned in openaev-front/package.json. Install and enable Corepack, which fetches that version when you run yarn:

npm install -g corepack
corepack enable

What's next?