Installation

To install crossmap, first clone the source-code repository and navigate into the project directory.

git clone https://github.com/tkonopka/crossmap.git
cd crossmap

The next steps involve installing the required dependencies, the graphical user interface, and a database service.

Primary software

The primary crossmap software is written in python and development is carried out using python version 3.7. You can check your version using

python --version

If your version is lower than 3.7, it is recommended to install the latest python interpreter before proceeding. (It is possible to have multiple python versions installed on a single computer, so upgrading python should not conflict with existing workflows.)

Beyond the python interpreter, the software requires a number of packages. These can be installed using the package manager pip.

pip install numpy scipy numba nmslib pymongo requests yaml

Note that the nmslib is a library for high-performance numerical computations. It can exploit hardware-specific features to maximize running speed. Because of this, the default installations via pip may output messages that the default installation may be sub-optimal. If this is the case, the messages will provide hints on how to compile the library from sources. It is recommended to follow those hints and to re-install the library.

After installing the required packages, the crossmap utility should be ready to run. As a diagnostic, the utility should be able to display a summary of the command-line interface.

python crossmap.py --help

This should display several lines with short descriptions of the arguments. Practical use-cases are covered in the documentation of the command-line interface.

Graphical user interface

Installation of the graphical user interface is optional. If you only intend to use the command-line tools, you can skip this section and continue with the installation of the database.

A graphical user interface is available to facilitate querying crossmap instances. This is implemented using a server-client design and requires additional python packages and a javascript development environment.

The back-end functionality is implemented using Django. This can be installed via pip.

pip install django

The front-end is implemented as a React application. To use it, you will need the node package manager, npm. You can check your version using

npm --version

If you do not yet have npm, or if your version is below 14.15, install it by following the instructions on the node home page.

The front-end relies on some external javascript packages. To install all the requirements, navigate into the crosschat directory and install the application.

cd crosschat
npm install
cd ..

Database

Most data operations performed by crossmap require access to a Mongo database.

If you already have mongodb, you can use configuration files (described in the next documentation page) to connect crossmap to an existing database. If you don’t already have mongodb, you can install it by following the Mongo installation guide.

In order to keep the database used by crossmap separate from any other database instances, it may be convenient to use a docker database container. This is the recommended route, as it also is a step toward deploying an entire crossmap application using a container system.

Docker setup

The first step toward running crossmap using docker containers is to ensure that docker itself is installed, configured, and running on the host machine.

Install docker and docker-compose following the official documentation.

On a Linux system, it may be necessary to configure a docker user group and to ensure that a user account is a member of that group.

sudo groupadd docker
usermod -a -G docker [USERNAME]

It may be necessary to log out and back in for the changes to take effect. Once the user group is configured, ensure that the docker service is running.

sudo service docker start
# or
sudo dockerd &
```

Database container

This section describes setup for a database-only docker container. This configuration is suitable for running a mongodb database and using ``crossmap`` outside of a container framework. For an alternative setup in which both the database and ``crossmap`` run in container, see the section on deploying crossmap applications.

To set up a docker container with a database, first determine a location on the file system where you’d like to store the database files. Then copy file crossmap-db.yaml, which is a docker-compose configuration, into the desired destination. (If you’d like to store the database files alongside the crossmap source code, you can leave the crossmap-db.yaml in place.)

Then, navigate into the location of the crossmap-db.yaml file, and launch a container using docker-compose.

docker-compose -f crossmap-db.yaml up -d

On a first attempt, this command will download software with database software. On subsequent attemps, startup should be very quick and display a status message.

When the database is no-longer needed, you can stop the database container.

docker-compose -f crossmap-db.yaml down