MassBank3

MassBank3 is the spectral reference library's next generation software product. The system consists of a modern software architecture and provides a new REST API with different services and a completely redesigned user interface.

This software is running at https://massbank.eu. It also provides a graphical interface using Swagger UI to get insights into the different REST API endpoints and their specifications.

There is a parallel instance at https://msbi.ipb-halle.de/MassBank. You can find the API's graphical interface here.

Installation

There are currently two ways to run MassBank:

1. Docker Compose
2. Kubernetes/Helm Charts

Docker Compose

Basic Settings

Make sure that Docker and Docker Compose are installed on your computer and ready to use.

Then clone the repository:

git clone https://github.com/MassBank/MassBank3.git

The directory MassBank/compose contains the env.dist file which serves as a template for environment variables. The system expects an .env file in that directory.

So navigate to that directory and copy the env.dist file into a new .env file.

cd MassBank3/compose && \
cp env.dist .env

The default structure of the data folder looks like the following:

/MassBank3
|---...
|---/compose
|---/data
    |---/MassBank-data
    |---/postgres-data
|---...

The path to PostgreSQL via DBLOCALPATH is "/MassBank3/data/postgres-data" by default. "/MassBank3/data/MassBank-data" is the default directory to store the MassBank data in record file format needed import data to different services and can be set via MBDATADIRECTORY.

And in order to provide the MassBank data to the services, download the latest release of MassBank data, unpack it and move the contributor's directories into data directoy (default):

mkdir ../data && \
wget https://github.com/MassBank/MassBank-data/archive/refs/heads/main.tar.gz && \
tar -xf main.tar.gz && \
mv MassBank-data-main ../data/MassBank-data/ && \
rm main.tar.gz

Now use docker compose to start the system (in daemon mode):

docker compose up -d

