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.
There are currently two ways to run MassBank:
- Docker Compose
- Kubernetes/Helm Charts
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 DB_LOCAL_PATH 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 MB_DATA_DIRECTORY.
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 MB_DB_INIT 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
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 MB_DATA_DIRECTORY (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".
The DISTRIBUTOR_TEXT property is a free text field to insert any description of the distributor of a running MassBank instance.
And DISTRIBUTOR_URL should contain the URL to the distributor's imprint/website.
To customise the title in the web browser change the MB3_FRONTEND_BROWSER_TAB_TITLE property.
A substitution of the text below the MassBank logo on the homepage is possible via editing MB3_FRONTEND_HOMEPAGE_INTRO_TEXT.
Both MB3_FRONTEND_HOMEPAGE_NEWS_SECTION_TEXT and MB3_FRONTEND_HOMEPAGE_FUNDING_SECTION_TEXT 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.
To enable a custom section with free text content set the variable MB3_FRONTEND_HOMEPAGE_ADDITIONAL_SECTION_NAME and MB3_FRONTEND_HOMEPAGE_ADDITIONAL_SECTION_TEXT. As the names indicate, the first stands for the section name while the latter is the text to fill that section.
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 HTML_HEAD_FILE property then its file content will be included in the head section of every HTML document of the web interface.
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 HTML_BODY_FILE 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.
In order to mount the HTML files, the variable HTML_LOCAL_DIR 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 (HTML_LOCAL_DIR) 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.
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
A description is available at https://github.com/MassBank/MassBank-charts.
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}
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 MB3_API_URL and concatenated via:
http://${MB3_API_HOST}:${MB3_API_PORT}${MB3_API_BASE_URL}
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.
To receive all records to the compound name mellein use:
http://localhost:8081/MassBank-api/records?compound_name=mellein
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).
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
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.