Installing & Deploying With Podman (Online)¶

Warning

There is currently an open issue with podman that breaks pulling images from registries with authentication. A workaround is to symlink the docker and podman auth files together:

Linux: ln -s ${XDG_RUNTIME_DIR}/containers/auth.json ~/.docker/config.json

macOS: ln -s ~/.config/containers/auth.json ~/.docker/config.json

Installing and deploying the Enterprise server with an internet connection (online) using Podman Compose consists of the following steps:

Ensuring you meet the requirements and have all dependencies installed
Running manage_server install --container-engine podman
Reviewing the config.env file
Starting services with manage_server start
(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:

Podman version 4.9+
A valid Binary Ninja Enterprise server license

Warning

It is very important that 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 downloaded from the purchase email or the customer portal to a new folder.

Then, run the following:

./manage_server install --container-engine podman

This will authenticate to our private Docker registry with your Enterprise server license, download the Enterprise server container images, and install the remaining 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:

What you want the initial password for the admin account, named admin, to be (which can be changed later)
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

Warning

We are assuming, in this guide, that you are installing rootless. We should also support a standard deployment, but you may also want to pass --docker-host to change the socket to the global unix:///run/podman/podman.sock. Although we do try fallbacks if none is set explicitly, we default to the user socket, unix:///run/user/<uid>/podman/podman.sock.

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 Podman Compose 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:

Run ./manage_server change_password admin and specify new credentials
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.