Customizing Docker Deployment¶

Versions of the Enterprise server before 3.2 were somewhat inflexible in terms of customizing the deployment. If we didn't expose a CLI switch, you simply couldn't make the change. This was a problem for some of our users that needed to customize their deployment due to deployment and/or change management requirements.

We are working toward addressing many of these problems. For now, the biggest change we've made is to write the Docker Compose service definition template we use to disk, in docker-compose.yml. Do not edit this file directly - values in this file can changed by adding entries in docker-compose.override.yml.

Note

The service definition file is parameterized in multiple places to take values from the environment. These are supplied by manage_server at runtime. Please be advised that any changes to these parameters within the config file may break functionality of the server management CLI.

Using an External Database (Beta)¶

The Enterprise server can be used with an external PostgreSQL database server. You will need to specify some or all of the flags listed under "Database Options" to most manage_server commands.

Using External Block Storage (Beta)¶

The Enterprise server can be used with an external Amazon S3-compatible block storage service. You will need to specify some or all of the flags listed under "Object Store Options" to most manage_server commands.

Deploying with Docker Swarm¶

Deploying with Docker Swarm, instead of Docker Compose, is as easy as passing the --swarm flag to the start command.

Note

If you would like to specify a specific stack name, you can do so by using --swarm=<STACK_NAME> instead. You will need to specify the full name when issuing any other commands.

Warning

Please keep in mind that the --swarm flag will need to be passed to most other commands as well. The stop command, for example, will not actually stop your Docker Swarm deployment unless you remember to pass the --swarm flag.

Danger

Docker Swarm deployments currently do not support more than one node at this time. Using a replicated setup with Docker Swarm will very likely lead to Bad Things™ happening (such as data loss). Please contact us directly if you need support for a replicated deployment.

Deploying with Kubernetes¶

Deploying with Kubernetes is not officially tested or supported. You may be able to get it working by translating the service definition template file with a tool like kompose (after manually filling in all the environment-specific settings), but manage_server does not understand Kubernetes resource files and will not be able to operate on your deployment.

We currently do not have plans for explicit support for Kubernetes and are not able to offer support for any deployments made with Kubernetes.

Using a Non-Default Volume Location¶

Warning

You should always make a backup of your data before messing with any volume locations. Please proceed with caution!

Note

In order to change volume locations for an existing server installation, the server must be reinitialized following these steps

By default, the Enterprise server stores all of its data in a Docker volume stored on the main partition of the host. This isn't always desirable, especially when your host is ephemeral or lacks a lot of local data. It is possible to specify a volume location that is not the default location by modifying the service definition template file.

As an example, if you want to store data on a local mountpoint instead of a Docker volume, you'll want to add the following to docker-compose.override.yml:

volumes:
    static_files:
        driver_opts:
            type: none
            device: /home/user/binaryninja_enterprise_static_files
            o: bind
    data:
        driver_opts:
            type: none
            device: /home/user/binaryninja_enterprise_data
            o: bind

Any mountpoint can be used in the device keys above, including those that are backed by network-based filesystems like NFS.

Danger

Service interruption and/or data loss can occur if the volume you have mounted, such as an NFS volume, should ever become unmounted while the Enterprise server is running. Proceed at your own risk!

Moving Your Default Docker Root¶

If you would like to continue using a Docker volume, but would like to move all Docker volume data off of your current disk, this is supported by Docker itself. Unfortunately, it's not well-documented. Here are the steps we recommend taking, should you want to do this:

Stop the Enterprise server with ./manage_server stop
Stop Docker with sudo systemctl stop docker (or equivalent)
Make a backup of your Docker data folder (optional, but recommended)
Create /etc/docker/daemon.json if it doesn't exist
Set the contents to { "data-root": "/path/to/new/folder" } (include any other options you need set)
Rename the old docker data folder to ensure it won't get written to: sudo mv /var/lib/docker /var/lib/docker.old
Restart docker with sudo systemctl start docker
Start the Enterprise server again with ./manage_server start

Danger

Do not attempt to do any of this with symlinks. It won't work, and you run the risk of corrupting your data.