Install OPNexus on Windows

OPNexus runs as a Docker stack. On Windows you use Docker Desktop with WSL 2 – the containers are the same as on Linux. This guide takes you from a plain Windows install to signing in.

Before you start

OPNexus is developed and tested on Linux. On Windows the same stack runs in Docker Desktop. This route has not been verified on every Windows version; feedback is welcome.
For permanent operation a Linux server or Linux VM is better. Docker Desktop only starts after you sign in to the PC and stops while the PC sleeps – during that time there is neither monitoring nor notifications. Windows is a good fit for trying it out, an always-on office PC or a test setup.
Windows Server: Docker Desktop is not supported there. Use a Linux VM (Hyper-V or VMware) and follow the Linux quick start.
Docker Desktop licence: free for individuals, education, open-source projects and small businesses, paid for larger companies. Docker publishes the current terms.

Requirements

Windows 11 or Windows 10 (64-bit, current version) and administrator rights for the setup.
Hardware virtualisation enabled in BIOS/UEFI (usually the default; Task Manager › Performance › CPU shows “Virtualization: Enabled”).
Enough memory for Docker next to your other programs; 8 GB in the PC is a sensible minimum.
Ports 80 and 443 are free (no IIS, no other local web server). Check in PowerShell: netstat -ano | findstr ":443" – no output means free.
The PC can reach your OPNsense firewalls over HTTPS (for example on the same network or through a VPN).

Step 1: Set up WSL 2

Open PowerShell as administrator (right-click Start › “Terminal (Admin)”) and install WSL with Ubuntu:

wsl --install

Restart Windows afterwards. When you first start “Ubuntu” (Start menu) you create a user name and password for the Linux environment. To check that WSL 2 is active:

wsl -l -v

The “VERSION” column must show 2.

Step 2: Install Docker Desktop

Download Docker Desktop for Windows from docker.com and install it with the option “Use WSL 2 instead of Hyper-V”.
Start Docker Desktop and wait until it says “Engine running” at the bottom left.
Open Settings › Resources › WSL Integration, switch on “Enable integration with my default WSL distro” and your Ubuntu, then choose “Apply & restart”.
Under Settings › General, “Start Docker Desktop when you sign in to your computer” is recommended.

Open an Ubuntu window and check both:

docker version
docker compose version

Both commands must print a version without errors.

Step 3: Install OPNexus

Type all following commands in the Ubuntu window. Keep OPNexus in the Linux file system (not under /mnt/c): it is much faster, and the opnexus tool for updates and backups runs there.

Download the current release bundle from the releases page (file opnexus-X.Y.Z.tar.gz). Replace X.Y.Z below with the version number:

mkdir -p ~/opnexus && cd ~/opnexus
curl -LO https://git.opnexus.dev/opnexus/opnexus/releases/download/vX.Y.Z/opnexus-X.Y.Z.tar.gz
tar xzf opnexus-X.Y.Z.tar.gz && cd opnexus-X.Y.Z
install -m 600 .env.example .env
nano .env

If curl does not work for you, download the file in your browser and copy it into the ~/opnexus folder; in Windows Explorer you reach it at \\wsl$\Ubuntu\home\YOUR-NAME\opnexus.

In the .env set at least POSTGRES_PASSWORD to a long password of your own (saving in nano: Ctrl+O, Enter, Ctrl+X). You can leave ADMIN_PASSWORD empty; OPNexus then generates one. Start the stack:

docker compose pull && docker compose up -d --no-build
./opnexus password

The last command shows the sign-in password for the user admin once. The first download of the images takes a few minutes. docker compose ps shows that all services are running and “healthy”.

Step 4: Sign in

Open https://localhost in your browser. OPNexus uses its own certificate authority, so the browser warns at first; the connection is encrypted regardless. Sign in as admin with the password shown. The setup assistant then walks you through your own password, two-factor sign-in and the first firewall.

Getting rid of the warning: import the certificate authority as trusted, once.

Download https://localhost/opnexus-ca.crt (in the browser via “Continue to site”).
Compare the fingerprint before importing: in PowerShell, certutil -hashfile opnexus-ca.crt SHA256 prints the file's SHA-256 value. In the Ubuntu window, docker compose exec -T proxy cat /data/caddy/pki/authorities/local/root.crt | openssl x509 -noout -fingerprint -sha256 prints the server's value. They must match (ignore the colons).
Import the file: double-click › “Install Certificate” › “Local Machine” (or “Current User”) › “Place all certificates in the following store” › Trusted Root Certification Authorities. Or in an administrator PowerShell: certutil -addstore -f "ROOT" opnexus-ca.crt.
Restart the browser. Firefox has its own store: Settings › Privacy & Security › View Certificates › Authorities › Import.

Reaching it from the network

If other computers should open OPNexus, enter the address of your Windows PC in the .env (here 10.0.0.5 as an example; it should be fixed, for instance by a DHCP reservation):

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

Then run docker compose up -d in the Ubuntu window. Import the certificate authority on every computer that uses OPNexus (step 4, with the address instead of localhost). If another computer cannot reach the page, the Windows firewall does not allow port 443 yet. In an administrator PowerShell:

New-NetFirewallRule -DisplayName "OPNexus HTTPS" -Direction Inbound -Protocol TCP -LocalPort 443 -Action Allow -Profile Private

Limit the rule to the network OPNexus should be reachable from. Details on addresses, names and TLS are in the handbook (German). Do not expose OPNexus unprotected to the internet.

Operations: update, back up, stop

Everything in the Ubuntu window, in the folder ~/opnexus/opnexus-X.Y.Z:

Task	Command
See the state	`./opnexus status`
Update (verifies signatures, rolls back on problems)	`./opnexus update`
Undo the last update	`./opnexus rollback`
Back up the database	`./opnexus backup`
Stop (data stays)	`docker compose stop`
Start again	`docker compose up -d`

The tool documentation describes updating in detail. Careful: docker compose down -v also deletes the database. It is meant for removing OPNexus for good.

Updates by click in the web interface (the optional updater container) are not verified on Windows; use ./opnexus update there.

Troubleshooting

Problem	Solution
`docker: command not found` in the Ubuntu window	Docker Desktop is not running, or WSL integration for your Ubuntu is off (step 2, point 3).
“Cannot connect to the Docker daemon”	Start Docker Desktop and wait until it says “Engine running”.
“port is already allocated” or “address already in use”	Port 80 or 443 is taken (often IIS or another web server). Stop that service, or change `PROXY_HTTPS_PORT` and `PROXY_HTTP_PORT` in the `.env`; the address in the browser (and in `OPNEXUS_SITES`/`FRONTEND_ORIGIN`) then carries the port.
Two-factor codes are rejected	The clock of the WSL environment can drift after Windows sleeps. Run `wsl --shutdown` in PowerShell and restart Docker Desktop.
The stack does not start on its own after a reboot	Docker Desktop only starts after you sign in. Switch on “Start Docker Desktop when you sign in” and sign in; the containers then start themselves.
Errors about odd characters in the `.env`	The file was saved with Windows line endings (CRLF). Edit it with `nano` in the Ubuntu window, or switch the editor to “LF”.
Sign-in password lost	`./opnexus password` sets a new one and shows it once.

More help is in the handbook (German).