Install OPNexus on macOS

OPNexus runs as a Docker stack. On a Mac you use the Docker Desktop app for it: downloading and extracting in Finder, setting up and starting with a few commands in Terminal, everything else in the app. This guide takes you from a plain Mac to the first sign-in.

Before you start

OPNexus is developed and tested on Linux. On a Mac the same stack runs in Docker Desktop, on Apple chips (M1 and newer) as well as on Intel Macs; images exist for both. This path is not tested on every macOS version; feedback is welcome.
For permanent operation a Linux server or Linux VM is the better choice. A Mac that sleeps or is signed out monitors nothing and sends no notifications. A Mac mini that stays on is a reasonable exception (see below).
Docker Desktop licence: free for individuals, education, open-source projects and small businesses, paid for larger companies. See Docker for the current terms.

Requirements

A current macOS release (Docker Desktop supports the current and the two previous major versions) and an administrator account for the installation.
8 GB of RAM in the Mac as a sensible minimum.
Ports 80 and 443 are free (normally the case).
The Mac reaches your OPNsense firewalls over HTTPS (for example on the same network or through a VPN).

Step 1: Install Docker Desktop

Download Docker Desktop from docker.com for your Mac: “Apple Chip” or “Intel Chip” ( › About This Mac tells you which).
Open the .dmg file and drag Docker into Applications. Start Docker from Applications, accept the terms and confirm the setup with your password. You can skip the Docker sign-in.
Wait until “Engine running” appears at the bottom left.
Under Settings › General, turn on “Start Docker Desktop when you sign in to your computer”.

Step 2: Download and set up OPNexus

Download the release bundle opnexus-1.34.1.tar.gz (all versions on the release page). Double-clicking it in Finder extracts the folder opnexus-1.34.1. Move the folder to a permanent place, for example your home folder.
Open the Terminal app (Applications › Utilities). Type cd (with a space), drag the folder opnexus-1.34.1 from Finder into the Terminal window and press Enter.
Create the settings file and open it in TextEdit. Finder does not allow file names that start with a dot, so this works only in Terminal:
```
cp .env.example .env
open -e .env
```
Set these values in TextEdit and save (⌘S):
```
POSTGRES_PASSWORD=a-long-password-of-your-own
ADMIN_PASSWORD=your-sign-in-password-at-least-12-characters
```
If your password contains quotes, first turn off “Smart Quotes” under Edit › Substitutions.

Step 3: Start OPNexus

In Terminal (still in the OPNexus folder) enter:
```
docker compose up -d
```
The first time, Docker downloads the images; this takes a few minutes.
Switch to Docker Desktop › Containers. The group opnexus appears there. Expand it and wait until all services have a green dot and backend and frontend show “healthy”.

Sign in and trust the certificate authority

Open https://localhost and sign in as admin with the ADMIN_PASSWORD from the .env; the setup assistant guides you through the first steps. OPNexus uses its own certificate authority, so the browser warns at first. The connection is encrypted anyway.

Get rid of the warning for good:

Download https://localhost/opnexus-ca.crt (in the browser via “Continue to site”).

Compare the fingerprint before importing. In Terminal, in the OPNexus folder:

openssl x509 -in ~/Downloads/opnexus-ca.crt -noout -fingerprint -sha256
docker compose exec -T proxy cat /data/caddy/pki/authorities/local/root.crt | openssl x509 -noout -fingerprint -sha256

Both lines must show the same value.

Double-clicking opnexus-ca.crt opens Keychain Access; the certificate lands in the “login” keychain. Double-click the entry “Caddy Local Authority” › “Trust” › “When using this certificate”: Always Trust, close the window and confirm with your password.
Safari and Chrome pick this up immediately; reload the page.
Firefox has its own store: Settings › Privacy & Security › View Certificates › Authorities › Import.

Reach it from the network

For other machines to open OPNexus, your Mac needs a fixed address on the network (for example a DHCP reservation). Enter it with open -e .env in the .env (example address 10.0.0.5):

OPNEXUS_SITES=10.0.0.5
OPNEXUS_DEFAULT_SNI=10.0.0.5
FRONTEND_ORIGIN=https://10.0.0.5
COOKIE_SECURE=true
TRUST_PROXY_HEADERS=true

Apply the change with docker compose up -d in the OPNexus folder. If macOS asks whether Docker may accept incoming connections, choose “Allow”. For the Mac to stay reachable, prevent automatic sleep under System Settings › Energy (or Battery › Options). Import the certificate authority on every machine that uses OPNexus (with the address instead of localhost). Details are in the manual.

Day to day: OPNexus in Docker Desktop

Almost everything happens in the Docker Desktop app, section Containers. OPNexus shows up there as the group opnexus with the services backend, frontend, proxy, postgres and postgres-backup.

Task	In Docker Desktop
Is everything running?	Green dot on every service; `backend` and `frontend` also show “healthy”.
Stop / start OPNexus	■ (Stop) or ▶ (Start) in the `opnexus` row. Your data is kept.
Restart one service	⟳ (Restart) in its row, e.g. `proxy` after changing the addresses.
View the log	Click the service › tab “Logs”. Without `ADMIN_PASSWORD`, the log of `backend` shows the generated sign-in password on the first start.
Start automatically	Turn on Settings › General › Start Docker Desktop when you sign in; the containers then start by themselves.

Careful: Volumes hold OPNexus' data (database, firewall credentials, keys). A deleted volume is gone for good; take a full backup first (below).

Updates, backups and password: the opnexus tool

The bundled tool opnexus is a Bash script for Linux. On macOS you run it from its Docker image instead, which already contains Bash, Docker Compose and the signature check. Enter the commands in Terminal in the OPNexus folder (cd and drag the folder into Terminal):

docker run --rm -it -v /var/run/docker.sock:/var/run/docker.sock -v "$PWD:/project" git.opnexus.dev/opnexus/opnexus-updater:latest opnexus status

Task	Last word instead of `status`
Status and version	`status`
Update to the newest version (verifies signatures, backs up the database, rolls back on problems)	`update`
Undo the last update	`rollback`
Back up the database	`backup`
Full backup including credentials (asks for a passphrase)	`backup --full`
New sign-in password for `admin`	`password`

Details: tool documentation. An update also replaces the docker-compose.yml in the folder (the old one is kept as a backup); your own changes belong in a docker-compose.override.yml.

Troubleshooting

Problem	Solution
`command not found: docker`	Docker Desktop is not running or was just installed. Start Docker Desktop, wait for “Engine running”, open a new Terminal window.
`./opnexus` reports errors (e.g. `mapfile: command not found`)	The script needs Linux tools. On macOS run the tool from the Docker image (section above).
“port is already allocated”	Port 80 or 443 is in use (e.g. a local web server). Stop that service or change `PROXY_HTTPS_PORT` and `PROXY_HTTP_PORT` in the `.env`; then open `https://localhost:PORT`.
A service stays red or keeps restarting	In Docker Desktop click the service › “Logs”. Often `POSTGRES_PASSWORD` is missing from the `.env` or TextEdit saved the file as `.env.rtf` (then reopen with `open -e .env`).
Two-factor codes are rejected	The clock of the Docker environment can drift after sleep. Quit Docker Desktop (whale icon in the menu bar › Quit) and start it again.
Forgot the sign-in password	`opnexus password` via the tool (section above) sets a new one and shows it.

More help is in the manual.