[!NOTE] Initially, the property MBDBINIT is set to true. Change that value to false after the database was filled within the first start. The database filling takes some time (circa 30 minutes on Apple's M3 Pro chip and a Docker environment with 4 CPUs and 8GB RAM allowed). The mb3tool service is responsible for that and stops running after finishing that task. Meanwhile you can check the amount of already imported data via the content page (frontend) or via following command line:

curl http://localhost:8081/MassBank-api/records/count

To stop the system use:

docker compose down -v

Advanced Settings

Add Custom MassBank Data

It's possible to add custom MassBank record data to your own MassBank instance. Simply add your MassBank files as subdirectory (or multiple directories) to the directory which was previously set via MBDATADIRECTORY (default is "/MassBank3/data/MassBank-data").

[!NOTE] The MassBank files need to be in the specified MassBank format. That means, every file should contain its own accession ID, peaks etc., see MassBank Record Format. In addition, each file name should contain the same accession ID and end with „.txt“, e.g. "MSBNK-IPB_Halle-PB001341.txt".

Distributor's Information

The DISTRIBUTORTEXT_ property is a free text field to insert any description of the distributor of a running MassBank instance.

And DISTRIBUTORURL_ should contain the URL to the distributor's imprint/website.

Title in Browser Tab

To customise the title in the web browser change the MB3FRONTENDBROWSERTABTITLE property.

Introduction/Welcome Text

A substitution of the text below the MassBank logo on the homepage is possible via editing MB3FRONTENDHOMEPAGEINTROTEXT.

Overwrite/Disable the News and Funding Section on Homepage

Both MB3FRONTENDHOMEPAGENEWSSECTIONTEXT_ and MB3FRONTENDHOMEPAGEFUNDINGSECTIONTEXT_ can be non-empty strings to replace the news and funding section content on the homepage with a free text. Set the value "disabled" to disable a section.

Add additional Section to Homepage

To enable a custom section with free text content set the variable MB3FRONTENDHOMEPAGEADDITIONALSECTIONNAME_ and MB3FRONTENDHOMEPAGEADDITIONALSECTIONTEXT_. As the names indicate, the first stands for the section name while the latter is the text to fill that section.

Extended HTML Head and Body

Head File

This optional feature enables to import of custom content in every webpage's HTML head of MassBank. This can be useful for the verification of your MassBank instance by Google search console or Bing, for example, or if the import of external libraries is needed when executing custom HTML body file content (see below).

If the .env file contains a non-empty HTMLHEADFILE property then its file content will be included in the head section of every HTML document of the web interface.

Body File

This optional feature enables the import of custom content in every webpage's HTML body of MassBank. This feature can be useful to implement a customised data privacy management, e.g. tracking. To display a data privacy section in every webpage's footer, the root element needs to have the id "data-privacy-container".

If the .env file contains a non-empty HTMLBODYFILE property then its file content will be included in the body section of every HTML document of the web interface to enable the data privacy management button. The HTML file content is responsible for what is shown in the graphical interface and for the executed code. The MassBank implementation does not influence or control that.

Mount Local Directory

In order to mount the HTML files, the variable HTMLLOCALDIR needs to be set to a local directory. For example in the root of the project.

Additionally, the volume needs to be mounted. Therefore, firstly, the directory (HTMLLOCALDIR) needs to be created and contain the head or both HTML files. Secondly, the volumes tag in the frontend section in the docker-compose file has to be re-activated.

Troubleshooting

In case your system is different from linux/amd64 then a warning might appear after starting docker compose:

The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested

Add the following properties to postgres, similarity-service and export-service in the docker-compose.yaml file to solve that problem:

platform: linux/amd64

Kubernetes/Helm Charts

A description is available at https://github.com/MassBank/MassBank-charts.

Frontend

The frontend can by default be accessed in the webbrowser at http://localhost:8080/MassBank and is composed via:

http://${MB3_FRONTEND_HOST}:${MB3_FRONTEND_PORT}${MB3_FRONTEND_BASE_URL}

REST API

To access this on your running instance, just visit the API URL in the browser. By default it is http://localhost:8081/MassBank-api and is defined by the environment variable MB3APIURL and concatenated via:

http://${MB3_API_HOST}:${MB3_API_PORT}${MB3_API_BASE_URL}

Examples

/records Endpoint

InChIKey

In order to get all records from the running instance at the API URL with an InChIKey of KWILGNNWGSNMPA-UHFFFAOYSA-N call the following URL:

{MB3_API_URL}/records?inchi_key=KWILGNNWGSNMPA-UHFFFAOYSA-N

The corresponding URL with default value (http://localhost:8081/MassBank-api) is:

http://localhost:8081/MassBank-api/records?inchi_key=KWILGNNWGSNMPA-UHFFFAOYSA-N

For example, to obtain the results via cURL use:

curl -X GET "http://localhost:8081/MassBank-api/records?inchi_key=KWILGNNWGSNMPA-UHFFFAOYSA-N"

The result is a set of complete MassBank records in JSON format.

Compound Name

To receive all records to the compound name mellein use:

http://localhost:8081/MassBank-api/records?compound_name=mellein

/records/search Endpoint

Compound Class

To receive all accession belonging to the compound class natural product use:

http://localhost:8081/MassBank-api/records/search?compound_class=natural+product

The result is a set of MassBank record IDs (accessions).

MS Type and Ion Mode

A request for searching MS2 spectra and negative ion mode looks like:

http://localhost:8081/MassBank-api/records/search?ms_type=MS2&ion_mode=NEGATIVE

Similarity Search

A similarity search request with the semicolon-separated tuples (m/z value, rel. intensity)

133.0648;225
151.0754;94
155.9743;112
161.0597;999
179.0703;750

and threshold value 0.8 looks like:

http://localhost:8081/MassBank-api/records/search?peak_list=133.0648%3B225%2C151.0754%3B94%2C155.9743%3B112%2C161.0597%3B999%2C179.0703%3B750&peak_list_threshold=0.8

The result is a set of MassBank record IDs (accessions) and the corresponding similarity score in JSON format. The calculation is done by the matchms package used in our similarity service.