diff --git a/docs/how_to/install_this_plugin.md b/docs/how_to/install_this_plugin.md index e5b1c11..4d0d49c 100644 --- a/docs/how_to/install_this_plugin.md +++ b/docs/how_to/install_this_plugin.md @@ -1,12 +1,83 @@ -# Install This Plugin +# Deploying a NOMAD Oasis with the UniSysCat Plugin -To install this plugin follow [part 4 of the FAIRmat tutorial 13](https://github.com/FAIRmat-NFDI/AreaA-Examples/tree/main/tutorial13/part4) or read the [NOMAD plugin documentation](https://nomad-lab.eu/prod/v1/staging/docs/plugins/plugins.html#add-a-plugin-to-your-nomad) for all details on how to deploy the plugin on your NOMAD Oasis instance. +## Prerequisites +- A GitHub account, which can be created for free on [github.com](https://github.com/signup?ref_cta=Sign+up&ref_loc=header+logged+out&ref_page=%2F&source=header-home). +- Docker installed on your computer; installation instructions can be found on [docs.docker.com/desktop/](https://docs.docker.com/desktop/). +- The following instructions are for the Windows operating system. If you are using Linux, please refer to the detailed instructions [here](https://github.com/FAIRmat-NFDI/AreaA-Examples/tree/main/tutorial13/part4) or read the [NOMAD plugin documentation](https://nomad-lab.eu/prod/v1/staging/docs/howto/oasis/plugins_install.html) for all details on how to deploy the plugin on your NOMAD instance. +To install this plugin, follow [part 4 of the FAIRmat tutorial 13](https://github.com/FAIRmat-NFDI/AreaA-Examples/tree/main/tutorial13/part4) or read the [NOMAD plugin documentation](https://nomad-lab.eu/prod/v1/staging/docs/plugins/plugins.html#add-a-plugin-to-your-nomad) for all details on how to deploy the plugin on your NOMAD Oasis instance. -If you already have a NOMAD Oasis, you just need to add the line +## Outline +1. Create a Docker image +2. Add the plugin +3. Update permissions +4. Run the OASIS + +## 1. Create a Docker image +We will now create a custom Docker image for your OASIS. There is a GitHub template repository with predefined workflows that can be used for this at [github.com/FAIRmat-NFDI/nomad-distribution-template](https://github.com/FAIRmat-NFDI/nomad-distribution-template). + +To use the template, choose the "Create a new repository" option after pressing the green "Use this template" button in the upper right corner. Please note that you have to be logged into GitHub to see this option. + +![gif for creating an Oasis deployment on GitHub](../images/Deploying%20Oasis%20with%20plugin.gif) + +## 2. Add the plugin +We will now add the plugin we developed as a demonstration for UniSysCat. To do this, we need to add the following line to the `plugins.txt` file: + +``` +git+https://github.com/FAIRmat-NFDI/nomad-unisyscat-plugin.git@main +``` + +We can do this directly from the GitHub web UI. Once this is saved, a workflow will run to create the image. + +![gif for adding the plugin to NOMAD Oasis deployment](../images/Deploying%20Oasis%20with%20plugin%202.gif) + +## 3. Update permissions +1. Make sure you have [Docker](https://docs.docker.com/engine/install/) installed. Docker nowadays comes with `docker compose` built in. Prior, you needed to install the stand-alone [docker-compose](https://docs.docker.com/compose/install/). +2. Download the `nomad-oasis.zip` archive from your distribution repository to your computer. +3. Unzip the `nomad-oasis.zip` file. + +![gif for downloading and unzipping the Oasis file](../images/Deploying%20Oasis%20with%20plugin%203.gif) + +4. Open Docker Desktop. +5. Open the Windows command prompt and set the directory to the location where you have unzipped the nomad-oasis file. Below is an example for navigating to the directory where we saved the file. Make sure to change this to the directory you specified. + +```sh +cd C:\Users\Fair-04\Documents\UniSysCat demo\nomad-oasis\nomad-oasis +``` + +6. Pull the images specified in the `docker-compose.yaml` (retrieved from the `nomad-oasis.zip`). Note that the image needs to be public or you need to provide a PAT. + +```sh +docker compose pull +``` + +7. Run it with Docker Compose in detached (`--detach` or `-d`) mode. + +```sh +docker compose up -d +``` + +8. Optionally, you can now test that NOMAD is running with: + +```sh +curl localhost/nomad-oasis/alive +``` + +![gif for pulling and decomposing the Oasis with Docker](../images/Deploying%20Oasis%20with%20plugin%204.gif) + +9. Finally, open [NOMAD Oasis](http://localhost/nomad-oasis) in your browser to start using your new NOMAD Oasis. + +```sh +http://localhost/nomad-oasis +``` + +![gif for accessing NOMAD Oasis locally](../images/Deploying%20Oasis%20with%20plugin%205.gif) + +## Additional Instructions +If you already have a NOMAD Oasis, you just need to add the line: ```sh git+https://github.com/FAIRmat-NFDI/nomad-unisyscat-plugin.git@main ``` -to the plugin.txt in your NOMAD Oasis repositorium. +to the `plugin.txt` in your NOMAD Oasis repository. \ No newline at end of file diff --git a/docs/how_to/use_this_plugin.md b/docs/how_to/use_this_plugin.md index aec98ef..24557c7 100644 --- a/docs/how_to/use_this_plugin.md +++ b/docs/how_to/use_this_plugin.md @@ -2,9 +2,9 @@ This plugin can be used in a NOMAD Oasis installation. Check the tips in [Install this plugin](install_this_plugin.md) for details. -Once the Oasis is deployed, you can generate different entries as shown below. +Once the NOMAD Oasis is deployed, you can generate different entries as shown below. -## Add new sample entries +## Create new sample entries ## Add instrument entry @@ -18,7 +18,7 @@ Once the Oasis is deployed, you can generate different entries as shown below. -## run a jupyter notebook to visualize the pdb file +## Run a jupyter notebook to visualize the `.pdb` file diff --git a/docs/images/Deploying Oasis with plugin 2.gif b/docs/images/Deploying Oasis with plugin 2.gif new file mode 100644 index 0000000..b274474 Binary files /dev/null and b/docs/images/Deploying Oasis with plugin 2.gif differ diff --git a/docs/images/Deploying Oasis with plugin 3.gif b/docs/images/Deploying Oasis with plugin 3.gif new file mode 100644 index 0000000..56c5816 Binary files /dev/null and b/docs/images/Deploying Oasis with plugin 3.gif differ diff --git a/docs/images/Deploying Oasis with plugin 4.gif b/docs/images/Deploying Oasis with plugin 4.gif new file mode 100644 index 0000000..a99178e Binary files /dev/null and b/docs/images/Deploying Oasis with plugin 4.gif differ diff --git a/docs/images/Deploying Oasis with plugin 5.gif b/docs/images/Deploying Oasis with plugin 5.gif new file mode 100644 index 0000000..83b1f65 Binary files /dev/null and b/docs/images/Deploying Oasis with plugin 5.gif differ diff --git a/docs/images/Deploying Oasis with plugin.gif b/docs/images/Deploying Oasis with plugin.gif new file mode 100644 index 0000000..d70d7d2 Binary files /dev/null and b/docs/images/Deploying Oasis with plugin.gif differ diff --git a/docs/index.md b/docs/index.md index 7b79730..406dba3 100644 --- a/docs/index.md +++ b/docs/index.md @@ -14,38 +14,38 @@ This example demonstrates how NOMAD effectively manages diverse research data, p The dataset used in this demonstration originates from a paper by C. Lorent *et al.* [(Angew. Chem. Int. Ed. 2021, 60, 15854–15862)](doi.org/10.1002/anie.202100451). -The paper introduces an innovative experimental setup for spectroscopic analyses of gas-converting metalloenzymes. It allows for adjustments in gas composition and temperature, enabling the preparation of specific redox states for characterization using complementary spectroscopic tools such as IR, EPR, or NRVS. +The paper introduces an innovative experimental setup for spectroscopic analyses of gas-converting metalloenzymes. It allows for adjustments in gas composition and temperature, enabling the preparation of specific redox states for characterization using complementary spectroscopic tools such as **IR**, **EPR**, or **NRVS**. ![Alt text](images/TOC%20figure%20from%20paper.png) This NOMAD Oasis demonstration illustrates the Research Data Management (RDM) of experiments focusing on the regulatory [NiFe]-hydrogenase from Ralstonia eutropha (ReRH). The experiments involve preparing the catalytic intermediate (Nia-C) using highly concentrated lyophilized samples of ReRH treated either in H2 or D2, followed by characterizing the sample via IR, Raman spectroscopy (RR), and Nuclear Resonance Vibrational Spectroscopy (NRVS). Additionally, it includes the calculation of vibrational frequencies. -The demonstration covers creating entries for different parts of the experiment, uploading raw data files from measurements and calculations, visualizing them in NOMAD, and demonstrating how different project members can collaborate. +The demonstration covers creating entries for different parts of the experiment, uploading raw data files from measurements and calculations, visualizing them in NOMAD, launching analysis tools like Jupyter notebooks with the files in NOMAD, and demonstrating how different project members can collaborate. ### **Supported Entry Types** In this demonstration, NOMAD supports multiple entry types, including: 1. **Experimental Data:** -- Tabular data files with the .dat file format. -- Binary data files with the .DSC file format. -- Electronic Lab Notebook (ELN) entries for samples, instruments, and processing, based on the NOMAD schema. +- Tabular data files with the `.dat` file format. +- Binary data files with the `.DSC` file format. +- Electronic Lab Notebook (ELN) entries for samples, instruments, and processes, based on NOMAD basic sections. -2. **Computational data:** -- Output files from Density Functional Theory (DFT) calculations based on the Gaussian 09 package. +1. **Computational data:** +- Output files from Density Functional Theory (DFT) calculations based on the ``Gaussian 09`` package. -### **Research Data:** +### **Research Data** -The data used in this NOMAD Oasis demonstration come from various sources, ensuring a comprehensive representation of the types of entries NOMAD can manage. The primary sources include: +The data used in this NOMAD Oasis demonstration come from various sources, ensuring a comprehensive representation of the types of entries NOMAD can handle. The primary sources include: -- In-situ Infrared (IR) spectroscopy for ReRH_Nia-C_H. -- 57Fe nuclear resonance vibrational spectroscopy (NRVS), both measured and simulated, for ReRH_Nia-C_H and ReRH_Nia-C_D. -- Electron paramagnetic spectroscopy (EPR) for ReRH_Nia-C_H. -- Density functional theory (DFT) calculations using the Gaussian package for ReRH_Nia-C_H and ReRH_Nia-C_D. +- **In-situ Infrared (IR) spectroscopy** for ``ReRH_Nia-C_H``. +- 57Fe **nuclear resonance vibrational spectroscopy (NRVS)**, both measured and simulated, for ``ReRH_Nia-C_H`` and ``ReRH_Nia-C_D``. +- **Electron paramagnetic spectroscopy (EPR)** for ``ReRH_Nia-C_H``. +- **Density functional theory (DFT)** calculations using the **Gaussian** package for ``ReRH_Nia-C_H`` and ``ReRH_Nia-C_D``. -By exploring this demonstration, users will gain a clearer understanding of how NOMAD can streamline research data management processes, enhance data quality, and foster collaboration across UniSysCat. +By exploring this demonstration, users will gain a clearer understanding of how NOMAD can streamline research data management processes, enhance and organize the data, and foster collaboration across UniSysCat.
@@ -65,8 +65,7 @@ How-to guides provide step-by-step instructions for a wide range of tasks, with ### Reference -The reference [section](reference/references.md) includes all CLI commands and arguments, all configuration options, -the possible schema annotations and their arguments, and a glossary of used terms. +The reference [section](reference/references.md) includes a list fo the measurements supported by this plugin.