|
1 | 1 | # ODTP Component Template |
2 | | -This is a template that facilitates the development of new odtp-components |
3 | 2 |
|
4 | | -Please follow the next steps to adapt your tool. |
| 3 | +This is a template that facilitates the development of new `odtp-components`. An `odtp` compatible component is a docker container able to perform a functional unit of computing in the digital twin. You can think of it as a blackbox that takes inputs files and/or parameters and perfom a task. Usually this lead to some files as a result (Ephemeral component), or to a visualization (Interactive component). |
5 | 4 |
|
6 | | -## Use of the template |
| 5 | +Internally a component will run a bash script `./app/app.sh` that must include the commands for running your tool, and managing the input/output logic. While input files are located in the folder `/odtp/odtp-input`, parameters values are represented by environment variables within the component. In this way you can access to them by using `$` before the name of your variable. Finally, the output files generated are requested to be placed in `/odtp/odtp-output/`. |
7 | 6 |
|
8 | | -Depending on the type of tool you may want to follow one of these procedure. |
| 7 | +## Internal data structure of a component |
9 | 8 |
|
10 | | -### Scripts in a repository (or tool under development) |
| 9 | +When the container is built an specific folder structure is generated: |
11 | 10 |
|
12 | | -1. Identify which parameters would you like to expose. |
13 | | -3. Configure the Dockerfile to pull your repo and install all needed dependencies. |
14 | | -4. Configure dependencies in requirements.txt if the dependencies offered in the repo are not compatible with the docker image. |
15 | | -5. Configure the app/app.sh file to run the tool |
16 | | -6. (Optional) Make use of config_templates if your tool requires the generation of a config file. |
17 | | -7. Describe all the metadata in odtp.yml |
18 | | -8. Publish your tool in the ODTP Zoo. |
| 11 | +- `/odtp`: The main folder. |
| 12 | +- `/odtp/odtp-component-client`: This is the odtp client that will manage the execution, logging, and input/output functions of the component. It is include as a submodule, and the user doesn't need to modify it. |
| 13 | +- `/odtp/odtp-app`: This folder have the content of `/app` folder in this template. It contains the tool execution bash script and the tool configuration files. |
| 14 | +- `/odtp/odtp-workdir`: This is the working directory where the tool repository should be placed and all the middle files such as cache folders. |
| 15 | +- `/odtp/odtp-input`: Input folder that is be mounted as volume for the docker container. |
| 16 | +- `/odtp/odtp-output`: Output folder that is mounted as volume for the docker container. |
| 17 | +- `/odtp/odtp-logs`: Folder reserved for internal loggings. |
| 18 | +- `/odtp/odtp-config`: Folder reserved for odtp configuration. |
19 | 19 |
|
20 | | -### Tool published in PIP/Conda/R |
| 20 | +## How to create an odtp compatible component using this template? |
21 | 21 |
|
22 | | -TO BE DONE |
| 22 | +1. Identify which parameters would you like to expose. |
| 23 | +2. Configure the Dockerfile to install all the OS requirements needed for your tool to run. |
| 24 | + 1. (Optional) If your tool requires python, and the dependencies offered in the repo are not compatible with the docker image you can configure custom dependencies in requirements.txt |
| 25 | +3. Configure the `app/app.sh` file to: |
| 26 | + 1. Clone the repository of your tool and checkout to one specific commit. |
| 27 | + 2. (Optional) If your app uses a config file (i.e. `config.yml` or `config.json`), you need to provide a templace including placeholders for the variables you would like to expose. Placeholders can be defined by using double curly braces wrapping the name of the variable, such as `{{VARIABLE}}`. Then you can run `python3 /odtp/odtp-component-client/parameters.py PATH_TO_TEMPLATE PATH_TO_OUTPUT_CONFIG_FILE` and every placeholder will be replaced by the value in the environment variable. |
| 28 | + 3. Copy (`cp -r`) or create symbolic links (`ln -s`) to locate the input files in `/odpt/odtp-input/` in the folder. |
| 29 | + 4. Run the tool. You can access to the parameters as environemnt variables (i.e. `$PARAMETER_A`) |
| 30 | + 5. Manage the output exporting. At the end of the component execution all generated output should be located in `/odtp/odtp-output`. Copy all output files into this folder. |
| 31 | +4. Describe all the metadata in `odtp.yml`. Please check below for instructions. |
| 32 | +5. Publish your tool in the ODTP Zoo. (Temporaly unavailable) |
23 | 33 |
|
24 | | -### Adding Semantic Context. |
| 34 | +### Semantic Validation |
25 | 35 |
|
26 | | -TO BE DONE |
| 36 | +ODTP will be able to validate the input/output files. In order to do this we use SHACL validation. However, the developer should provide a schema of the input/output schema. This section is still under development and it will be available soon. |
27 | 37 |
|
28 | | -## Testing the component. |
| 38 | +## Testing the component |
29 | 39 |
|
30 | | -This component can be tested in isolation with the following instructions. |
| 40 | +There are 3 main ways in which you can test a component and the different odtp features. |
31 | 41 |
|
32 | | -1. Prepare manually a folder called volume containing the input files/folder needed: |
| 42 | +1. Testing it as a docker container |
| 43 | +2. Testing it as a single component using `odtp` |
| 44 | +3. Testing it in a `odtp` digital twin execution |
33 | 45 |
|
34 | | -2. Create your `.env` file with the parameters. **If you do not have MONGODB and/or S3 activated omit this step, and just provide the scenario as environmental variable.** |
| 46 | +When developing we recomend to start by testing the component via docker and then follow with the others. |
| 47 | + |
| 48 | +### Testing the component as a docker container |
| 49 | + |
| 50 | +The user will need to manually create the input/output folders and build the docker image. |
| 51 | + |
| 52 | +1. Prepare the following folder structure: |
35 | 53 |
|
36 | 54 | ``` |
37 | | -PARAMETER_A=A |
38 | | -PARAMETER_B=B |
39 | | -MONGODB_CLIENT=mongodb://..... |
40 | | -S3_SERVER=https://.... |
41 | | -S3_ACCESS_KEY=Q0ISQ.... |
42 | | -S3_SECRET_KEY=OoPthI.... |
43 | | -S3_BUCKET_NAME=13301.... |
| 55 | +- testing-folder |
| 56 | + - data-input |
| 57 | + - data-output |
44 | 58 | ``` |
45 | 59 |
|
46 | | -3. Build the dockerfile. **PLEASE MODIFY THE NAME OF THE TOOL** |
| 60 | +Place all required input files in `testing-folder/data-input`. |
| 61 | + |
| 62 | +2. Create your `.env` file with the following parameters. |
47 | 63 |
|
48 | 64 | ``` |
49 | | -docker build -t odtp-app . |
| 65 | +# ODTP COMPONENT VARIABLES |
| 66 | +PARAMETER-A=..... |
| 67 | +PARAMETER-B=..... |
50 | 68 | ``` |
51 | 69 |
|
52 | | -4. Run the following command. **PLEASE MODIFY THE NAME OF THE TOOL** |
| 70 | +3. Build the dockerfile. |
53 | 71 |
|
54 | 72 | ``` |
55 | | -docker run -it --rm -v {PATH_TO_YOUR_VOLUME}:/odtp/odtp-volume --env-file .env odtp-app |
| 73 | +docker build -t odtp-component . |
| 74 | +``` |
| 75 | + |
| 76 | +4. Run the following command. |
| 77 | + |
| 78 | +``` |
| 79 | +docker run -it --rm \ |
| 80 | +-v {PATH_TO_YOUR_INPUT_VOLUME}:/odtp/odtp-input \ |
| 81 | +-v {PATH_TO_YOUR_INPUT_VOLUME}:/odtp/odtp-output \ |
| 82 | +--env-file .env \ |
| 83 | +odtp-component |
| 84 | +``` |
| 85 | + |
| 86 | +This command will run the component. If you want debug some errors and execute the docker in an interactive manner, you can use the flag `--entrypoint bash` when running docker. |
| 87 | + |
| 88 | +Also if your tool is interactive such as an Streamlit app, don't forget to map the ports by using `-p XXXX:XXXX`. |
| 89 | + |
| 90 | +### Testing the component as part of odtp |
| 91 | + |
| 92 | +To execute the command as part of `odtp` please refer to our `odtp` documentation: |
| 93 | + |
| 94 | +https://odtp-org.github.io/odtp-manuals/ |
| 95 | + |
| 96 | +## `odtp.yml` |
| 97 | + |
| 98 | +ODTP requires a set of metadata to work. These field should be filled by the developers. |
| 99 | + |
| 100 | +```yml |
| 101 | +# This file should contain basic component information for your component. |
| 102 | +- component-name: Component Name |
| 103 | +- component-author: Component Author |
| 104 | +- component-version: Component Version |
| 105 | +- component-repository: Component Repository |
| 106 | +- component-license: Component License |
| 107 | +- component-type: ephemeral or interactive. |
| 108 | +- component-description: Description |
| 109 | +- tags: |
| 110 | + - tag1 |
| 111 | + - tag2 |
| 112 | + |
| 113 | +# Information about the tool |
| 114 | +- tool-name: Tool name |
| 115 | +- tool-author: Tool's author |
| 116 | +- tool-version: Tool version |
| 117 | +- tool-repository: Tool's repository |
| 118 | +- tool-license: Tool's license |
| 119 | + |
| 120 | +# If aplicable, ports exposed by the component |
| 121 | +- ports: |
| 122 | + - XXXX |
| 123 | + |
| 124 | +# If aplicable, parameters exposed by the component |
| 125 | +# Add compatible datatype: str, int or float |
| 126 | +- parameters: |
| 127 | + - PARAMETER A: datatype |
| 128 | + |
| 129 | +# If aplicable, data-input list required by the component |
| 130 | +- data-inputs: |
| 131 | + - data |
| 132 | + - cache |
| 133 | + |
| 134 | +# If aplicable, data-output list produced by the component |
| 135 | +- data-output: |
| 136 | + - output |
| 137 | + |
| 138 | +# If aplicable, data-output list produced by the component. |
| 139 | +# Temporally unavaible. |
| 140 | +- inputSchema: PATH_TO_INPUT_SCHEMA |
| 141 | +- outputSchema: PATH_TO_INPUT_SCHEMA |
| 142 | + |
| 143 | +# If aplicable, define devices needed such as gpus. |
| 144 | +- devices: |
| 145 | + - gpus: False |
56 | 146 | ``` |
57 | 147 |
|
58 | 148 | ## Changelog |
59 | 149 |
|
60 | | -- v.0.2.0 |
61 | | - - Compatible with ODTP v.0.2.0 only with platform / components |
62 | | - - Compatible with configuration text files |
63 | | - - Improved loging system |
64 | | - - Accepting Digital Twins, Executions, and steps, metadata. |
65 | | - - Including component versioning in `odtp.yml` |
| 150 | +- v0.3.0 |
| 151 | + - Turning `odtp-client` into a separate repository and adding it as a submodule in `odtp-component-client` |
| 152 | + - Updating `app.sh` and tutorial. |
| 153 | + - Updating `odtp.yml` file. |
| 154 | + |
| 155 | +- v0.2.0 |
| 156 | + - Compatible with ODTP v.0.2.0 only with platform / components |
| 157 | + - Compatible with configuration text files |
| 158 | + - Improved loging system |
| 159 | + - Accepting Digital Twins, Executions, and steps, metadata. |
| 160 | + - Including component versioning in `odtp.yml` |
66 | 161 |
|
67 | | -- v.0.1.0 |
68 | | - - Compatible with ODTP v.0.1.0 only with platform / components |
69 | | - - Compatible with configuration text files |
| 162 | +- v0.1.0 |
| 163 | + - Compatible with ODTP v.0.1.0 only with platform / components |
| 164 | + - Compatible with configuration text files |
| 165 | + |
| 166 | +## Acknowledgments, Copyright, and Licensing |
| 167 | + |
| 168 | +### Acknowledgments and Funding |
70 | 169 |
|
71 | | -# Acknowledgments, Copyright, and Licensing |
72 | | -## Acknowledgments and Funding |
73 | 170 | This work is part of the broader project **O**pen **D**igital **T**win **P**latform of the **S**wiss **M**obility **S**ystem (ODTP-SMS) funded by Swissuniversities CHORD grant Track B - Establish Projects. ODTP-SMS project is a joint endeavour by the Center for Sustainable Future Mobility - CSFM (ETH Zürich) and the Swiss Data Science Center - SDSC (EPFL and ETH Zürich). |
74 | 171 | The Swiss Data Science Center (SDSC) develops domain-agnostic standards and containerized components to manage digital twins. This includes the creation of the Core Platform (both back-end and front-end), Service Component Integration Templates, Component Ontology, and the Component Zoo template. |
75 | 172 | The Center for Sustainable Future Mobility (CSFM) develops mobility services and utilizes the components produced by SDSC to deploy a mobility digital twin platform. CSFM focuses on integrating mobility services and collecting available components in the mobility zoo, thereby applying the digital twin concept in the realm of mobility. |
76 | 173 |
|
77 | | -## Copyright |
| 174 | +### Copyright |
| 175 | + |
78 | 176 | Copyright © 2023-2024 Swiss Data Science Center (SDSC), www.datascience.ch. All rights reserved. |
79 | 177 | The SDSC is jointly established and legally represented by the École Polytechnique Fédérale de Lausanne (EPFL) and the Eidgenössische Technische Hochschule Zürich (ETH Zürich). This copyright encompasses all materials, software, documentation, and other content created and developed by the SDSC. |
80 | 178 |
|
81 | | -## Intellectual Property (IP) Rights |
| 179 | +### Intellectual Property (IP) Rights |
| 180 | + |
82 | 181 | The Open Digital Twin Platform (ODTP) is the result of a collaborative effort between ETH Zurich (ETHZ) and the École Polytechnique Fédérale de Lausanne (EPFL). Both institutions hold equal intellectual property rights for the ODTP project, reflecting the equitable and shared contributions of EPFL and ETH Zürich in the development and advancement of this initiative. |
83 | 182 |
|
84 | | -## Licensing |
| 183 | +### Licensing |
| 184 | + |
85 | 185 | The Service Component Integration Templates within this repository are licensed under the BSD 3-Clause "New" or "Revised" License. This license allows for broad compatibility and standardization, encouraging open use and contribution. For the full license text, please see the LICENSE file accompanying these templates. |
86 | 186 |
|
87 | | -### Distinct Licensing for Other Components |
| 187 | +#### Distinct Licensing for Other Components |
| 188 | + |
88 | 189 | - **Core Platform**: Open-source under AGPLv3. |
89 | 190 | - **Ontology**: Creative Commons Attribution-ShareAlike (CC BY-SA). |
90 | 191 | - **Component Zoo Template**: BSD-3 license. |
91 | 192 |
|
92 | 193 | ### Alternative Commercial Licensing |
| 194 | + |
93 | 195 | Alternative commercial licensing options for the core platform and other components are available and can be negotiated through the EPFL Technology Transfer Office (https://tto.epfl.ch) or ETH Zürich Technology Transfer Office (https://ethz.ch/en/industry/transfer.html). |
94 | 196 |
|
95 | 197 | ## Ethical Use and Legal Compliance Disclaimer |
| 198 | + |
96 | 199 | Please note that this software should not be used to deliberately harm any individual or entity. Users and developers must adhere to ethical guidelines and use the software responsibly and legally. This disclaimer serves to remind all parties involved in the use or development of this software to engage in practices that are ethical, lawful, and in accordance with the intended purpose of the software. |
0 commit comments