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.
A current test instance is running at https://msbi.ipb-halle.de/MassBank/.
Note
Although this version of MassBank is already considered as fully functional, it is still work in progress and in a testing phase!
Please create a new issue in case of observing any bug or discrepancy.
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
|---/massbank-volume
|---/postgres-data
|---...
The path to PostgreSQL via DB_LOCAL_PATH is "/MassBank3/data/postgres-data" by default. "/MassBank3/data/massbank-volume" is the default directory to store the MSP file needed for the similarity service and can be set via MSP_LOCAL_PATH. "/MassBank3/data/massbank-data" is the default directory to store the MassBank data in folders needed for the export service and can be set via EXPORT_MB_DATA_DIRECTORY.
In order to provide the MassBank data to the similarity service, download the latest release of MassBank data in MSP format and move it the data directoy (default):
mkdir ../data
mkdir ../data/massbank-volume
wget https://github.com/MassBank/MassBank-data/releases/latest/download/MassBank_NIST.msp
mv MassBank_NIST.msp ../data/massbank-volume/MassBank_NIST.msp
And in order to provide the MassBank data to the export service, download the latest release of MassBank data, unzip it and move the contributor's directories into data directoy (default):
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. The mb3tool service is responsible for that and stops after finishing that task.
To stop the system use:
docker compose down -v
This optional feature enables the verification of your MassBank instance by Google search console.
If the .env file contains a non-empty GOOGLE_SEARCH_CONSOLE_KEY property then this key will be used as meta-tag in every HTML document of the web interface.
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.
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
Description is coming soon.
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}
There is a graphical interface by means of Swagger UI to have insights into the different API endpoints and their specifications at our test instance.
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.