Advanced: Docker & VPS Install

Most people should install VolNinja Desktop: one download, nothing else to set up. This page covers the other path, which runs VolNinja with Docker from a terminal. Use it for a cloud server (VPS), Linux, an Intel Mac, or if you prefer running VolNinja in an isolated environment you control from the command line.

VolNinja ships as a self-contained package that Docker runs for you; you never install trading software piece by piece. When you are done, head to Connecting IBKR.

Before you start

1. An active VolNinja subscription or trial, with a verified email. The install command is unlocked once both are in place. If you have not signed up yet, start with Account & billing.
2. Docker Desktop. Download the free version for your platform from docker.com, install it, and launch it. When the whale icon in your menu bar or system tray stops animating, Docker is ready. On Windows, Docker Desktop also sets up WSL2 for you (more on that below). On Linux, Docker Engine plus the Docker Compose plugin works too.
3. IBKR Gateway or TWS, on the same machine. You can install it now or right after; the walkthrough is in Connecting IBKR.

Get your personal install command

Open your welcome page at volninja.com/welcome or your account page at volninja.com/account, and expand Advanced: install with Docker (VPS / headless). Copy the one-line install command shown there with the copy button.

This command is personal to you: it carries a private download credential tied to your subscription. Treat it like a password and do not share it.

The command looks like this (your credential replaces the …):

curl -fsSL https://volninja.com/install.sh | VOLNINJA_PULL_USER=appliance VOLNINJA_PULL_PASS=… bash

Running it installs VolNinja, starts it, and leaves you with a small volninja command for everyday control. Pick your platform below.

Install

Mac

1. Install Docker Desktop for Mac and launch it. Apple Silicon and Intel Macs are both supported; the right version is selected automatically.

2. Open the Terminal app (Applications → Utilities, or search "Terminal" with Spotlight).

3. Paste your personal install command and press Return. The first run downloads VolNinja before starting it.

4. When it finishes, VolNinja is already running. Confirm it with:

   volninja status
   

Windows

On Windows, this path runs VolNinja inside WSL, a lightweight Linux environment that Docker Desktop sets up for you. You run the install command in a WSL terminal, not in PowerShell.

1. Install Docker Desktop for Windows. During setup, keep the Use WSL 2 option enabled, then launch Docker Desktop.

2. If you have never used WSL, open PowerShell and run wsl --install, then restart if prompted. This gives you an Ubuntu Linux terminal.

3. Open your WSL terminal: search the Start menu for Ubuntu (or WSL).

4. Paste your personal install command and press Enter. The first run downloads VolNinja before starting it.

5. Confirm it is running:

   volninja status
   

Linux

1. Install Docker Engine and the Docker Compose plugin (Docker Desktop for Linux works too). Start Docker, and make sure your user is allowed to run it without sudo.

2. Open a terminal.

3. Paste your personal install command and press Enter. The first run downloads VolNinja before starting it.

4. Confirm it is running:

   volninja status
   

VPS (a cloud server)

Running VolNinja on a small cloud server (a VPS) lets it trade around the clock without depending on your laptop being open. The setup is the same as Linux, with one difference at the end: because a server has no desktop browser, you connect it to your account from the command line.

1. On the VPS (Ubuntu or Debian works well), install Docker Engine and the Docker Compose plugin, and start Docker.

2. Connect to the server over SSH.

3. Paste your personal install command and press Enter.

4. Confirm it is running with volninja status.

5. Connect it to your account from the terminal:

   volninja pair --headless
   

   Follow the short code and link it prints on your own computer to approve the connection.

Confirm it is running

Two commands tell you the state of a Docker install.

• volninja status lists each part of VolNinja and whether it is running and healthy, shows the folder VolNinja lives in, and reports whether the machine is connected to your account yet.
• volninja doctor checks the prerequisites for you (Docker installed and running, VolNinja responding) and flags anything that is missing.

When status shows the services running and healthy, VolNinja is up and ready to connect.

Connect it to your account

A one-time pairing links this machine to your VolNinja account. There is nothing to copy and no tokens to paste; you approve it in your browser.

On a Mac, Windows, or Linux desktop, run:

volninja pair

This opens the VolNinja Setup page in your browser. Follow the same three steps as on the desktop app, described in Connect it to your account. On a headless VPS, use volninja pair --headless instead, as shown in the VPS steps above.

Pairing is covered in more detail in Device pairing.

Everyday control

With a Docker install, you manage VolNinja with a few commands:

Using your own database

VolNinja keeps all of your data in a Postgres database that ships with the appliance. You do not need to set this up, and most people never change it.

If you already run your own Postgres and would rather VolNinja used that, open ~/volninja/.env in a text editor and add a line pointing at your server:

DATABASE_URL=postgresql+psycopg2://user:password@host.docker.internal:5432/autotrader2

Use host.docker.internal for a database on the same computer as VolNinja; 127.0.0.1 there would mean "inside VolNinja's own container", not your machine. For a database on another machine, use its hostname or IP address.

Then apply it:

volninja restart

A few things to know:

• The database does not have to exist yet. VolNinja creates it on the next start. The server does have to be running, and the user in the address needs permission to create databases.
• VolNinja reserves two more names on that server. Alongside the database you name, it uses <name>_volninja_prev and <name>_volninja_restore, which it creates, renames and drops while it backs up and restores. The name you pick must be lowercase letters, digits and underscores, must not start with a digit, and must be at most 46 characters long.
• Nothing is copied over. Pointing VolNinja at a different database gives you a fresh, empty one. To move your existing data, take a backup first with volninja backup, switch, then volninja restore.
• If VolNinja cannot reach the database, it will not start. It never falls back to the bundled one, because that would split your trading history across two places. Run volninja doctor to see what it found.
• Use a database on your own machine or local network. VolNinja talks to its database constantly, and a database reached over the internet will make it slow and unreliable.
• Restoring a backup needs the database to itself, so close any other program connected to it first, including your own psql session.

You can go back to the bundled database at any time by removing the DATABASE_URL line and running volninja start again. The bundled database keeps your old data, so switching back restores what was there before you switched away.

Keeping it up to date

When a new version is available, a banner across the top of the trading app tells you, and you apply it with one command, volninja update. It backs up your database first and rolls itself back if anything goes wrong. The details are in Updating VolNinja.

Next steps

VolNinja is installed, running, and connected to your account. Now:

• Connect IBKR — get IBKR Gateway or TWS ready and confirm the connection.
• Take the tour — a quick walk through the main screens before your first trade.