Skip to content

Installing & Deploying With Docker (Offline)

Installing and deploying the Enterprise server without internet access (offline) using Docker Compose or Docker Swarm largely follows the same flow as online installs. The key difference is in loading images and binaries from local files instead of pulling them from our registry. The process consists of the following steps:

  1. Ensuring you meet the requirements, have all dependencies installed, and have all the necessary artifacts
  2. Running manage_server install --offline
  3. Reviewing the config.env file
  4. Starting services with manage_server start
  5. (Optional) Customizing your server

Requirements & Dependencies

If you haven't already, please review the requirements listed in the installation overview.

Before installing, you will also need the following:

  • Docker Engine version 20.10.0+
    • Docker Desktop 4.0+ should have this
  • A valid Binary Ninja Enterprise server license
  • The offline artifacts:
    • Enterprise server .zip from your purchase email, the customer portal, or the license recovery page
    • images.tar (server images) and manage_server executable for your platform, typically packaged together in an offline bundle

Warning

Alternative container runtimes for Docker like RailCar should theoretically work fine, but have not been tested and are not officially supported.

Warning

It is very important that the server.key file is kept secret. Anyone with access to the contents can decrypt traffic to/from the server.

Danger

We do not currently support installing as the root user due to a limitation of the default PostgreSQL container we leverage as part of the default deployment.

Installing the Server

Note

If you would like to use ARM64 images (e.g. if hosting on newer Apple hardware), pass --platform linux/arm64 to the ./manage_server install command.

Extract the Enterprise server .zip file from the purchase email, customer portal, or license recovery to a new folder. Place your offline image bundle (images.tar, for example) in the same directory.

Then, run the following:

./manage_server install --offline --imagefile images.tar

This will load the Enterprise server container images from the tarball and install the remaining the required files:

  • config.env: Default environment configuration for the service stack
  • keys/*: Files used for server verification (and can be replaced to customize SSL)
  • secrets/*: Newly generated credentials and identifiers for your server

It will also ask you two questions that need to be answered:

  1. What you want the initial password for the admin account, named admin, to be (which can be changed later)
  2. What the full domain you will be hosting the Enterprise server on is (e.g. https://enterprise.binary.ninja:3535/)

The install command takes a very large number of options for customizing your installation. Please see the command reference for a full list. Some commonly used options include:

  • --license-file: Takes an alternate path to your Enterprise server license file (default is ./license.dat)
  • --license-bundle: Takes an alternate path to your Enterprise client license bundle file (default is ./license-bundle.b64)
  • --port: Changes the default port from 3535 to your specified option
  • --no-tls: Tells the proxy to not use TLS (useful if you have another proxy in front of the Enterprise server that handles this)
  • --no-warp: Skips deploying the bundled WARP service

Review Configuration

After installation, please review the config.env file that was generated to ensure values look correct. If not, you can either re-install, or manually add, change, or remove any variables manually.

If you choose to re-install (recommended), please be aware that install will refuse to overwrite your config.env file to ensure customers don't accidentally overwrite their configuration. Simply move (or remove) this file to run it again.

If you choose to make changes manually (not recommended), see the example config.env for a list of accepted variables.

For some modifications, like creating bind mounts or specifying deploy labels, you will need to change the docker-compose.override.yml file instead. Please see the Docker configuration guide for more information.

Note

Make sure the port you chose (3535 is the default) is accessible before proceeding. Otherwise, you won't be able to verify that the server is working.

Starting Your Server

Starting your server for the first time should be as simple as:

./manage_server start

This will load the configuration from config.env into the environment, then use Docker Compose (or Docker Swarm, if you specified --swarm when installing) to start the server.

You will see all of the log output in your terminal from services starting. This is very useful on the first run so you can catch installation or configuration issues. While not an exhaustive list, the Troubleshooting guide has some guidance on finding and fixing common problems. The first run will take longer than subsequent runs as databases are created, migrations are run, and the object store is configured.

Once you are sure the deployment is working, you can use Ctrl-C to stop it. Then, you can start the server again while detached:

./manage_server start --detach

Warning

It is recommended that you change the initial admin password you set during install. This password is written, in plaintext, to ./secrets/initial_admin_password in order to pass it to the Enterprise server. See the section on changing admin credentials below. This file can also be safely removed after the server has been installed and is not used beyond initial setup.

Customizing Your Server

At this point, you're done! But, you may wish to customize your server further.

Hosting Client Installers

If you would like to host Binary Ninja Enterprise client installers through your local Enterprise server, please see this page for more information.

Changing Admin Credentials

If you want to change the admin credentials, there are two options:

  1. Run ./manage_server change_password admin and specify new credentials
  2. Log in to https://your_host:3535/admin with your credentials and use the CHANGE PASSWORD link
    • Remember that the port may be different if it was changed during installation.

Setting Firewall Rules

See the Firewall configuration guide for setting up firewall rules to help protect your Enterprise server.

Custom SSL Certificate

If you would like to use an SSL certificate other than the one we provide, see the Custom SSL Certificate guide. Or, you can run the Enterprise server behind a proxy that handles TLS for you.

Add a Forward Proxy

See this guide for an example of configuring Binary Ninja to work behind the Traefik proxy.

Email Setup

In order for users to be able to use the self-service "Forgot Password" functionality, you'll need to configure the email settings in the web-based admin interface.

Single Sign-On (SSO) Setup

In order for users to be able to use a Single Sign-On (SSO) provider (LDAP, OAuth2, OpenID Connect) to authenticate to the server with their client, you will need to configure SSO.

Hosting Client Updates

Note

Clients will need to check the "Use Enterprise Server For Updates" option in the "Updates" section of the Settings window within Binary Ninja to switch to using the Enterprise server for updates.

If you would like to host Binary Ninja Enterprise client updates on your local Enterprise server, please see this page. This is incredibly useful if you're hosting the server on a network without internet access or have many clients that are on the same network as the Enterprise server.