diff --git a/.idea/codeStyles/codeStyleConfig.xml b/.idea/codeStyles/codeStyleConfig.xml index bfffe9c33f..480f7cb42e 100644 --- a/.idea/codeStyles/codeStyleConfig.xml +++ b/.idea/codeStyles/codeStyleConfig.xml @@ -1,5 +1,6 @@ + \ No newline at end of file diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 0000000000..1417f0a54b --- /dev/null +++ b/.readthedocs.yml @@ -0,0 +1,6 @@ +build: + image: latest + +python: + version: 3.7 + requirements_file: docs/requirements.txt diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000000..40735824e2 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,2 @@ +.vscode +_build diff --git a/docs/DeveloperGuide.html b/docs/DeveloperGuide.html deleted file mode 100644 index 6e22862633..0000000000 --- a/docs/DeveloperGuide.html +++ /dev/null @@ -1,28 +0,0 @@ - - - - - - - - Page Redirection - - -If you are not redirected automatically, follow http://eclipse.github.io/winery/dev/ -to reach the developer guide of Eclipse Winery™. - - diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000000..f28067fa74 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,31 @@ +# Copyright (c) 2020 Contributors to the Eclipse Foundation +# +# See the NOTICE file(s) distributed with this work for additional +# information regarding copyright ownership. +# +# This program and the accompanying materials are made available under the +# terms of the Eclipse Public License 2.0 which is available at +# http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0 +# which is available at https://www.apache.org/licenses/LICENSE-2.0. +# +# SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 + +# Minimal makefile for Sphinx documentation + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000000..06262e7faa --- /dev/null +++ b/docs/README.md @@ -0,0 +1,23 @@ + + + +# Eclipse Winery Documentation + +## Build + +``` +pip install -r requirements.txt +make.bat html +``` diff --git a/docs/SUPPORT.md b/docs/SUPPORT.md deleted file mode 100644 index dd03e7b7d8..0000000000 --- a/docs/SUPPORT.md +++ /dev/null @@ -1,7 +0,0 @@ -# Getting support of Eclipse Winery - -In case you have concrete issues, please open an issue at https://github.com/eclipse/winery/issues. - -There is a mailing list available at https://dev.eclipse.org/mailman/listinfo/winery-dev. - -General information about Eclipse Winery is available at https://eclipse.org/winery/. diff --git a/docs/ToolChain.html b/docs/ToolChain.html deleted file mode 100644 index 3a38716d2a..0000000000 --- a/docs/ToolChain.html +++ /dev/null @@ -1,28 +0,0 @@ - - - - - - - - Page Redirection - - -If you are not redirected automatically, follow http://eclipse.github.io/winery/dev/ToolChain -to reach the toolchain guide of Eclipse Winery™. - - diff --git a/docs/UserGuide.html b/docs/UserGuide.html deleted file mode 100644 index 7a6a2dcc04..0000000000 --- a/docs/UserGuide.html +++ /dev/null @@ -1,28 +0,0 @@ - - - - - - - - Page Redirection - - -If you are not redirected automatically, follow http://eclipse.github.io/winery/user/ -to reach the user guide of Eclipse Winery™. - - diff --git a/docs/tosca/yaml/Converter.md b/docs/_legacy/Converter.md similarity index 100% rename from docs/tosca/yaml/Converter.md rename to docs/_legacy/Converter.md diff --git a/docs/user/CrawlerAndComponentExtractionForChefCookbooks.md b/docs/_legacy/CrawlerAndComponentExtractionForChefCookbooks.md similarity index 100% rename from docs/user/CrawlerAndComponentExtractionForChefCookbooks.md rename to docs/_legacy/CrawlerAndComponentExtractionForChefCookbooks.md diff --git a/docs/user/DASpecification.md b/docs/_legacy/DASpecification.md similarity index 100% rename from docs/user/DASpecification.md rename to docs/_legacy/DASpecification.md diff --git a/docs/user/DeployableComponentsUsage.md b/docs/_legacy/DeployableComponentsUsage.md similarity index 100% rename from docs/user/DeployableComponentsUsage.md rename to docs/_legacy/DeployableComponentsUsage.md diff --git a/docs/tosca/yaml/ModelChangesAndExtensions.md b/docs/_legacy/ModelChangesAndExtensions.md similarity index 100% rename from docs/tosca/yaml/ModelChangesAndExtensions.md rename to docs/_legacy/ModelChangesAndExtensions.md diff --git a/docs/dev/TOSCA-Management.md b/docs/_legacy/TOSCA-Management.md similarity index 97% rename from docs/dev/TOSCA-Management.md rename to docs/_legacy/TOSCA-Management.md index adad27337b..b021b26b15 100644 --- a/docs/dev/TOSCA-Management.md +++ b/docs/_legacy/TOSCA-Management.md @@ -8,7 +8,7 @@ system, this structure is also present in the angular app. Entry into the angular app is the `WineryRepositoryComponent`. It contains the standard header and the router outlet. All main routes are configured in the `WineryRepositoryRoutingModule` which is bootstrapped in the `WineryRepositoryModule`. -![Angular Component Diagram](graphics/repositoryUiAngularComponentDiagram.png) +![Angular Component Diagram](figures/repositoryUiAngularComponentDiagram.png) [source](repositoryUiAngularComponentDiagram.plantuml) ### Main Routes diff --git a/docs/_config.yml b/docs/_legacy/_config.yml similarity index 100% rename from docs/_config.yml rename to docs/_legacy/_config.yml diff --git a/docs/dev/howtos/howto-angular.md b/docs/_legacy/angular.md similarity index 74% rename from docs/dev/howtos/howto-angular.md rename to docs/_legacy/angular.md index 3b66bb23b4..9bffccc0e7 100644 --- a/docs/dev/howtos/howto-angular.md +++ b/docs/_legacy/angular.md @@ -1,28 +1,21 @@ -# Eclipse Winery Angular Apps +# Winery's Angular Apps -TODO: generisch für beide apps - -## Prerequisites -1. Install [git](https://git-scm.com) -2. Install and setup [Node.js](https://nodejs.org/en/) and [NPM](https://www.npmjs.com) which ships with Node.js -3. **optional** Install the [Angular-CLI](https://cli.angular.io) globally. - -### Backend +## Backend The frontend assumes that the backend server is running on - the same host, - the same protocol, - the same port - and is reachable under the context `/winery`. -#### Development If the frontend runs via npm on the development ports, the backend MUST be running at port `8080`. An example request to the backend, if it runs locally, looks like this: `http://localhost:8080/winery/servicetemplates`. -### Topologymodeler -During development, the repository UI depends on the development version of the topologymodeler. Therefore, -you need to have both angular apps running with the local development server outlined below. +## Topology Modeler + +During development, the repository UI depends on the development version of the topologymodeler. +Therefore, you need to have both angular apps running with the local development server outlined below. Otherwise, the repository UI assumes that the topologymodeler runs on - the same host, @@ -92,21 +85,3 @@ You can also set up a IntelliJ run configuration as outlined above. Instead of c ## Generate war files Execute `mvn package`. - -## Development Hints -- [Exiting a for-each loop early](https://stackoverflow.com/a/2641374/6592788) - - -## License - -Copyright (c) 2017 Contributors to the Eclipse Foundation - -See the NOTICE file(s) distributed with this work for additional -information regarding copyright ownership. - -This program and the accompanying materials are made available under the -terms of the Eclipse Public License 2.0 which is available at -http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0 -which is available at https://www.apache.org/licenses/LICENSE-2.0. - -SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 diff --git a/docs/dev/building.md b/docs/_legacy/building.md similarity index 100% rename from docs/dev/building.md rename to docs/_legacy/building.md diff --git a/docs/dev/howtos/howto-repository.md b/docs/_legacy/howto-repository.md similarity index 97% rename from docs/dev/howtos/howto-repository.md rename to docs/_legacy/howto-repository.md index 17e17b02aa..7c4275bbc4 100644 --- a/docs/dev/howtos/howto-repository.md +++ b/docs/_legacy/howto-repository.md @@ -1,6 +1,6 @@ ## Working with the Repository -![Repository Interfaces Inheritance](graphics/InheritanceOfInterfacesRelatedToTheRepository.png) +![Repository Interfaces Inheritance](figures/InheritanceOfInterfacesRelatedToTheRepository.png) The general idea is to seperate the repository and the repository client. The repository itself is only accessed through the REST resources offered by `org.eclipse.winery.repository.rest`. diff --git a/docs/dev/howtos/howto-test-repository.md b/docs/_legacy/howto-test-repository.md similarity index 100% rename from docs/dev/howtos/howto-test-repository.md rename to docs/_legacy/howto-test-repository.md diff --git a/docs/user/graphics/modeling/3-AddNewNodeType.PNG b/docs/_legacy/modeling/3-AddNewNodeType.PNG similarity index 100% rename from docs/user/graphics/modeling/3-AddNewNodeType.PNG rename to docs/_legacy/modeling/3-AddNewNodeType.PNG diff --git a/docs/user/graphics/modeling/4-AddNewNodeType.PNG b/docs/_legacy/modeling/4-AddNewNodeType.PNG similarity index 100% rename from docs/user/graphics/modeling/4-AddNewNodeType.PNG rename to docs/_legacy/modeling/4-AddNewNodeType.PNG diff --git a/docs/user/graphics/modeling/5-AddNewNodeType-AddInterface.PNG b/docs/_legacy/modeling/5-AddNewNodeType-AddInterface.PNG similarity index 100% rename from docs/user/graphics/modeling/5-AddNewNodeType-AddInterface.PNG rename to docs/_legacy/modeling/5-AddNewNodeType-AddInterface.PNG diff --git a/docs/user/graphics/modeling/6-AddNewNodeType-AddInterface.PNG b/docs/_legacy/modeling/6-AddNewNodeType-AddInterface.PNG similarity index 100% rename from docs/user/graphics/modeling/6-AddNewNodeType-AddInterface.PNG rename to docs/_legacy/modeling/6-AddNewNodeType-AddInterface.PNG diff --git a/docs/dev/graphics/repositoryUiAngularComponentDiagram.plantuml b/docs/_legacy/repositoryUiAngularComponentDiagram.plantuml similarity index 100% rename from docs/dev/graphics/repositoryUiAngularComponentDiagram.plantuml rename to docs/_legacy/repositoryUiAngularComponentDiagram.plantuml diff --git a/docs/dev/graphics/repositoryUiAngularComponentDiagram.png b/docs/_legacy/repositoryUiAngularComponentDiagram.png similarity index 100% rename from docs/dev/graphics/repositoryUiAngularComponentDiagram.png rename to docs/_legacy/repositoryUiAngularComponentDiagram.png diff --git a/docs/user/TopologyCompletionTutorial.md b/docs/_legacy/topology-completion-tutorial.md similarity index 100% rename from docs/user/TopologyCompletionTutorial.md rename to docs/_legacy/topology-completion-tutorial.md diff --git a/docs/dev/troubleshootings.md b/docs/_legacy/troubleshootings.md similarity index 100% rename from docs/dev/troubleshootings.md rename to docs/_legacy/troubleshootings.md diff --git a/docs/user/graphics/completion/tutorial/Example_Topology_TC_1.png b/docs/_legacy/tutorial/Example_Topology_TC_1.png similarity index 100% rename from docs/user/graphics/completion/tutorial/Example_Topology_TC_1.png rename to docs/_legacy/tutorial/Example_Topology_TC_1.png diff --git a/docs/user/graphics/completion/tutorial/Example_Topology_TC_2.png b/docs/_legacy/tutorial/Example_Topology_TC_2.png similarity index 100% rename from docs/user/graphics/completion/tutorial/Example_Topology_TC_2.png rename to docs/_legacy/tutorial/Example_Topology_TC_2.png diff --git a/docs/user/graphics/completion/tutorial/Import_Repo.png b/docs/_legacy/tutorial/Import_Repo.png similarity index 100% rename from docs/user/graphics/completion/tutorial/Import_Repo.png rename to docs/_legacy/tutorial/Import_Repo.png diff --git a/docs/user/graphics/completion/tutorial/NodeType_Overview.png b/docs/_legacy/tutorial/NodeType_Overview.png similarity index 100% rename from docs/user/graphics/completion/tutorial/NodeType_Overview.png rename to docs/_legacy/tutorial/NodeType_Overview.png diff --git a/docs/user/graphics/completion/tutorial/Open_Topology_Modeler.png b/docs/_legacy/tutorial/Open_Topology_Modeler.png similarity index 100% rename from docs/user/graphics/completion/tutorial/Open_Topology_Modeler.png rename to docs/_legacy/tutorial/Open_Topology_Modeler.png diff --git a/docs/user/graphics/completion/tutorial/Requirement_Types_Overview.png b/docs/_legacy/tutorial/Requirement_Types_Overview.png similarity index 100% rename from docs/user/graphics/completion/tutorial/Requirement_Types_Overview.png rename to docs/_legacy/tutorial/Requirement_Types_Overview.png diff --git a/docs/user/graphics/completion/tutorial/Tc_dialog_example.png b/docs/_legacy/tutorial/Tc_dialog_example.png similarity index 100% rename from docs/user/graphics/completion/tutorial/Tc_dialog_example.png rename to docs/_legacy/tutorial/Tc_dialog_example.png diff --git a/docs/user/graphics/completion/tutorial/Tc_step_by_step.png b/docs/_legacy/tutorial/Tc_step_by_step.png similarity index 100% rename from docs/user/graphics/completion/tutorial/Tc_step_by_step.png rename to docs/_legacy/tutorial/Tc_step_by_step.png diff --git a/docs/_static/.gitkeep b/docs/_static/.gitkeep new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/adr/0002-filesystem-folder-structure-using-type-namespace-id-structure.md b/docs/adr/0002-filesystem-folder-structure-using-type-namespace-id-structure.md index 5bc1a98d03..c3be26217d 100644 --- a/docs/adr/0002-filesystem-folder-structure-using-type-namespace-id-structure.md +++ b/docs/adr/0002-filesystem-folder-structure-using-type-namespace-id-structure.md @@ -1,6 +1,6 @@ # File system folder structure using type-namespace-id structure -Winery's data is stored in a a file system [ADR-0001](0001-use-filesystem-as-backend). +Winery's data is stored in a a file system [ADR-0001](0001-use-filesystem-as-backend.md). The contents of the repository should be - human readable @@ -15,7 +15,7 @@ The contents of the repository should be *Chosen Alternative: Folders subdivided in type-namespace-id* -The final file system layout itself is documented at [RepositoryLayout](../dev/RepositoryLayout). +The final file system layout itself is documented at [RepositoryLayout](../dev/repository-layout.md). ### human readable diff --git a/docs/adr/0003-double-encoded-urls.md b/docs/adr/0003-double-encoded-urls.md index 2ff692d189..94cae922e9 100644 --- a/docs/adr/0003-double-encoded-urls.md +++ b/docs/adr/0003-double-encoded-urls.md @@ -3,7 +3,7 @@ URLs should be human-readable, slashes are not allowed. Encoded slahes are not enabled as default due to security reasons. -More information about encoding is available at [dev/Encoding.md](dev/Encoding). +More information about encoding is available at [dev/Encoding.md](../dev/encoding.md). ## Considered Alternatives diff --git a/docs/adr/0015-copy-source-to-files.md b/docs/adr/0015-copy-source-to-files.md index b5a8ff3f5c..7e98cafb15 100644 --- a/docs/adr/0015-copy-source-to-files.md +++ b/docs/adr/0015-copy-source-to-files.md @@ -31,4 +31,4 @@ Forces: * `-` Needs a runtime/compiler * `-` See [ADR-0014] - [ADR-0014]: (0014-use-eclipse-orion-as-editor.md) +[ADR-0014]: 0014-use-eclipse-orion-as-editor.md diff --git a/docs/adr/index.md b/docs/adr/index.md index 3815c8e907..ce5e782015 100644 --- a/docs/adr/index.md +++ b/docs/adr/index.md @@ -1,3 +1,18 @@ + + + # Architectural Decision Log This lists the architectural decisions for Eclipse Winery. @@ -38,5 +53,5 @@ This lists the architectural decisions for Eclipse Winery. -[template.md](template.md) contains the template. +The [template.md](template.md) contains the MADR template. More information on MADR is available at . diff --git a/docs/adr/template.md b/docs/adr/template.md index 5d62057a76..b3a56ff3ef 100644 --- a/docs/adr/template.md +++ b/docs/adr/template.md @@ -1,6 +1,21 @@ + + + # [short title of solved problem and solution] -* Status: [accepted | superseeded by [ADR-0005](0005-example.md) | deprecated | …] +* Status: [accepted | superseeded by [ADR-0000](0000-use-architectural-decision-records.md) | deprecated | ...] * Deciders: [list everyone involved in the decision] * Date: [YYYY-MM-DD when the decision was last updated] @@ -12,75 +27,61 @@ Technical Story: [description | ticket/issue URL] ## Decision Drivers -* [driver 1, e.g., a force, facing concern, …] -* [driver 2, e.g., a force, facing concern, …] -* … +* [driver 1, e.g., a force, facing concern, ...] +* [driver 2, e.g., a force, facing concern, ...] +* ... ## Considered Options * [option 1] * [option 2] * [option 3] -* … +* ... ## Decision Outcome -Chosen option: "[option 1]", because [justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force force | … | comes out best (see below)]. +Chosen option: "[option 1]", because [justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force force | ... | comes out best (see below)]. ### Positive Consequences -* [e.g., improvement of quality attribute satisfaction, follow-up decisions required, …] -* … +* [e.g., improvement of quality attribute satisfaction, follow-up decisions required, ...] +* ... ### Negative consequences -* [e.g., compromising quality attribute, follow-up decisions required, …] -* … +* [e.g., compromising quality attribute, follow-up decisions required, ...] +* ... ## Pros and Cons of the Options ### [option 1] -[example | description | pointer to more information | …] +[example | description | pointer to more information | ...] * Good, because [argument a] * Good, because [argument b] * Bad, because [argument c] -* … +* ... ### [option 2] -[example | description | pointer to more information | …] +[example | description | pointer to more information | ...] * Good, because [argument a] * Good, because [argument b] * Bad, because [argument c] -* … +* ... ### [option 3] -[example | description | pointer to more information | …] +[example | description | pointer to more information | ...] * Good, because [argument a] * Good, because [argument b] * Bad, because [argument c] -* … +* ... ## Links * [Link type] [Link to ADR] -* … - -## License - -Copyright (c) 2018 Contributors to the Eclipse Foundation - -See the NOTICE file(s) distributed with this work for additional -information regarding copyright ownership. - -This program and the accompanying materials are made available under the -terms of the Eclipse Public License 2.0 which is available at -http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0 -which is available at https://www.apache.org/licenses/LICENSE-2.0. - -SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 +* ... diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000000..80c4d2d127 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,82 @@ +# Copyright (c) 2020 Contributors to the Eclipse Foundation +# +# See the NOTICE file(s) distributed with this work for additional +# information regarding copyright ownership. +# +# This program and the accompanying materials are made available under the +# terms of the Eclipse Public License 2.0 which is available at +# http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0 +# which is available at https://www.apache.org/licenses/LICENSE-2.0. +# +# SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 + +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +import datetime +from recommonmark.parser import CommonMarkParser +from recommonmark.transform import AutoStructify + +now = datetime.datetime.now() + +# -- Project information ----------------------------------------------------- + +project = 'Eclipse Winery' +copyright = '(c) 2013-{} Contributors to the Eclipse Foundation.'.format(now.year) +author = 'Contributors to the Eclipse Foundation' + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx_markdown_tables', + 'recommonmark', + 'sphinx.ext.autosectionlabel', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = [] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '_legacy', 'README.md'] + +source_parsers = { + '.md': CommonMarkParser, +} + +source_suffix = ['.rst', '.md'] + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'sphinx_rtd_theme' + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + + +def setup(app): + app.add_config_value('recommonmark_config', { + 'auto_toc_tree': False, + 'enable_eval_rst': True, + 'enable_math': True, + 'enable_inline_math': True, + }, True) + app.add_transform(AutoStructify) diff --git a/docs/dev/config/Eclipse/cleanup.xml b/docs/config/Eclipse/cleanup.xml similarity index 100% rename from docs/dev/config/Eclipse/cleanup.xml rename to docs/config/Eclipse/cleanup.xml diff --git a/docs/dev/config/Eclipse/codetemplates.xml b/docs/config/Eclipse/codetemplates.xml similarity index 100% rename from docs/dev/config/Eclipse/codetemplates.xml rename to docs/config/Eclipse/codetemplates.xml diff --git a/docs/dev/config/Eclipse/eclipse_save_actions.png b/docs/config/Eclipse/figures/eclipse_save_actions.png similarity index 100% rename from docs/dev/config/Eclipse/eclipse_save_actions.png rename to docs/config/Eclipse/figures/eclipse_save_actions.png diff --git a/docs/dev/config/Eclipse/eclipse_save_actions_1_code_organizing.png b/docs/config/Eclipse/figures/eclipse_save_actions_1_code_organizing.png similarity index 100% rename from docs/dev/config/Eclipse/eclipse_save_actions_1_code_organizing.png rename to docs/config/Eclipse/figures/eclipse_save_actions_1_code_organizing.png diff --git a/docs/dev/config/Eclipse/eclipse_save_actions_2_code_style.png b/docs/config/Eclipse/figures/eclipse_save_actions_2_code_style.png similarity index 100% rename from docs/dev/config/Eclipse/eclipse_save_actions_2_code_style.png rename to docs/config/Eclipse/figures/eclipse_save_actions_2_code_style.png diff --git a/docs/dev/config/Eclipse/eclipse_save_actions_3_member_accesses.png b/docs/config/Eclipse/figures/eclipse_save_actions_3_member_accesses.png similarity index 100% rename from docs/dev/config/Eclipse/eclipse_save_actions_3_member_accesses.png rename to docs/config/Eclipse/figures/eclipse_save_actions_3_member_accesses.png diff --git a/docs/dev/config/Eclipse/eclipse_save_actions_4_missing_code.png b/docs/config/Eclipse/figures/eclipse_save_actions_4_missing_code.png similarity index 100% rename from docs/dev/config/Eclipse/eclipse_save_actions_4_missing_code.png rename to docs/config/Eclipse/figures/eclipse_save_actions_4_missing_code.png diff --git a/docs/dev/config/Eclipse/eclipse_save_actions_5_unnecessary_code.png b/docs/config/Eclipse/figures/eclipse_save_actions_5_unnecessary_code.png similarity index 100% rename from docs/dev/config/Eclipse/eclipse_save_actions_5_unnecessary_code.png rename to docs/config/Eclipse/figures/eclipse_save_actions_5_unnecessary_code.png diff --git a/docs/dev/config/Eclipse/formatter_settings.xml b/docs/config/Eclipse/formatter_settings.xml similarity index 100% rename from docs/dev/config/Eclipse/formatter_settings.xml rename to docs/config/Eclipse/formatter_settings.xml diff --git a/docs/dev/config/Eclipse/README.md b/docs/config/Eclipse/index.md similarity index 69% rename from docs/dev/config/Eclipse/README.md rename to docs/config/Eclipse/index.md index b8f24390ad..dd12a7c727 100644 --- a/docs/dev/config/Eclipse/README.md +++ b/docs/config/Eclipse/index.md @@ -1,3 +1,18 @@ + + + # Eclipse Configuration HowTo We have issues with removing trailing spaces at Eclipse. @@ -48,28 +63,14 @@ Java -> Editor -> Templates: java_editor_templates.xml Save Actions: follow eclipse_save_actions*.png: -![eclipse_save_actions.png](eclipse_save_actions.png) -![eclipse_save_actions_1_code_organizing.png](eclipse_save_actions_1_code_organizing.png) -![eclipse_save_actions_2_code_style.png](eclipse_save_actions_2_code_style.png) -![eclipse_save_actions_3_member_accesses.png](eclipse_save_actions_3_member_accesses.png) -![eclipse_save_actions_4_missing_code.png](eclipse_save_actions_4_missing_code.png) -![eclipse_save_actions_5_unnecessary_code.png](eclipse_save_actions_5_unnecessary_code.png) +![](figures/eclipse_save_actions.png) +![](figures/eclipse_save_actions_1_code_organizing.png) +![](figures/eclipse_save_actions_2_code_style.png) +![](figures/eclipse_save_actions_3_member_accesses.png) +![](figures/eclipse_save_actions_4_missing_code.png) +![](figures/eclipse_save_actions_5_unnecessary_code.png) ## Further hints The repository location can be changed: Copy `winery.properties` to `path-to-workspace\.metadata\.plugins\org.eclipse.wst.server.core\tmp0\wtpwebapps\winery`. - -## License - -Copyright (c) 2012-2017 Contributors to the Eclipse Foundation - -See the NOTICE file(s) distributed with this work for additional -information regarding copyright ownership. - -This program and the accompanying materials are made available under the -terms of the Eclipse Public License 2.0 which is available at -http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0 -which is available at https://www.apache.org/licenses/LICENSE-2.0. - -SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 diff --git a/docs/dev/config/Eclipse/java_editor_templates.xml b/docs/config/Eclipse/java_editor_templates.xml similarity index 100% rename from docs/dev/config/Eclipse/java_editor_templates.xml rename to docs/config/Eclipse/java_editor_templates.xml diff --git a/docs/dev/config/IntelliJ IDEA/UpdateCopyrightHeaders.md b/docs/config/IntelliJ IDEA/copyright-header.md similarity index 63% rename from docs/dev/config/IntelliJ IDEA/UpdateCopyrightHeaders.md rename to docs/config/IntelliJ IDEA/copyright-header.md index 3463dde211..53ce4eac88 100644 --- a/docs/dev/config/IntelliJ IDEA/UpdateCopyrightHeaders.md +++ b/docs/config/IntelliJ IDEA/copyright-header.md @@ -1,39 +1,25 @@ -## Update copyright header +# Update Copyright Header Steps to update copyright headers: 1. Define scopes to apply the copy right header to: - Open properties Ctrl Alt S and search for `Scopes` - Select packages for the scope and click `Include Recursively` - ![GitAutoCheck](graphics/SetScopes.png) + ![](figures/SetScopes.png) 2. Apply copyright settings to Scope: - Open properties `ctrl alt s` and search for `Copyright` - Add copyright entry and apply previously created scope - ![GitAutoCheck](graphics/Copyright.png) + ![](figures/Copyright.png) 3. Create copyright profile: - Open Settings/Editor/Copyright/'Copyright Profiles' - Add copyright text without borders - Set Copyright year dynamically with `${today.year}` - Add copyright regex (Acquired by selecting the copyright header in intellij editor and pressing `ctrl shift f`) - Allow replacing old copyright identified by regex seems not to work - ![GitAutoCheck](graphics/CopyrightProfiles.png) + ![](figures/CopyrightProfiles.png) 4. Adjust copyright formatting settings - Open Settings/Editor/Copyright/Formatting - Change to `Use block comments` with `Prefix each line`, set `Relative Location` to `Before other comments`and increase `Separator before/after Length` to `81` - ![GitAutoCheck](graphics/CopyrightFormat.png) + ![](figures/CopyrightFormat.png) 5. Delete previous copyright header manually (Replace with empty String) 6. Right click package and choose `Update Copyright..` - Check files for duplicated copyright header (occurs if copyright regex not set correctly) - -## License - -Copyright (c) 2017-2018 Contributors to the Eclipse Foundation - -See the NOTICE file(s) distributed with this work for additional -information regarding copyright ownership. - -This program and the accompanying materials are made available under the -terms of the Eclipse Public License 2.0 which is available at -http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0 -which is available at https://www.apache.org/licenses/LICENSE-2.0. - -SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 diff --git a/docs/dev/config/IntelliJ IDEA/graphics/Copyright.png b/docs/config/IntelliJ IDEA/figures/Copyright.png similarity index 100% rename from docs/dev/config/IntelliJ IDEA/graphics/Copyright.png rename to docs/config/IntelliJ IDEA/figures/Copyright.png diff --git a/docs/dev/config/IntelliJ IDEA/graphics/CopyrightFormat.png b/docs/config/IntelliJ IDEA/figures/CopyrightFormat.png similarity index 100% rename from docs/dev/config/IntelliJ IDEA/graphics/CopyrightFormat.png rename to docs/config/IntelliJ IDEA/figures/CopyrightFormat.png diff --git a/docs/dev/config/IntelliJ IDEA/graphics/CopyrightProfiles.png b/docs/config/IntelliJ IDEA/figures/CopyrightProfiles.png similarity index 100% rename from docs/dev/config/IntelliJ IDEA/graphics/CopyrightProfiles.png rename to docs/config/IntelliJ IDEA/figures/CopyrightProfiles.png diff --git a/docs/dev/config/IntelliJ IDEA/graphics/SetScopes.png b/docs/config/IntelliJ IDEA/figures/SetScopes.png similarity index 100% rename from docs/dev/config/IntelliJ IDEA/graphics/SetScopes.png rename to docs/config/IntelliJ IDEA/figures/SetScopes.png diff --git a/docs/dev/config/IntelliJ IDEA/graphics/activate-checkstyle.gif b/docs/config/IntelliJ IDEA/figures/activate-checkstyle.gif similarity index 100% rename from docs/dev/config/IntelliJ IDEA/graphics/activate-checkstyle.gif rename to docs/config/IntelliJ IDEA/figures/activate-checkstyle.gif diff --git a/docs/dev/config/IntelliJ IDEA/graphics/run-repositoryui-step1-add-npm-config.png b/docs/config/IntelliJ IDEA/figures/run-repositoryui-step1-add-npm-config.png similarity index 100% rename from docs/dev/config/IntelliJ IDEA/graphics/run-repositoryui-step1-add-npm-config.png rename to docs/config/IntelliJ IDEA/figures/run-repositoryui-step1-add-npm-config.png diff --git a/docs/dev/config/IntelliJ IDEA/graphics/run-repositoryui-step2-configure.png b/docs/config/IntelliJ IDEA/figures/run-repositoryui-step2-configure.png similarity index 100% rename from docs/dev/config/IntelliJ IDEA/graphics/run-repositoryui-step2-configure.png rename to docs/config/IntelliJ IDEA/figures/run-repositoryui-step2-configure.png diff --git a/docs/dev/config/IntelliJ IDEA/graphics/run-step1-edit-configuration.png b/docs/config/IntelliJ IDEA/figures/run-step1-edit-configuration.png similarity index 100% rename from docs/dev/config/IntelliJ IDEA/graphics/run-step1-edit-configuration.png rename to docs/config/IntelliJ IDEA/figures/run-step1-edit-configuration.png diff --git a/docs/dev/config/IntelliJ IDEA/graphics/run-step10-choose-artifact.png b/docs/config/IntelliJ IDEA/figures/run-step10-choose-artifact.png similarity index 100% rename from docs/dev/config/IntelliJ IDEA/graphics/run-step10-choose-artifact.png rename to docs/config/IntelliJ IDEA/figures/run-step10-choose-artifact.png diff --git a/docs/dev/config/IntelliJ IDEA/graphics/run-step11-select-artifcat.png b/docs/config/IntelliJ IDEA/figures/run-step11-select-artifcat.png similarity index 100% rename from docs/dev/config/IntelliJ IDEA/graphics/run-step11-select-artifcat.png rename to docs/config/IntelliJ IDEA/figures/run-step11-select-artifcat.png diff --git a/docs/dev/config/IntelliJ IDEA/graphics/run-step12-set-winery-as-application-context.png b/docs/config/IntelliJ IDEA/figures/run-step12-set-winery-as-application-context.png similarity index 100% rename from docs/dev/config/IntelliJ IDEA/graphics/run-step12-set-winery-as-application-context.png rename to docs/config/IntelliJ IDEA/figures/run-step12-set-winery-as-application-context.png diff --git a/docs/dev/config/IntelliJ IDEA/graphics/run-step2-add-new-configuration.png b/docs/config/IntelliJ IDEA/figures/run-step2-add-new-configuration.png similarity index 100% rename from docs/dev/config/IntelliJ IDEA/graphics/run-step2-add-new-configuration.png rename to docs/config/IntelliJ IDEA/figures/run-step2-add-new-configuration.png diff --git a/docs/dev/config/IntelliJ IDEA/graphics/run-step3-add-tomcat.png b/docs/config/IntelliJ IDEA/figures/run-step3-add-tomcat.png similarity index 100% rename from docs/dev/config/IntelliJ IDEA/graphics/run-step3-add-tomcat.png rename to docs/config/IntelliJ IDEA/figures/run-step3-add-tomcat.png diff --git a/docs/dev/config/IntelliJ IDEA/graphics/run-step4-configure-tomcat-button.png b/docs/config/IntelliJ IDEA/figures/run-step4-configure-tomcat-button.png similarity index 100% rename from docs/dev/config/IntelliJ IDEA/graphics/run-step4-configure-tomcat-button.png rename to docs/config/IntelliJ IDEA/figures/run-step4-configure-tomcat-button.png diff --git a/docs/dev/config/IntelliJ IDEA/graphics/run-step5-add-appserver-button.png b/docs/config/IntelliJ IDEA/figures/run-step5-add-appserver-button.png similarity index 100% rename from docs/dev/config/IntelliJ IDEA/graphics/run-step5-add-appserver-button.png rename to docs/config/IntelliJ IDEA/figures/run-step5-add-appserver-button.png diff --git a/docs/dev/config/IntelliJ IDEA/graphics/run-step6-set-apache-tomcat-directory.png b/docs/config/IntelliJ IDEA/figures/run-step6-set-apache-tomcat-directory.png similarity index 100% rename from docs/dev/config/IntelliJ IDEA/graphics/run-step6-set-apache-tomcat-directory.png rename to docs/config/IntelliJ IDEA/figures/run-step6-set-apache-tomcat-directory.png diff --git a/docs/dev/config/IntelliJ IDEA/graphics/run-step7-confirm.png b/docs/config/IntelliJ IDEA/figures/run-step7-confirm.png similarity index 100% rename from docs/dev/config/IntelliJ IDEA/graphics/run-step7-confirm.png rename to docs/config/IntelliJ IDEA/figures/run-step7-confirm.png diff --git a/docs/dev/config/IntelliJ IDEA/graphics/run-step8-name-and-no-browser.png b/docs/config/IntelliJ IDEA/figures/run-step8-name-and-no-browser.png similarity index 100% rename from docs/dev/config/IntelliJ IDEA/graphics/run-step8-name-and-no-browser.png rename to docs/config/IntelliJ IDEA/figures/run-step8-name-and-no-browser.png diff --git a/docs/dev/config/IntelliJ IDEA/graphics/run-step9-button-add-deployment-artifacts.png b/docs/config/IntelliJ IDEA/figures/run-step9-button-add-deployment-artifacts.png similarity index 100% rename from docs/dev/config/IntelliJ IDEA/graphics/run-step9-button-add-deployment-artifacts.png rename to docs/config/IntelliJ IDEA/figures/run-step9-button-add-deployment-artifacts.png diff --git a/docs/dev/config/IntelliJ IDEA/graphics/run-topologymodeler-step1-add-npm-config.png b/docs/config/IntelliJ IDEA/figures/run-topologymodeler-step1-add-npm-config.png similarity index 100% rename from docs/dev/config/IntelliJ IDEA/graphics/run-topologymodeler-step1-add-npm-config.png rename to docs/config/IntelliJ IDEA/figures/run-topologymodeler-step1-add-npm-config.png diff --git a/docs/dev/config/IntelliJ IDEA/graphics/run-topologymodeler-step2-configure.png b/docs/config/IntelliJ IDEA/figures/run-topologymodeler-step2-configure.png similarity index 100% rename from docs/dev/config/IntelliJ IDEA/graphics/run-topologymodeler-step2-configure.png rename to docs/config/IntelliJ IDEA/figures/run-topologymodeler-step2-configure.png diff --git a/docs/dev/config/IntelliJ IDEA/graphics/run-workflowmodeler-step2.png b/docs/config/IntelliJ IDEA/figures/run-workflowmodeler-step2.png similarity index 100% rename from docs/dev/config/IntelliJ IDEA/graphics/run-workflowmodeler-step2.png rename to docs/config/IntelliJ IDEA/figures/run-workflowmodeler-step2.png diff --git a/docs/dev/config/IntelliJ IDEA/idea64.exe.vmoptions b/docs/config/IntelliJ IDEA/idea64.exe.vmoptions similarity index 100% rename from docs/dev/config/IntelliJ IDEA/idea64.exe.vmoptions rename to docs/config/IntelliJ IDEA/idea64.exe.vmoptions diff --git a/docs/config/IntelliJ IDEA/index.md b/docs/config/IntelliJ IDEA/index.md new file mode 100644 index 0000000000..2e11539619 --- /dev/null +++ b/docs/config/IntelliJ IDEA/index.md @@ -0,0 +1,146 @@ + + + +# IntelliJ Configuration + +## Preparation: Install IntelliJ + +1. Get a JetBrains Ultimate License. For students: Visit . +1. Install [JetBrains Toolbox](https://www.jetbrains.com/toolbox/): `choco install jetbrainstoolbox` and `choco pin add -n jetbrainstoolbox`, because JetBrains does an auto update +1. Install "IntelliJ IDEA Ultimate" using the JetBrains Toolbox. + +## Preparation: Build Winery + +Build Winery to have all dependencies fetched by Maven: `mvn clean install -DskipTests`. + +## Setup IntelliJ + +1. At start of IntelliJ, browse to the root `pom.xml` and open it as project. +1. Enable checkstyle: Follow the shown steps and apply them in IntelliJ + ![](figures/activate-checkstyle.gif) + - Install the [IntelliJ Checkstyle Plugin](https://plugins.jetbrains.com/plugin/1065-checkstyle-idea). + It can be found via plug-in repository (Settings -> Plugins -> Browse repositories) + - Open the Settings (by pressing Ctrl + Alt + S) + - Go to Other Settings -> CheckStyle. + - Click on the green plus and add `checkstyle.xml` from the root of the Winery code repository. +1. Configure the code style + 1. Open the Settings (by pressing Ctrl + Alt + S) + 1. Go to "Editor > Code Style" + 1. Click "Manage..." (right of "Scheme:") + 1. Click "Import Scheme" + 1. Choose "IntelliJ IDEA code style XML" + 1. Navigate to `intellij-idea-code-style.xml`. It is located in `docs/config/IntelliJ IDEA`. + 1. Press "OK" + 1. You will see a message "Winery configuration settings were imported". + 1. Press "OK" + 1. Press "Close" + 1. Press "OK" +1. Setup code headers to be inserted automatically + 1. Open the Settings (by pressing Ctrl + Alt + S) + 1. Go to Editor > Copyright > Copyright Profiles + 1. Click the green plus + 1. Name "Winery" + 1. Copyright text from [Source Code Headers](../../dev/source-code-headers.md) + 1. Go to Editor > Copyright > Formatting + 1. Adjust copyright formatting settings + - Change to `Use block comments` with `Prefix each line` + - Set `Relative Location` to `Before other comments` + - Increase `Separator before/after Length` to `81` + - ![GitAutoCheck](figures/CopyrightFormat.png) + 1. Go to Editor > Copyright + 1. Set "Winery" as Default project copyright + 1. Press "OK" +1. Setup Apache Tomcat + 1. Download Tomcat 9.0 from . + Choose "zip" (e.g., ). + 1. Extract it to `c:\apache`. Result: `C:\apache\apache-tomcat-9.0.7`. + 1. ![](figures/run-step1-edit-configuration.png) + 1. ![](figures/run-step2-add-new-configuration.png) + 1. ![](figures/run-step3-add-tomcat.png) + 1. ![](figures/run-step4-configure-tomcat-button.png) + 1. ![](figures/run-step5-add-appserver-button.png.png) + 1. ![](figures/run-step6-set-apache-tomcat-directory.png) + 1. Press OK
+ ![](figures/run-step7-confirm.png) + 1. Set name and no browser launch:
+ ![](figures/run-step8-name-and-no-browser.png) + 1. Add deployment artifacts:
+ ![](figures/run-step9-button-add-deployment-artifacts.png) + 1. ![](figures/run-step10-choose-artifact.png) + 1. ![](figures/run-step11-select-artifcat.png) + 1. Set `/winery` as application context:
+ ![](figures/run-step12-set-winery-as-application-context.png) + 1. Click "Apply" +1. Setup npm run for TOSCA Management UI + 1. ![](figures/run-repositoryui-step1-add-npm-config.png) + 1. ![](figures/run-repositoryui-step2-configure.png) +1. Setup npm run for Topology Modeler + 1. ![](figures/run-topologymodeler-step1-add-npm-config.png) + 1. ![](figures/run-topologymodeler-step2-configure.png) +1. Setup npm run for Workflowmodeler (BPMN4TOSCA Modeler) + 1. ![](figures/run-topologymodeler-step1-add-npm-config.png) + 1. ![](figures/run-workflowmodeler-step2.png) +1. Optional: Setup XSD validation for TOSCA files + 1. Open the Settings (by pressing Ctrl + Alt + S) + 1. Go to "Languages & Frameworks" + 1. Select "Schemas and DTDs" + 1. Click on the plus on the right at "External Schemas and DTDs" + 1. Enter `http://docs.oasis-open.org/tosca/ns/2011/12` as URI + 1. In "Project Schemas" search for `TOSCA-v1.0.xsd`. + It should be located at "org.eclipse.winery.common". + In the case of opening `C:\winery-repository` in IntelliJ, you have to select enter `C:\git-repositories\winery\org.eclipse.winery.common\src\main\resources\TOSCA-v1.0.xsd` in the Field "File" + 1. Click "OK". + 1. Go to "Editor" + 1. Select "File Types" + 1. At "Recognized File Types", scroll down to XML + 1. Select "XML" + 1. At "Registered Patterns", click on the Plus + 1. Enter `*.tosca` in the popup. + 1. Click "OK" + 1. Click "OK" +1. Optional: In case you do not want to have the live-update of Angular, you build the WARs of the UI and then deploy as follows: + - External artifact `.../org.eclipse.winery.frontends/target/tosca-management.war` to `/` + - External artifact `.../org.eclipse.winery.frontends/target/topologymodeler.war` to `/winery-topology-modeler` + - External artifact `.../org.eclipse.winery.frontends/target/workflowmodeler.war` to `/winery-workflowmodeler` +1. Run everything + - Select "Winery - REST". Click on "Play" (the green rectangle) + - Select "TOSCA Mangement UI". Click on "Play" + - Select "Topolgoy Modeler". Click on "Play". + - Open in your browser. +1. Demonstration: Open winery-repository (AKA tosca-definitions) in IntelliJ + This ensures that you can work with the TOSCA files using the IDE. + 1. Go to File -> Open... + 1. Enter `c:\winery-repository` + 1. Click "OK" + 1. At the dialog "Open Project" choose "New Window" + 1. Expand `winery-repository` (on the left side) + 1. Expand `nodetypes` + 1. Expand `http%3A%2F%2Fplain.winery.opentosca.org%2Fnodetypes` + 1. Expand `NodeTypeWithTwoKVProperties` + 1. Double click `NodeType.tosca` + 1. Go to line 14 + 1. Type in `<` + 1. See that `Shift / Ctrl+Shift+F / Ctrl+F: Differrent forms of search + - Ctrl+Alt+L: Organize imports (fixes checkstyle) + - Ctrl+X: if nothing is marked: cut line (equal to marking whole line and using Ctrl+X) + - Ctrl+Shift+T: Create/jump to the test class +* See [Update Copyright Header](copyright-header.md) for updating old copyright headers diff --git a/docs/dev/config/IntelliJ IDEA/intellij-idea-code-style.xml b/docs/config/IntelliJ IDEA/intellij-idea-code-style.xml similarity index 100% rename from docs/dev/config/IntelliJ IDEA/intellij-idea-code-style.xml rename to docs/config/IntelliJ IDEA/intellij-idea-code-style.xml diff --git a/docs/dev/Configurationmanagment.md b/docs/dev/Configurationmanagment.md deleted file mode 100644 index 70c27f62b7..0000000000 --- a/docs/dev/Configurationmanagment.md +++ /dev/null @@ -1,97 +0,0 @@ -# Configurationmanagement - -All Components are implemented in the package `org.eclipse.winery.common.configuration`. -The configuration is YAML based and called "winery.yml". The default Configuration is contained in -the resource folder. - -## Adding new Features -To add a new feature to the configuration one has to simply add it hierarchically under the features tab in the winery.yml file. -This has to be done both in the winery.yml file in the filesystem and in the default configuration winery.yml file in the resources folder. - -```yaml -ui: - features: - splitting: true - completion: true - patternRefinement: true - compliance: true - accountability: true - nfv: true - endpoints: - container: http://localhost:1337 - workflowmodeler: http://localhost:8080/winery-workflowmodeler - topologymodeler: http://localhost:8080/winery-topologymodeler - repositoryApiUrl: http://localhost:8080/winery - repositoryUiUrl: http://localhost:8080/# -repository: - provider: file - repositoryRoot: "" - git: - clientSecret: secret - password: default - clientID: id - autocommit: false - username: default -``` -**Figure 1: Adding new feature to the YAML Configuration.** - -If the feature has been added to the YAML Configuration the ```getUiConfig()``` method of the Environments class will return a UiConfigurationObject Instance -which has the added feature as a map entry in the features map attribute. This can be accessed with the getFeatures() method. -The key of the feature entry is the same name that was added to the winery.yml file. - -## Accessing the configuration in the backend - -The configuration is split into different objects. The `UiConfigurationObject` -contains the feature flags and endpoints. -The `RepositoryConfigurationObject` contains all the repository settings including a -`GitConfigurationObject`. -The `GitConfigurationObject` contains all settings associated with Git. -Each of these configuration objects can be accessed through a getter in the -`Environments` class, e.g. `getGitConfig()`. -When the changes to a configuration object shall be persisted, the -`Environments` class offers a save method, in which the changed configuration object -has to be passed as the parameter. - -## Accessing the Configuration in the Frontend -In the `org.eclipse.winery.repository.rest.resources.admin.AdminTopResource.java` are two methods implemented which -are used to send the configuration to the frontend ```getConfig()``` and get updates to the configuration from the frontend ```setConfig()```. -In the frontend the `WineryRepositoryConfigurationService` manages those resources. Injecting the service where the configuration -is needed provides the configuration as the configuration attribute of the WineryRepositoryConfigurationService. Therefore the feature -has to be added as a boolean attribute to the WineryConfiguration interface. -```typescript -export interface WineryConfiguration { - features: { - splitting: boolean; - completion: boolean; - compliance: boolean; - patternRefinement: boolean; - accountability: boolean; - nfv: boolean; - }; - endpoints: { - container: String; - workflowmodeler: String; - topologymodeler: String; - }; -} -``` -**Figure 2: Adding new feature to the WineryConfiguration Interface.** - - -### Using feature toggles -The `FeatureToggleDirective` offers a way to use the configuration to toggle features on or off dynamically. -Before using the directive in any html file it has to be imported first into the corresponding module. Additionally an enum in the component where the feature toggle will be used has to be created and declared with the FeatureEnum. -```typescript -export enum FeatureEnum { - Splitting = 'splitting', Completion = 'completion', Compliance = 'compliance', - PatternRefinement = 'patternRefinement', Accountability = 'accountability', NFV = 'nfv', - newFeature = 'newFeature' -} -``` -**Figure 3: Adding new feature to the Enum.** - -Finally the directive can be used to toggle the feature according to the set configuration. -```html -
-``` -**Figure 4: Using the directive for the pattern refinement feature.** diff --git a/docs/dev/Encoding.md b/docs/dev/Encoding.md index fa0d7bceaf..59e0f0b8d1 100644 --- a/docs/dev/Encoding.md +++ b/docs/dev/Encoding.md @@ -1,4 +1,19 @@ -# Encoding of folder names, namespaces, and ids in Winery + + + +# Encoding of folder names, namespaces, and IDs in Winery **Outdated** Although the information about double-encoding is correct, the UI has been re-implemented using Angular, which introduces an additional layer of URLs. @@ -6,21 +21,22 @@ In file systems, characters `/` and `:` are not allowed [source](https://stackoverflow.com/a/31976060/873282). The [design decision](../adr/0002-filesystem-folder-structure-using-type-namespace-id-structure.md) is that all files (node types, imports in CSARs, ...) are stored and structured using directories with human readable names. -Therefore, the namespace URI must be used in a encoded form, otherwise the name would not be valid (`http://www...`). +Therefore, the namespace URI must be used in an encoded form, otherwise the name would not be valid (`http://www...`). An example for such a directory name is `http%3A%2F%2Fwww.w3.org%2F2001%2FXMLSchema`. Since (1) namespaces are URIs and (2) [percent-encoded](https://tools.ietf.org/html/rfc3986#section-2.1) URIs form valid directory names, URL encoding is used. For a better understanding we distinguish two cases: (1) calling a URL and -(2) linking to the location of an tosca import in a tosca XML file contained in the CSAR. +(2) linking to the location of a TOSCA import in a TOSCA XML file contained in the CSAR -### First case: Calling a URL -When using the Winery UI to show a Node Type the following URL is used by the browser: http://localhost:8080/winery/nodetypes/http%253A%252F%252Fopentosca.org%252Fnodetypes/Java8/ -The convention for URLs in the winery are: `winery/type/namespace/id` (see [DevGuide](./#url-structure)). +### (1) Calling a URL - - winery: `http://localhost:8080/winery/` +For example, to query node type information the following URL can be used: . +The convention for URLs in the Winery are: `winery/type/namespace/id` (see [REST API](rest.md#url-structure)). + + - winery: `http://localhost:8080/winery` - type: `nodetypes` - namespace: `http%253A%252F%252Fopentosca.org%252Fnodetypes` - id: `Java8` @@ -29,39 +45,24 @@ We have a closer look to the namespace part `http%253A%252F%252Fopentosca.org%25 The '/' and ':' of the URI are double [percent-encoded](https://tools.ietf.org/html/rfc3986#section-2.1), i.e., `:` is encoded --> `%3A` is encoded --> `%253A` (`%` is encoded --> `%25`). -If no double encoding whould be used http://localhost:8080/winery/nodetypes/http%3A%2F%2Fopentosca.org%252Fnodetypes/Java8/ whould be the used URL. +If no double encoding would be used would be the used URL. Web servers such as -Apache Tomcat [[1](https://stackoverflow.com/a/14600740/873282), [2](https://stackoverflow.com/a/41559969/873282)], -Apache [[3](https://stackoverflow.com/a/9933890/873282),[4](https://stackoverflow.com/a/3235361/873282)], -nginx [[5](https://stackoverflow.com/a/37584637/873282)], and -JBoss [[6](https://stackoverflow.com/a/5628325/873282)] -forbit this due to security issues. See -- http://en.wikipedia.org/wiki/Directory_traversal_attack -- http://www.tomcatexpert.com/blog/2011/11/02/best-practices-securing-apache-tomcat-7 -- https://stackoverflow.com/a/28113090/873282 +Apache Tomcat [1](https://stackoverflow.com/a/14600740/873282), [2](https://stackoverflow.com/a/41559969/873282), +Apache [3](https://stackoverflow.com/a/9933890/873282), [4](https://stackoverflow.com/a/3235361/873282), +nginx [5](https://stackoverflow.com/a/37584637/873282), and +JBoss [6](https://stackoverflow.com/a/5628325/873282) +forbid this due to security issues. +See [7](http://en.wikipedia.org/wiki/Directory_traversal_attack), [8](http://www.tomcatexpert.com/blog/2011/11/02/best-practices-securing-apache-tomcat-7), and [9](https://stackoverflow.com/a/28113090/873282). -Note that `%2F` and `/` are not the same in an URI: See Example 2 in [W3C's URI recommendations](https://www.w3.org/Addressing/URL/4_URI_Recommentations.html). +Note that `%2F` and `/` are not the same in a URI. +See Example 2 in [W3C's URI recommendations](https://www.w3.org/Addressing/URL/4_URI_Recommentations.html). -### Second Case: Encoding of directory names +### (2) Encoding of Directory Names As already mentioned, URLs used in directory names must be encoded. In XML files the `location` of an `tosca:import` is, for instance given as: `../imports/http%253A%252F%252Fwww.w3.org%252F2001%252FXMLSchema/http%253A%252F%252Fopentosca.org%252Fproperties/TopicProperties/TopicProperties.xsd`, which represents the path of the file. The attribute `location` is of type anyURI, i.e., this part [has to be decoded](https://tools.ietf.org/html/rfc3986#section-2.4). -If only single encouding is used like `../imports/http%3A%2F%2Fwww.w3.org...` the decoding whould lead to `../imports/http://www.w3.org...`, which is not a valid URI and also not a valid file name. -Summary: Because the namespace is part of the used URIs and the ns itself is a URI too this double encoding is required. - - -## License - -Copyright (c) 2017 Contributors to the Eclipse Foundation - -See the NOTICE file(s) distributed with this work for additional -information regarding copyright ownership. - -This program and the accompanying materials are made available under the -terms of the Eclipse Public License 2.0 which is available at -http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0 -which is available at https://www.apache.org/licenses/LICENSE-2.0. +If only single encoding is used like `../imports/http%3A%2F%2Fwww.w3.org...` the decoding would lead to `../imports/http://www.w3.org...`, which is not a valid URI and also not a valid file name. -SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 +Summary: Because the namespace is part of the used URI and the namespace itself is a URI too, double encoding is required. diff --git a/docs/dev/REST.md b/docs/dev/REST.md index 0567c5cc3d..870675711b 100644 --- a/docs/dev/REST.md +++ b/docs/dev/REST.md @@ -1,15 +1,29 @@ -# REST + + + +# REST API All resources are implemented in classes in the package `org.eclipse.winery.repository.rest.resources`. We call all elements directly nested in the definitions element "components". They are implemented using JAX RS using [Jersey](https://eclipse-ee4j.github.io/jersey/). -The full set the API is used by the Type, Template, and Artifact Management UI (see [User Documentation](../user/)). -A subset of the API is used at [IWineryRepository](#iwineryrepository). +The full set the API is used by the Management user interface and the Topology Modeler. ## URL Structure -The idea behind the URL structure may shortly describes by `ROOT/s///`, which makes the structure similar to one of the [file system](RepositoryLayout). +The idea behind the URL structure may shortly describes by `ROOT/s///`, which makes the structure similar to one of the [file system](repository-layout.md). Encoding is done following [RFC 3986](https://tools.ietf.org/html/rfc3986#section-2.1). An online URL-encoder may be found at: . @@ -21,67 +35,54 @@ This is due to security decisions to disallow `%2F` in URLs. The part until `s` is realized by ["AbstractComponentsResource" and its subclasses](#collections-of-components). The resource specific part is realized by [subclasses of AbstractComponentInstanceResource](#component-instances). -More information on encoding is given at [Encoding](Encoding). +More information on encoding is given at [Encoding](encoding.md). ## Collections of Components -![AbstractCompoenentResource Inheritance](graphics/InheritanceOfAbstractComponentResource.png) -**Figure 6: Inheritance of AbstractComponentResource** +![](figures/InheritanceAbstractComponentResource.png) -Figure 6 shows the inheritance of AbstractComponentsResource. It contains an intermediate class -"AbstractComponentsWithTypeReferenceResource" which handles a POST with an additional type. It is used at -all components which have a type associated. These are artifact templates, node type implementations, -relationship type implementations and policy templates. +The figure above shows the inheritance of AbstractComponentsResource. +It contains an intermediate class `AbstractComponentsWithTypeReferenceResource` which handles a POST with an additional type. +It is used at all components which have a type associated. +These are artifact templates, node type implementations, relationship type implementations and policy templates. -All logic is implemented in AbstractComponentsRessource. -It handles creation of resources (using POST) and creation of AbstractComponentInstanceResources. +All logic is implemented in `AbstractComponentsResource`. +It handles creation of resources (using POST) and creation of `AbstractComponentInstanceResources`. ## Component Instances -![AbstractComponentInstanceResource Inheritance](graphics/InheritanceOfAbstractComponentInstanceResource.png) -**Figure 7: Inheritance of AbstractComponentInstanceResource** +![](figures/InheritanceAbstractComponentInstanceResource.png) -Figure 7 shows the inheritance of AbstractComponentInstanceResource. +The figure above shows the inheritance of `AbstractComponentInstanceResource`. For each component, a class exists. Using Intermediate classes, common properties are handled. These are explained in the following sections. ### AbstractComponentInstanceResourceWithNameDerivedFromAbstractFinal -Several component instances have the attributes "name", "dervidedFrom", "abstract", and "final". These are -handled in the class "AbstractComponentInstanceResourceWithNameDerivedFromAbstractFinal". In this group, -type implementations, namely node type implementations and relationship type implementations can be found. +Several component instances have the attributes `name`, `dervidedFrom`, `abstract`, and `final`. +These are handled in the class `AbstractComponentInstanceResourceWithNameDerivedFromAbstractFinal`. +In this group, type implementations, namely node type implementations and relationship type implementations can be found. -Furthermore, type resources exist. These are grouped by the "EntityTypeResource". Within the context of this class, -"TopologyGraphElementEntityTypeResource" is introduced. This class groups together "NodeTypeResource" and "RelationshipTypeResource". +Furthermore, type resources exist. +These are grouped by the `EntityTypeResource`. +Within the context of this class, `TopologyGraphElementEntityTypeResource` is introduced. +This class groups together `NodeTypeResource` and `RelationshipTypeResource`. ### AbstractComponentInstanceWithReferencesResource -This class groups together classes with file references. Artifact Templates may reference files and a Service -Template may reference plans. The user can copy files manually to the right place in the directory structure of -the repository. By calling the method "synchronizeReferences()", the referenced stores in the XML are -synchronized with the actually existing files. This is done whenever the XML is retrieved from the repository. +This class groups together classes with file references. +Artifact Templates may reference files and a Service Template may reference plans. +The user can copy files manually to the right place in the directory structure of the repository. +By calling the method `synchronizeReferences()`, the referenced stores in the XML are synchronized with the actually existing files. This is done whenever the XML is retrieved from the repository. #### GenericImportResource -This class is used to handle different import types. Currently only CSD is supported. The class is -"XSDImportResource". +This class is used to handle different import types. +Currently, only CSD is supported. +The class is `XSDImportResource`. #### PolicyTemplateResource -This class implements the resource for a policy template. Since a policy template does not contain any external -file references, it is not modeled as child of "AbstractComponentInstanceWithReferencesResource". - -## License - -Copyright (c) 2013-2018 Contributors to the Eclipse Foundation - -See the NOTICE file(s) distributed with this work for additional -information regarding copyright ownership. - -This program and the accompanying materials are made available under the -terms of the Eclipse Public License 2.0 which is available at -http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0 -which is available at https://www.apache.org/licenses/LICENSE-2.0. - -SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 +This class implements the resource for a policy template. +Since a policy template does not contain any external file references, it is not modeled as child of `AbstractComponentInstanceWithReferencesResource`. diff --git a/docs/dev/ToolChain-initialization.md b/docs/dev/ToolChain-initialization.md deleted file mode 100644 index e9f24c3a63..0000000000 --- a/docs/dev/ToolChain-initialization.md +++ /dev/null @@ -1,67 +0,0 @@ -# Eclipse Winery Toolchain - -To contribute to Eclipse Winery development you need a GitHub account and access to . -Email your supervisor your GitHub username. - -- In case you did not choose an account name, use `flastname` as pattern: - `f` is the lower-case first letter of your firstname and - `lastname` is the lower-case lastname. -- Due to open source development, your email adress will get public. - In case, you don't have a public email adress, we recommend to create one or use your student email adress. - In case you want to create a longer-lasting one, please use the GitHub username. - Example: `flastname@gmail.com`. -- Please enable the git-hooks by executing `git config core.hooksPath .git-hooks` in the root of the repository. - -## Steps to get Apache Maven ready - -Get [Apache Maven](https://maven.apache.org/) to run. - -Windows: - -1. Get [choclatey](https://chocolatey.org/) -1. Execute in an **Administor cmd.exe**: `@"%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe" -NoProfile -InputFormat None -ExecutionPolicy Bypass -Command "iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))" && SET "PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin"` -1. Execute `choco install maven`. This also installs the latest Java8 JDK. - -## Steps to get write access to the code repositories - -1. Email your supervisor your GitHub username and your development email address. -2. Your supervisor adds you to the team "developers" at and . -3. You will receive two emails from GitHub asking for your confirmation. -4. Open the link . -5. Open the link . - -## Steps to initialize the code repository - -1. Clone (it automatically becomes the `origin`). - - We recommend that git repositories reside in `c:\git-repositories`. - - Use [ConEmu](https://conemu.github.io/) as program for all your shells: `choco install conemu`. - Install [chocolatey](https://chocolatey.org/) to use the `choco` command. - - Execute `git clone https://github.com/OpenTOSCA/winery.git` in `c:\git-repositories`. -2. Change into the newly created directory `winery`: `cd winery`. -3. Add `upstream` as second remote: `git remote add upstream https://github.com/eclipse/winery.git` -4. Fetch everything from `upstream`: `git fetch upstream` -5. Run `mvn package -DskipTests` to have `Version.java` generated - -## Steps to initialize the TOSCA repository - -Please go to the [quick setup guide](../user/quicksetup.md). - -## Steps to initialize the IDE - -Setup IntelliJ as described at [config/IntelliJ IDEA](config/IntelliJ%20IDEA). -Alternatively, you can you Eclipse as described at [config/Eclipse](config/Eclipse). -However, the latter is currently work-in-progress. - -## License - -Copyright (c) 2013-2018 Contributors to the Eclipse Foundation - -See the NOTICE file(s) distributed with this work for additional -information regarding copyright ownership. - -This program and the accompanying materials are made available under the -terms of the Eclipse Public License 2.0 which is available at -http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0 -which is available at https://www.apache.org/licenses/LICENSE-2.0. - -SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 diff --git a/docs/dev/ToolChain.md b/docs/dev/ToolChain.md index 5c6071d2ee..3a326643ae 100644 --- a/docs/dev/ToolChain.md +++ b/docs/dev/ToolChain.md @@ -1,159 +1,86 @@ -# Eclipse Winery Toolchain - - - -- [Steps for working on a topic](#steps-for-working-on-a-topic) -- [GitHub - Prepare Final Pull Request](#github---prepare-final-pull-request) -- [GitHub - Create Final Pull Request](#github---create-final-pull-request) -- [GitHub - Change Final Pull Request](#github---change-final-pull-request) -- [GitHub - After Pull Request Got Merged](#github---after-pull-request-got-merged) -- [Excursus: Git](#excursus-git) - - - -This presents the tool chain used for creating and updating a pull request on GitHub. - -For the general setup, please go to [ToolChain-initialization](ToolChain-initialization.md). - -## Steps for working on a topic - -Main idea: Separate branch for each topic (fix a bug, add functionality) and accordingly named. -See for more information. - - 1. Sync with latest changes on upstream (especially master branch): `git fetch upstream --prune`. - 3. Create branch based on `upstream/master` and make it known publicly: - - `git checkout upstream/master` - - `git checkout -b [name]` - Branch naming patterns: - - Bugfix: `fix/SHORT-TITLE`, e.g., `fix/deletion-of-namespaces` - - Feature: `feature/SHORT-TITLE`, e.g., `feature/drag-and-drop-for-bpmn4tosca` - - Thesis: `thesis/SHORT-THESIS-TITLE`. Replace `SHORT-THESIS-TITLE` with something meaningful, e.g., `thesis/versioning` - - EnPro: prefix `fix` or `feature` (see above) with `enpro/`, e.g., `enpro/fix/policy-rendering` - - StuPro: prefix `fix` or `feature` (see below) with `stupro/`, e.g., `stupro/feature/github-oauth` - - `git push --set-upstream origin [name]` - 4. Do you your fist commit. Don't forget to sign-off the commit (Ctrl+S in Git Gui). - 6. Push the changes to origin: `git push`. - 7. Create [WIP] Pull Request. - - Go to 🡒 Pull Request - - Change the "base branch" to OpenTOSCA/winery - ![change-base-fork-to-opentosca-winery](graphics/toolchain-change-base-fork-to-opentosca-winery.png) - - Fill in the title of the Pull Request following the pattern `[WIP] Title of the thesis/work/target` - - Fill in the provided description form - - Add `[x]` to the items listed in the write field - - Check the description in the Preview and send the Pull Request - 8. There are automatic checks in place - ![GitAutoCheck](graphics/autoCheckGit.png) - 9. If there is a red cross, click in respective "Details" and fix them - -**You keep working and discuss with your supervisor how things go.** - -After each working day, do the following: - - 1. Commit. Don't forget to sign the commit (Ctrl+S in Git Gui). - 2. `git push` - 3. Keep your branch updated with `upstream/master`: - - `git fetch upstream` - - `git merge upstream/master` - - Resolve conflicts - if there are some. See for a documentation when using IntellIJ. - - `git push` - - -## GitHub - Prepare Final Pull Request - -The aim of these steps to have a **single commit**. -This is required by the Eclipse process for checking for intellectual property (IP process for short). - -**Before commencing these steps, check with your supervisor** - -### Formal Requirements - -* 🡒 Create an account **WITH THE SAME EMAIL AS USED FOR THE COMMITS** (can also be checked in [gitk]) -* Sign the Contributor Agreement electronically - -### Git Steps: Ensure that a single commit is created - - 1. `git fetch upstream` - fetches all updates from https://github.com/eclipse/winery ("upstream") to the local git storage - 2. `git merge upstream/master` - merges all updates from upstream to the local branch - 3. (Resolve merge conflicts) - required if there are conflicting changes - 4. Commit & Push with signed commit message (Ctrl+S in Git Gui) - this ensures that you have the changes backuped in case something goes wrong at the next steps - 5. `git reset upstream/master` - this prepares that all commits can be squashed together: - The local checkout ("working tree") is left untouched, but the "pointer" of the current branch is reset to `upstream/master`. - Now, Git Gui shows the difference between `upstream/master` and your changes. - 6. Check changes in Git Gui: - - Each change you wanted: Is it recognized? - - At each file: Is the copyright information in the [header](CodeHeaders.md) OK? - - Check if you are listed in the [NOTICE](https://github.com/eclipse/winery/blob/master/NOTICE) file as a contributor with the correct year - - Are there too much changed lines? 🡒 Do not stage spurious lines to the commit (e.g., tab to spaces, ...) - - Are there too much changed files? 🡒 Do not stage files you did not intend to change (e.g., `build.gradle` if you did not touch `build.gradle` at all) - - Check again the style (!) - - (Don't forget RESCAN to see the current changes) - 7. Add description as new markdown file to to `docs/index.md` (if helpful) - 8. Press "Stage to Commit" 🡒 all changes are staged to Commit - 9. Sign the Commit Message (Ctrl+S in Git Gui) - 10. In the case of multiple authors: Add each additional author with `Co-authored-by`. - See also in the [Eclipse Handbook](https://www.eclipse.org/projects/handbook/#resources-commit). - Example: - - Co-authored-by: Some Bodyelse - Signed-off-by: Some Body - - 11. Commit & Push with "force overwrite" since you changed the branch: `git push -f` - -## GitHub - Create Final Pull Request - -**Attention: Commits on the same branch done after the Pull Request is sent are still part of the Pull Request (!)** - -* Go to https://github.com/eclipse/winery 🡒 Pull Request -* Fill in the title of the Pull Request and give a more detailed description of the changes or added functionality -* In case of UI changes: Add screenshots -* Add `[x]` to the items listed in the write field -* Check the description in the Preview and send the Pull Request -* Close your Pull Request at OpenTOSCA/winery with a comment referencing the full URL of the new Pull Request, e.g. `Follow up at https://github.com/eclipse/winery/pull/212`. - - -## GitHub - Change Final Pull Request - -* There are automatic checks in place - -![GitAutoCheck](graphics/autoCheckGit.png) - -* If there is a red cross, click in repective "Details" and fix them - -* In case of missing code quality, ... changes are requested by a committer (person controlling the pull request process) -* FOR WINERY THE FOLLOWING APPLIES: - - Open Git Gui - - Make requested changes in your code (don't forget to RESCAN) - - Commit - - Push - - Wait for a second review - - In case everything is fine, squash the commits into one. - See [GitHub - Prepare Pull Request](#github---prepare-pull-request). - Then, do a force push (`git push -f`). + -## GitHub - After Pull Request Got Merged - -* Delete the branch locally. -* The branch on origin () is deleted by the maintainer having done the merge. - -## Excursus: Git - -![ExcursusGit](graphics/ExcursusGit.png) - -Please see also [use gitk to understand git](https://lostechies.com/joshuaflanagan/2010/09/03/use-gitk-to-understand-git/) to understand the settings in git. - -## License - -Copyright (c) 2017 Contributors to the Eclipse Foundation - -See the NOTICE file(s) distributed with this work for additional -information regarding copyright ownership. - -This program and the accompanying materials are made available under the -terms of the Eclipse Public License 2.0 which is available at -http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0 -which is available at https://www.apache.org/licenses/LICENSE-2.0. - -SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 +# Eclipse Winery Toolchain - [gitk]: https://lostechies.com/joshuaflanagan/2010/09/03/use-gitk-to-understand-git/ +To contribute to Eclipse Winery development you need a GitHub account and access to . +Email your supervisor your GitHub username. + +- In case you did not choose an account name, use `flastname` as pattern: + `f` is the lower-case first letter of your first name and + `lastname` is the lower-case last name. +- Due to open source development, your email address will get public. + In case, you don't have a public email address, we recommend creating one or use your student email address. + In case you want to create a longer-lasting one, please use the GitHub username. + Example: `flastname@gmail.com`. +- Please enable the git-hooks by executing `git config core.hooksPath .git-hooks` in the root of the repository. + +## Install Apache Maven + +Get [Apache Maven](https://maven.apache.org/) to run. + +## Get write access to the code repositories + +1. Email your supervisor your GitHub username and your development email address. +2. Your supervisor adds you to the team "developers" at and . +3. You will receive two emails from GitHub asking for your confirmation. +4. Open the link . +5. Open the link . + +## Steps to initialize the code repository + +1. Clone (it automatically becomes the `origin`). + - We recommend that git repositories reside in `c:\git-repositories`. + - Use [ConEmu](https://conemu.github.io) as a program for all your shells: `choco install conemu`. + Install [chocolatey](https://chocolatey.org/) to use the `choco` command. + - Execute `git clone https://github.com/OpenTOSCA/winery.git` in `c:\git-repositories`. +2. Change into the newly created directory `winery`: `cd winery`. +3. Add `upstream` as second remote: `git remote add upstream https://github.com/eclipse/winery.git` +4. Fetch everything from `upstream`: `git fetch upstream` or `git fetch --all` +5. Run `mvn clean install -DskipTests` to build the whole project + +## Steps to initialize a TOSCA repository + +Winery has built-in *magic* to check for existence of `c:/winery-repository` on Windows. +If that directory exists, this is used as repository location. +If that directory does not exists, it uses the home directory, which is `%HOME%` defaulting to `c:/Users//winery-repository` +(or `~/winery-repository` on Linux-based operating systems). + +However, you can start Winery based on an existing repository. + +XML Repo: +YAML Repo: https://github.com/radon-h2020/radon-particles + +1. Clone one the repositories from above +2. Start the Winery backend to initialize the configuration files +3. Go to `C:\Users\\.winery` on your computer and open the file `winery.yml` +4. Adjust the value of the `provider` and `repositoryRoot` attribute: + + ``` + provider: file + repositoryRoot: c:\git-repositories\tosca-definitions-internal + ``` + or + ``` + provider: yaml + repositoryRoot: c:\git-repositories\radon-particles + ``` +5. Restart your Winery backend + +## Steps to initialize the IDE + +Setup IntelliJ IDEA as described at [config/IntelliJ IDEA](../config/IntelliJ%20IDEA/index.md). +Alternatively, you can you Eclipse as described at [config/Eclipse](../config/Eclipse/index.md). +However, the latter is currently work-in-progress. diff --git a/docs/dev/branches.md b/docs/dev/branches.md index 78dccb4f57..7adf1e23c6 100644 --- a/docs/dev/branches.md +++ b/docs/dev/branches.md @@ -1,3 +1,18 @@ + + + # Branches The `master` branch is always compiling and all tests should go through. @@ -10,44 +25,9 @@ We try to follow following naming conventions: - Bugfix: `fix/issue-NNN` or `fix/SHORT-TITLE` if fixing an issue with a number or give it a title - Feature: `feature/issue-NNN` or `feature/SHORT-TITLE` - - WIP: `wip/SHORT-TITLE` for work in progress without issue and you know won't be finished soon - - Thesis: `thesis/SHORT-THESIS-TITLE`. Replace `SHORT-THESIS-TITLE` with something meaningful + - WIP: `wip/SHORT-TITLE` for 'work in progress' without an issue and you know won't be finished soon + - Thesis: `thesis/SHORT-THESIS-TITLE`, replace `SHORT-THESIS-TITLE` with something meaningful - EnPro: prefix `fix`, `feature`, `wip` (see below) with `enpro/` - StuPro: prefix `fix`, `feature`, `wip` (see below) with `stupro/` See for a discussion and other ideas. - -## Editing the gh-pages branch of the test repository - -It is beneficial to have the [gh-pages branch](https://github.com/winery/test-repository/tree/gh-pages) of the test repository checked out in a second directory to be able to work in Winery and on the homepage in parallel. -Git supports that by the [worktree command](https://git-scm.com/docs/git-worktree): - -1. Change directory to `C:\winery-repository` -2. Execute `git worktree add ..\git-repositories\winery-repository-gh-pages gh-pages` to check out the `gh-pages` branch into `C:\git-repositories\winery-repository-gh-pages`. - -Full output: - -``` -$ C:\winery-repository -> git worktree add ..\git-repositories\winery-repository-gh-pages gh-pages -Preparing ../git-repositories/winery/winery-repository-gh-pages (identifier winery-repository-gh-pages) -HEAD is now at 5017713 Initial documentation -``` - -## License - -Copyright (c) 2013-2018 Contributors to the Eclipse Foundation - -See the NOTICE file(s) distributed with this work for additional -information regarding copyright ownership. - -This program and the accompanying materials are made available under the -terms of the Eclipse Public License 2.0 which is available at -http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0 -which is available at https://www.apache.org/licenses/LICENSE-2.0. - -SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 - - [Apache Maven]: https://maven.apache.org/ - [bower]: https://bower.io/ - [jsPlumb#165]: https://github.com/jsplumb/jsPlumb/issues/165 diff --git a/docs/dev/config.md b/docs/dev/config.md new file mode 100644 index 0000000000..28c5b860c5 --- /dev/null +++ b/docs/dev/config.md @@ -0,0 +1,108 @@ + + + +# Configuration and Features + +Implemented in the package `org.eclipse.winery.common.configuration`. +The configuration is YAML based and called `winery.yml`. +The default Configuration is contained in the resource folder. + +## Adding new Features + +To add a new feature to the configuration one has to simply add it hierarchically under the features tab in the `winery.yml` file. +This has to be done both in the winery.yml file in the filesystem and in the default configuration winery.yml file in the resources folder. + +```yaml +ui: + features: + splitting: true + completion: true + patternRefinement: true + compliance: true + accountability: true + nfv: true + endpoints: + container: http://localhost:1337 + workflowmodeler: http://localhost:8080/winery-workflowmodeler + topologymodeler: http://localhost:8080/winery-topologymodeler + repositoryApiUrl: http://localhost:8080/winery + repositoryUiUrl: http://localhost:8080/# +repository: + provider: file + repositoryRoot: "" + git: + clientSecret: secret + password: default + clientID: id + autocommit: false + username: default +``` + +If the feature has been added to the YAML Configuration the `getUiConfig()` method of the Environments class will return a UiConfigurationObject Instance which has the added feature as a map entry in the features map attribute. This can be accessed with the getFeatures() method. +The key of the feature entry is the same name that was added to the `winery.yml` file. + +## Accessing the Configuration in the Backend + +The configuration is split into different objects. +The `UiConfigurationObject` contains the feature flags and endpoints. +The `RepositoryConfigurationObject` contains all the repository settings including a `GitConfigurationObject`. +The `GitConfigurationObject` contains all settings associated with Git. +Each of these configuration objects can be accessed through a getter in the `Environments` class, e.g. `getGitConfig()`. +When the changes to a configuration object shall be persisted, the `Environments` class offers a save method, in which the changed configuration object has to be passed as the parameter. + +## Accessing the Configuration in the Frontend + +In the `org.eclipse.winery.repository.rest.resources.admin.AdminTopResource.java` are two methods implemented which are used to send the configuration to the frontend `getConfig()` and get updates to the configuration from the frontend `setConfig()`. +In the frontend the `WineryRepositoryConfigurationService` manages those resources. +Injecting the service where the configuration is needed provides the configuration as the configuration attribute of the WineryRepositoryConfigurationService. +Therefore the feature has to be added as a boolean attribute to the WineryConfiguration interface. + +```typescript +export interface WineryConfiguration { + features: { + splitting: boolean; + completion: boolean; + compliance: boolean; + patternRefinement: boolean; + accountability: boolean; + nfv: boolean; + }; + endpoints: { + container: String; + workflowmodeler: String; + topologymodeler: String; + }; +} +``` + +### Using Feature Toggles + +The `FeatureToggleDirective` offers a way to use the configuration to toggle features on or off dynamically. +Before using the directive in any html file it has to be imported first into the corresponding module. +Additionally, an enum in the component where the feature toggle will be used has to be created and declared with the FeatureEnum. + +```typescript +export enum FeatureEnum { + Splitting = 'splitting', Completion = 'completion', Compliance = 'compliance', + PatternRefinement = 'patternRefinement', Accountability = 'accountability', NFV = 'nfv', + newFeature = 'newFeature' +} +``` + +Finally, the directive can be used to toggle the feature according to the set configuration. + +``` +
+``` diff --git a/docs/dev/config/IntelliJ IDEA/README.md b/docs/dev/config/IntelliJ IDEA/README.md deleted file mode 100644 index 817d8bdee3..0000000000 --- a/docs/dev/config/IntelliJ IDEA/README.md +++ /dev/null @@ -1,147 +0,0 @@ -# IntelliJ Configuration - -## Preparation: Install IntelliJ - -1. Get a JetBrains Ultimate License. For students: Visit . -1. Install [JetBrains Toolbox](https://www.jetbrains.com/toolbox/): `choco install jetbrainstoolbox` and `choco pin add -n jetbrainstoolbox`, because JetBrains does an auto update -1. Install "IntelliJ IDEA Ultimate" using the JetBrains Toolbox. - -## Preparation of the code - -Generate a war to have all dependencies fetched by maven: `mvn package -DskipTests`. -This ensures that `Version.java` is generated and all node dependencies are fetched. -If this goes wrong at the first run, execute `mvn package -DskipTests` a second time. - -## Setup of IntelliJ - -1. At start of IntelliJ, browse to the root `pom.xml` and open it as project. -3. Enable checkstyle: Follow the shown steps and apply them in IntelliJ - ![Enable CheckStyle in IntelliJ](graphics/activate-checkstyle.gif) - - Install the [IntelliJ Checkstyle Plugin](https://plugins.jetbrains.com/plugin/1065-checkstyle-idea). - It can be found via plug-in repository (Settings -> Plugins -> Browse repositories) - - Open the Settings (by pressing Ctrl + Alt + S) - - Go to Other Settings -> CheckStyle. - - Click on the green plus and add `checkstyle.xml` from the root of the Winery code repository. -4. Configure the code style (Source: ) - 1. Open the Settings (by pressing Ctrl + Alt + S) - 3. Go to "Editor > Code Style" - 3. Click "Manage..." (right of "Scheme:") - 4. Click "Import Scheme" - 4. Choose "IntelliJ IDEA code style XML" - 5. Navigate to `intellij-idea-code-style.xml`. It is located in `docs/dev/config/IntelliJ IDEA` - 6. Press "OK" - 6. You will see a message "Winery configuration settings were imported". - 7. Press "OK" - 8. Press "Close" - 9. Press "OK" -5. Setup code headers to be inserted automatically - 1. Open the Settings (by pressing Ctrl + Alt + S) - 2. Go to Editor > Copyright > Copyright Profiles - 3. Click the green plus - 4. Name "Winery" - 5. Copyright text from [CodeHeaders](../../CodeHeaders.md) - 6. Go to Editor > Copyright > Formatting - 7. Adjust copyright formatting settings - - Change to `Use block comments` with `Prefix each line` - - Set `Relative Location` to `Before other comments` - - Increase `Separator before/after Length` to `81` - - ![GitAutoCheck](graphics/CopyrightFormat.png) - 8. Go to Editor > Copyright - 9. Set "Winery" as Default project copyright - 10. Press "OK" -6. Setup Apache Tomcat - 1. Download Tomcat 9.0 from . - Choose "zip" (E.g., ). - 1. Extract it to `C:\Apache`. Result: `C:\Apache\apache-tomcat-9.0.7`. - 1. ![](graphics/run-step1-edit-configuration.png) - 1. ![](graphics/run-step2-add-new-configuration.png) - 1. ![](graphics/run-step3-add-tomcat.png) - 1. ![](graphics/run-step4-configure-tomcat-button.png) - 1. ![](graphics/run-step5-add-appserver-button.png.png) - 1. ![](graphics/run-step6-set-apache-tomcat-directory.png) - 1. Press OK
- ![](graphics/run-step7-confirm.png) - 1. Set name and no browser launch:
- ![](graphics/run-step8-name-and-no-browser.png) - 1. Add deployment artifacts:
- ![](graphics/run-step9-button-add-deployment-artifacts.png) - 1. ![](graphics/run-step10-choose-artifact.png) - 1. ![](graphics/run-step11-select-artifcat.png) - 1. Set `/winery` as application context:
- ![](graphics/run-step12-set-winery-as-application-context.png) - 1. Click "Apply" -6. Setup npm run for TOSCA Management UI - 1. ![](graphics/run-repositoryui-step1-add-npm-config.png) - 1. ![](graphics/run-repositoryui-step2-configure.png) -6. Setup npm run for Topologymodeler - 1. ![](graphics/run-topologymodeler-step1-add-npm-config.png) - 1. ![](graphics/run-topologymodeler-step2-configure.png) -6. Setup npm run for Workflowmodeler (BPMN4TOSCA Modeler) - 1. ![](graphics/run-topologymodeler-step1-add-npm-config.png) - 1. ![](graphics/run-workflowmodeler-step2.png) -6. Setup XSD validation for TOSCA files - 1. Open the Settings (by pressing Ctrl + Alt + S) - 1. Go to "Languages & Frameworks" - 1. Select "Schemas and DTDs" - 1. Click on the plus on the right at "External Schemas and DTDs" - 1. Enter `http://docs.oasis-open.org/tosca/ns/2011/12` as URI - 1. In "Project Schemas" search for `TOSCA-v1.0.xsd`. - It should be located at "org.eclipse.winery.common". - In the case of opening `C:\winery-repository` in IntelliJ, you have to select enter `C:\git-repositories\winery\org.eclipse.winery.common\src\main\resources\TOSCA-v1.0.xsd` in the Field "File" - 1. Click "OK". - 1. Go to "Editor" - 1. Select "File Types" - 1. At "Recognized File Types", scroll down to XML - 1. Select "XML" - 1. At "Registered Patterns", click on the Plus - 1. Enter `*.tosca` in the popup. - 1. Click "OK" - 1. Click "OK" -6. Optional: In case you do not want to have the live-update of Angular, you build the wars of the UI and then deploy as follows: - - External artifact `.../org.eclipse.winery.frontends/target/tosca-management.war` to `/` - - External artifact `.../org.eclipse.winery.frontends/target/topologymodeler.war` to `/winery-topology-modeler` - - External artifact `.../org.eclipse.winery.frontends/target/workflowmodeler.war` to `/winery-workflowmodeler` -9. Run everything - - Select "Winery - REST". Click on "Play" (the green rectangle) - - Select "TOSCA Mangement UI". Click on "Play" - - Select "Topolgoymodeler". Click on "Play". - - Open in your browser. -10. Demonstration: Open winery-repository (AKA tosca-definitions) in IntelliJ - This ensures that you can work with the TOSCA files using the IDE. - 1. Go to File -> Open... - 1. Enter `C:\winery-repository` - 1. Click "OK" - 1. At the dialog "Open Project" choose "New Window" - 1. Expand `winery-repository` (on the left side) - 1. Expand `nodetypes` - 1. Exapnd `http%3A%2F%2Fplain.winery.opentosca.org%2Fnodetypes` - 1. Expand `NodeTypeWithTwoKVProperties` - 1. Double click `NodeType.tosca` - 1. Go to line 14 - 1. Type in `<` - 1. See that `Shift / Ctrl+Shift+F / Ctrl+F: Differrent forms of search - - Ctrl+Alt+L: Organize imports (fixes checkstyle) - - Ctrl+X: if nothing is marked: cut line (equal to marking whole line and using Ctrl+X) - - Ctrl+Shift+T: Create/jump to the test class -* See [UpdateCopyrightHeaders](UpdateCopyrightHeaders.md) for updating old copyright headers - -## License - -Copyright (c) 2017-2019 Contributors to the Eclipse Foundation - -See the NOTICE file(s) distributed with this work for additional -information regarding copyright ownership. - -This program and the accompanying materials are made available under the -terms of the Eclipse Public License 2.0 which is available at -http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0 -which is available at https://www.apache.org/licenses/LICENSE-2.0. - -SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 diff --git a/docs/dev/graphics/AdminIdHierarchy.png b/docs/dev/figures/AdminIdHierarchy.png similarity index 100% rename from docs/dev/graphics/AdminIdHierarchy.png rename to docs/dev/figures/AdminIdHierarchy.png diff --git a/docs/dev/graphics/autoCheckGit.png b/docs/dev/figures/AutoCheckGit.png similarity index 100% rename from docs/dev/graphics/autoCheckGit.png rename to docs/dev/figures/AutoCheckGit.png diff --git a/docs/dev/graphics/toolchain-change-base-fork-to-opentosca-winery.png b/docs/dev/figures/ChangeBaseForkToOpentoscaWinery.png similarity index 100% rename from docs/dev/graphics/toolchain-change-base-fork-to-opentosca-winery.png rename to docs/dev/figures/ChangeBaseForkToOpentoscaWinery.png diff --git a/docs/dev/graphics/ComponentIdHierarchy.png b/docs/dev/figures/ComponentIdHierarchy.png similarity index 100% rename from docs/dev/graphics/ComponentIdHierarchy.png rename to docs/dev/figures/ComponentIdHierarchy.png diff --git a/docs/dev/graphics/create-policy-modal.PNG b/docs/dev/figures/CreatePolicyModal.png similarity index 100% rename from docs/dev/graphics/create-policy-modal.PNG rename to docs/dev/figures/CreatePolicyModal.png diff --git a/docs/dev/graphics/create-policy-template-modal.PNG b/docs/dev/figures/CreatePolicyTemplateModal.png similarity index 100% rename from docs/dev/graphics/create-policy-template-modal.PNG rename to docs/dev/figures/CreatePolicyTemplateModal.png diff --git a/docs/dev/graphics/custom-key-value-property.PNG b/docs/dev/figures/CustomKeyValueProperty.png similarity index 100% rename from docs/dev/graphics/custom-key-value-property.PNG rename to docs/dev/figures/CustomKeyValueProperty.png diff --git a/docs/dev/graphics/custom-key-value-property-created.PNG b/docs/dev/figures/CustomKeyValuePropertyCreated.png similarity index 100% rename from docs/dev/graphics/custom-key-value-property-created.PNG rename to docs/dev/figures/CustomKeyValuePropertyCreated.png diff --git a/docs/dev/graphics/custom-key-value-property-modal.PNG b/docs/dev/figures/CustomKeyValuePropertyModal.png similarity index 100% rename from docs/dev/graphics/custom-key-value-property-modal.PNG rename to docs/dev/figures/CustomKeyValuePropertyModal.png diff --git a/docs/dev/graphics/custom-key-value-property-template.PNG b/docs/dev/figures/CustomKeyValuePropertyTemplate.png similarity index 100% rename from docs/dev/graphics/custom-key-value-property-template.PNG rename to docs/dev/figures/CustomKeyValuePropertyTemplate.png diff --git a/docs/dev/graphics/custom-key-value-property-template-value.PNG b/docs/dev/figures/CustomKeyValuePropertyTemplateValue.png similarity index 100% rename from docs/dev/graphics/custom-key-value-property-template-value.PNG rename to docs/dev/figures/CustomKeyValuePropertyTemplateValue.png diff --git a/docs/dev/graphics/ExcursusGit.png b/docs/dev/figures/ExcursusGit.png similarity index 100% rename from docs/dev/graphics/ExcursusGit.png rename to docs/dev/figures/ExcursusGit.png diff --git a/docs/dev/graphics/ExcursusGit.pptx b/docs/dev/figures/ExcursusGit.pptx similarity index 100% rename from docs/dev/graphics/ExcursusGit.pptx rename to docs/dev/figures/ExcursusGit.pptx diff --git a/docs/dev/graphics/FilesystemDirectoryLayout.png b/docs/dev/figures/FilesystemDirectoryLayout.png similarity index 100% rename from docs/dev/graphics/FilesystemDirectoryLayout.png rename to docs/dev/figures/FilesystemDirectoryLayout.png diff --git a/docs/dev/graphics/GenericIdHierarchy.png b/docs/dev/figures/GenericIdHierarchy.png similarity index 100% rename from docs/dev/graphics/GenericIdHierarchy.png rename to docs/dev/figures/GenericIdHierarchy.png diff --git a/docs/dev/graphics/InheritanceOfAbstractComponentInstanceResource.png b/docs/dev/figures/InheritanceAbstractComponentInstanceResource.png similarity index 100% rename from docs/dev/graphics/InheritanceOfAbstractComponentInstanceResource.png rename to docs/dev/figures/InheritanceAbstractComponentInstanceResource.png diff --git a/docs/dev/graphics/InheritanceOfAbstractComponentResource.png b/docs/dev/figures/InheritanceAbstractComponentResource.png similarity index 100% rename from docs/dev/graphics/InheritanceOfAbstractComponentResource.png rename to docs/dev/figures/InheritanceAbstractComponentResource.png diff --git a/docs/dev/github-workflow.md b/docs/dev/github-workflow.md new file mode 100644 index 0000000000..937b313764 --- /dev/null +++ b/docs/dev/github-workflow.md @@ -0,0 +1,163 @@ + + + +# Eclipse Winery GitHub Workflow + + + +- [Steps for working on a topic](#steps-for-working-on-a-topic) +- [GitHub - Prepare Final Pull Request](#github---prepare-final-pull-request) +- [GitHub - Create Final Pull Request](#github---create-final-pull-request) +- [GitHub - Change Final Pull Request](#github---change-final-pull-request) +- [GitHub - After Pull Request Got Merged](#github---after-pull-request-got-merged) +- [Excursus: Git](#excursus-git) + + + +This presents the tool chain used for creating and updating a pull request on GitHub. + +For the general setup, please go to [Eclipse Winery Toolchain](toolchain.md). + + +## Steps for working on a topic + +Main idea: Separate branch for each topic (fix a bug, add functionality) and accordingly named. +See for more information. + + 1. Sync with latest changes on upstream (especially master branch): `git fetch upstream --prune`. + 3. Create branch based on `upstream/master` and make it known publicly: + - `git checkout upstream/master` + - `git checkout -b [name]` + Branch naming patterns: + - Bugfix: `fix/SHORT-TITLE`, e.g., `fix/deletion-of-namespaces` + - Feature: `feature/SHORT-TITLE`, e.g., `feature/drag-and-drop-for-bpmn4tosca` + - Thesis: `thesis/SHORT-THESIS-TITLE`. Replace `SHORT-THESIS-TITLE` with something meaningful, e.g., `thesis/versioning` + - EnPro: prefix `fix` or `feature` (see above) with `enpro/`, e.g., `enpro/fix/policy-rendering` + - StuPro: prefix `fix` or `feature` (see below) with `stupro/`, e.g., `stupro/feature/github-oauth` + - `git push --set-upstream origin [name]` + 4. Do you your fist commit. Don't forget to sign-off the commit (Ctrl+S in Git Gui). + 6. Push the changes to origin: `git push`. + 7. Create [WIP] Pull Request. + - Go to 🡒 Pull Request + - Change the "base branch" to OpenTOSCA/winery + ![](figures/ChangeBaseForkToOpentoscaWinery.png) + - Fill in the title of the Pull Request following the pattern `[WIP] Title of the thesis/work/target` + - Fill in the provided description form + - Add `[x]` to the items listed in the write field + - Check the description in the Preview and send the Pull Request + 8. There are automatic checks in place + ![](figures/AutoCheckGit.png) + 9. If there is a red cross, click in respective "Details" and fix them + +**You keep working and discuss with your supervisor how things go.** + +After each working day, do the following: + + 1. Commit. Don't forget to sign the commit (Ctrl+S in Git Gui). + 2. `git push` + 3. Keep your branch updated with `upstream/master`: + - `git fetch upstream` + - `git merge upstream/master` + - Resolve conflicts - if there are some. See for a documentation when using IntellIJ. + - `git push` + + +## GitHub - Prepare Final Pull Request + +The aim of these steps to have a **single commit**. +This is required by the Eclipse process for checking for intellectual property (IP process for short). + +**Before commencing these steps, check with your supervisor** + +### Formal Requirements + +* 🡒 Create an account **WITH THE SAME EMAIL AS USED FOR THE COMMITS** (can also be checked in [gitk]) +* Sign the Contributor Agreement electronically + +### Git Steps: Ensure that a single commit is created + + 1. `git fetch upstream` - fetches all updates from https://github.com/eclipse/winery ("upstream") to the local git storage + 2. `git merge upstream/master` - merges all updates from upstream to the local branch + 3. (Resolve merge conflicts) - required if there are conflicting changes + 4. Commit & Push with signed commit message (Ctrl+S in Git Gui) - this ensures that you have the changes backuped in case something goes wrong at the next steps + 5. `git reset upstream/master` - this prepares that all commits can be squashed together: + The local checkout ("working tree") is left untouched, but the "pointer" of the current branch is reset to `upstream/master`. + Now, Git Gui shows the difference between `upstream/master` and your changes. + 6. Check changes in Git Gui: + - Each change you wanted: Is it recognized? + - At each file: Is the copyright information in the [header](source-code-headers.md) OK? + - Check if you are listed in the [NOTICE](https://github.com/eclipse/winery/blob/master/NOTICE) file as a contributor with the correct year + - Are there too much changed lines? 🡒 Do not stage spurious lines to the commit (e.g., tab to spaces, ...) + - Are there too much changed files? 🡒 Do not stage files you did not intend to change (e.g., `build.gradle` if you did not touch `build.gradle` at all) + - Check again the style (!) + - (Don't forget RESCAN to see the current changes) + 7. Add description as new markdown file to to `docs/index.md` (if helpful) + 8. Press "Stage to Commit" 🡒 all changes are staged to Commit + 9. Sign the Commit Message (Ctrl+S in Git Gui) + 10. In the case of multiple authors: Add each additional author with `Co-authored-by`. + See also in the [Eclipse Handbook](https://www.eclipse.org/projects/handbook/#resources-commit). + Example: + ``` + Co-authored-by: Some Bodyelse + Signed-off-by: Some Body + ``` + 11. Commit & Push with "force overwrite" since you changed the branch: `git push -f` + + +## GitHub - Create Final Pull Request + +**Attention: Commits on the same branch done after the Pull Request is sent are still part of the Pull Request (!)** + +* Go to https://github.com/eclipse/winery 🡒 Pull Request +* Fill in the title of the Pull Request and give a more detailed description of the changes or added functionality +* In case of UI changes: Add screenshots +* Add `[x]` to the items listed in the write field +* Check the description in the Preview and send the Pull Request +* Close your Pull Request at OpenTOSCA/winery with a comment referencing the full URL of the new Pull Request, e.g. `Follow up at https://github.com/eclipse/winery/pull/212`. + + +## GitHub - Change Final Pull Request + +* There are automatic checks in place + ![](figures/AutoCheckGit.png) + +* If there is a red cross, click in respective "Details" and fix them + +* In case of missing code quality, ... changes are requested by a committer (person controlling the pull request process) +* FOR WINERY THE FOLLOWING APPLIES: + - Open Git Gui + - Make requested changes in your code (don't forget to RESCAN) + - Commit + - Push + - Wait for a second review + - In case everything is fine, squash the commits into one. + See [GitHub - Prepare Pull Request](#github---prepare-pull-request). + Then, do a force push (`git push -f`). + + +## GitHub - After Pull Request Got Merged + +* Delete the branch locally. +* The branch on origin () is deleted by the maintainer having done the merge. + + +## Excursus: Git + +![](figures/ExcursusGit.png) + +Please see also [use gitk to understand git](https://lostechies.com/joshuaflanagan/2010/09/03/use-gitk-to-understand-git/) to understand the settings in git. + + +[gitk]: https://lostechies.com/joshuaflanagan/2010/09/03/use-gitk-to-understand-git/ diff --git a/docs/dev/graphics/AddingFeatureToYAML.PNG b/docs/dev/graphics/AddingFeatureToYAML.PNG deleted file mode 100644 index f2324e30c5..0000000000 Binary files a/docs/dev/graphics/AddingFeatureToYAML.PNG and /dev/null differ diff --git a/docs/dev/graphics/InheritanceOfInterfacesRelatedToTheRepository.png b/docs/dev/graphics/InheritanceOfInterfacesRelatedToTheRepository.png deleted file mode 100644 index 18f0c4a4dd..0000000000 Binary files a/docs/dev/graphics/InheritanceOfInterfacesRelatedToTheRepository.png and /dev/null differ diff --git a/docs/dev/graphics/NewFeatureEnum.PNG b/docs/dev/graphics/NewFeatureEnum.PNG deleted file mode 100644 index 007739b073..0000000000 Binary files a/docs/dev/graphics/NewFeatureEnum.PNG and /dev/null differ diff --git a/docs/dev/graphics/UsingDirective.PNG b/docs/dev/graphics/UsingDirective.PNG deleted file mode 100644 index 980ed2d9c9..0000000000 Binary files a/docs/dev/graphics/UsingDirective.PNG and /dev/null differ diff --git a/docs/dev/graphics/WineryConfigurationInterface.PNG b/docs/dev/graphics/WineryConfigurationInterface.PNG deleted file mode 100644 index 11735dd543..0000000000 Binary files a/docs/dev/graphics/WineryConfigurationInterface.PNG and /dev/null differ diff --git a/docs/dev/graphics/WinerysRenderingofNodetypes.png b/docs/dev/graphics/WinerysRenderingofNodetypes.png deleted file mode 100644 index cd54a25735..0000000000 Binary files a/docs/dev/graphics/WinerysRenderingofNodetypes.png and /dev/null differ diff --git a/docs/dev/graphics/WinerysTopologyModeler.png b/docs/dev/graphics/WinerysTopologyModeler.png deleted file mode 100644 index 5fd036def2..0000000000 Binary files a/docs/dev/graphics/WinerysTopologyModeler.png and /dev/null differ diff --git a/docs/dev/howtos/howto-log.md b/docs/dev/howtos/howto-log.md deleted file mode 100644 index cc8a8196fb..0000000000 --- a/docs/dev/howtos/howto-log.md +++ /dev/null @@ -1,19 +0,0 @@ -# How to log - -The `logback-test.xml` is the same for each project. -A change, however, needs to be synced manually. -Use following commands at git bash: - - find . -maxdepth 1 -type d -name "org.eclipse.*" -exec cp org.eclipse.winery.repository.rest/src/test/resources/logback-test.xml \{\}/src/test/resources/ \; - -## License - -Copyright (c) 2018 Contributors to the Eclipse Foundation - -See the NOTICE file(s) distributed with this work for additional -information regarding copyright ownership. - -This program and the accompanying materials are made available under the -terms of the Eclipse Public License 2.0 which is available at -http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0 -which is available at https://www.apache.org/licenses/LICENSE-2.0. diff --git a/docs/dev/howtos/index.md b/docs/dev/howtos/index.md deleted file mode 100644 index 7f70d56baf..0000000000 --- a/docs/dev/howtos/index.md +++ /dev/null @@ -1,18 +0,0 @@ -# How tos - -- [How to work with Angular](howto-angular.md) -- [How to do logging](howto-log.md) -- [How to work with the repository](howto-repository.md) -- [How to test within the repository](howto-test-repository.md) - -## License - -Copyright (c) 2018 Contributors to the Eclipse Foundation - -See the NOTICE file(s) distributed with this work for additional -information regarding copyright ownership. - -This program and the accompanying materials are made available under the -terms of the Eclipse Public License 2.0 which is available at -http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0 -which is available at https://www.apache.org/licenses/LICENSE-2.0. diff --git a/docs/dev/id-system.md b/docs/dev/id-system.md index c3ed488c45..7f0d9bcd7d 100644 --- a/docs/dev/id-system.md +++ b/docs/dev/id-system.md @@ -1,10 +1,25 @@ -# Winery's Id System + + + +# Winery's ID System The general idea behind the storage of Winery is that each entity comes with an id. The id is either self contained or references a parent id, where the element is nested in. All Ids inherit from `GenericId`. -![GenericId Hierarchy](graphics/GenericIdHierarchy.png) +![](figures/GenericIdHierarchy.png) The child `AdminId` is used for all administrative elements required for internal management. `DummyParentForGeneratedXSDRef` is required during the export of generated XML Schema Definitions due to the use of Winery's key/value properties. @@ -13,8 +28,7 @@ All other elements have "TOSCAElementId" as parent. ## AdminId -![AdminId Hierarchy](graphics/AdminIdHierarchy.png) -**Inheritance hierarchy of AdminId** +![](figures/AdminIdHierarchy.png) `NamespacesId` is used as container for a mapping file from namespace prefixes to namespaces. `TypesId` is the parent element of all types user can set. @@ -23,15 +37,13 @@ The inclusion of `PlanLanguages` is due to reuse of the class `AbstractTypesMana TOSCA does not restrict these enumerations. Therefore, Winery manages all known types for itself. - ## DefinitionsChildId -This Id class is used for all entities directly nested in a `TDefinitions` element. +This ID class is used for all entities directly nested in a `TDefinitions` element. They all have a namespace and an id attribute. This is ensured by `DefinitionsChildId`. -![ComponentId Hierarchy](graphics/ComponentIdHierarchy.png) -*Inheritance hierarchy of DefinitionsChildId** +![](figures/ComponentIdHierarchy.png) `EntityTemplateId` collects all Entity Templates directly nested in a Definitions element. As a result, the ids of NodeTemplates or RelationshipTemplates do not inherit from EntityTemplateId. @@ -47,17 +59,3 @@ Node Types and Relationship Types have the direct parent `TopologyGraphElementTy `GenericImportId` is an artificial entity. It is used to be able to store imports of an imported CSAR. These imports might be XSD definitions, but also WSDL files. - -## License - -Copyright (c) 2013-2018 Contributors to the Eclipse Foundation - -See the NOTICE file(s) distributed with this work for additional -information regarding copyright ownership. - -This program and the accompanying materials are made available under the -terms of the Eclipse Public License 2.0 which is available at -http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0 -which is available at https://www.apache.org/licenses/LICENSE-2.0. - -SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 diff --git a/docs/dev/index.md b/docs/dev/index.md index 30985f65c4..d3aeea0cc1 100644 --- a/docs/dev/index.md +++ b/docs/dev/index.md @@ -1,53 +1,43 @@ -# Eclipse Winery Developer Guide + -This document provides an index to all development guidelines and background information of winery. -- [ADR](../adr) - list of [architectural decision records](https://adr.github.io) showing which design decisions were taken during development of Winery -- [Branches](branches.md) - information on branches -- [CodeHeaders](CodeHeaders.md) - documentation about required code headers -- [UI Configuration](Configurationmanagment.md) - documentation how to configure the frontends -- IDE Setup - - IntelliJ Ultimate setup: [config/IntelliJ IDEA/README.md](config/IntelliJ%20IDEA/) - - Eclipse setup: [config/Eclipse/README.md](config/Eclipse/) -- [Encoding](Encoding.md) - information about how percent-encoding is used at Winery -- [Handling of Properties](property-handling.md) -- [How tos](howtos) - multiple howtos -- [ID system](id-system.md) -- [Projects](projects.md) - information on the projects -- [Property Handling](property-handling.md) -- [Recommended Reading](recommended-reading.md) -- [RepositoryLayout](RepositoryLayout.md) - documents the layout of the repository (stored as plain text files) -- [TOSCA-Mangement UI](TOSCA-Management.md) -- [REST](REST.md) - how Winery's REST API works -- [ToolChain](ToolChain) - GitHub workflow -- [Trouble Shooting](troubleshootings.md) -- [TOSCA](../tosca/) - notes on OASIS TOSCA -- [Extract Deployable Components from Chef Cookbooks](../user/CrawlerAndComponentExtractionForChefCookbooks.md) - Notes on crawler and extraction of components from chef cookbooks -- [DeployableComponents](../user/DeployableComponentsUsage.md) - Explanations on dockerfile component extraction tool - -To get started, go on at [ToolChain](ToolChain.md). - -As a user, continue at our [quick Start](../user/quickstart.md), which shows how to start how to work with Winery. - -## Quick Develop - -1. Clone the repository `git clone https://github.com/eclipse/winery && cd winery`. -2. If you are a Mac user, [install solidity natively](https://solidity.readthedocs.io/en/latest/installing-solidity.html#binary-packages). -3. Build the repository `mvn package -DskipTests` (skiping the tests for a faster build). -4. Continue your IDE setup: - - [IntelliJ Ultimate](config/IntelliJ%20IDEA/) - - [Eclipse](config/Eclipse/) +# Developer Guide -## License +This document provides an index to all development guidelines and background information of Eclipse Winery. -Copyright (c) 2013-2018 Contributors to the Eclipse Foundation - -See the NOTICE file(s) distributed with this work for additional -information regarding copyright ownership. - -This program and the accompanying materials are made available under the -terms of the Eclipse Public License 2.0 which is available at -http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0 -which is available at https://www.apache.org/licenses/LICENSE-2.0. - -SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 +- [Recommended Reading](recommended-reading.md) +- [Modules](modules.md) - Winery's module structure +- [Branches](branches.md) - How to branch +- [Source Code Headers](source-code-headers.md) - Documentation about required source code headers +- [REST API](rest.md) - How Winery's REST API works +- [Encoding](encoding.md) - Information about how encoding is used in Winery +- [ID System](id-system.md) - Winery's ID System +- [Repository Layout](repository-layout.md) - Documents the layout of the repository (stored as plain text files) +- [Property Handling](property-handling.md) +- [Configuration and Features](config.md) +- [TOSCA 1.0 Notes](tosca.md) +- IDE Setup + * IntelliJ IDEA (recommended): [config/IntelliJ IDEA](../config/IntelliJ%20IDEA/index.md) + * Eclipse: [config/Eclipse](../config/Eclipse/index.md) +- [Winery GitHub Workflow](github-workflow.md) + +## Getting Started + +* Clone the repository: `git clone https://github.com/eclipse/winery && cd winery`. +* Build Eclipse Winery: `mvn clean install -DskipTests` (skipping the tests for a faster build). +* Setup your IDE: + - IntelliJ IDEA (recommended): [config/IntelliJ IDEA](../config/IntelliJ%20IDEA/index.md) + - Eclipse: [config/Eclipse](../config/Eclipse/index.md) +* Get familiar with [Winery's GitHub workflow](github-workflow.md) diff --git a/docs/dev/projects.md b/docs/dev/modules.md similarity index 56% rename from docs/dev/projects.md rename to docs/dev/modules.md index 9e66c1ed5d..c1886d5e71 100644 --- a/docs/dev/projects.md +++ b/docs/dev/modules.md @@ -1,78 +1,81 @@ -# Projects + + + +# Winery's Module Structure + +> OUTDATED This section provides a short overview on all projects Winery consists of. -## Project org.eclipse.winery.common +`org.eclipse.winery.common` -This project contains classes used by the repository and topology modeler projects. It contains constants, the id -system, interface definitions for repository access and the datatype to manage Winery's extended key/value properties. +This project contains classes used by the repository and topology modeler projects. +It contains constants, the id system, interface definitions for repository access and the datatype to manage Winery's extended key/value properties. -## Project org.eclipse.winery.highlevelrestapi +`org.eclipse.winery.highlevelrestapi` This project contains an API to communicate with REST services. It provides an abstraction layer above Apache Commons HTTPClient. It is used by projects generated by the IA generator to upload compiled implementations as implementation artifacts. -## Project org.eclipse.winery.generators.ia +`org.eclipse.winery.generators.ia` This project contains the generator which generates a NodeType implementation based on a NodeType interface. -## Project org.eclipse.winery.model.csar.toscametafile +`org.eclipse.winery.model.csar.toscametafile` This project contains the model for the file "Tosca.meta". -## Project org.eclipse.winery.model.selfservice +`org.eclipse.winery.model.selfservice` This project contains the model for the self service portal. It is used by the Vinothek [BBKL14] to display user defined data. -## Project org.eclipse.winery.model.tosca +`org.eclipse.winery.model.tosca` This project contains a JAX B generated model of the XSD of OASIS TOSCA v1.0. The XSD hat to be modified to enable proper referencing and use. An Implementation Artifactmay carry a "name" attribute. The contents of properties of Boundary Definitions are processed in "lax" mode. -## Project org.eclipse.winery.repository +`org.eclipse.winery.repository` This is the heart of Winery. This project hosts the repository, where all entities of TOSCA are stored and managed. It realizes the components "Type, Template, and Artifact Management" and "Repository" (Figure 1). -## Project org.eclipse.winery.repository.client +`org.eclipse.winery.repository.client` -Whis project hosts a client using the REST API of the repository and offering a Java object based client to the +This project hosts a client using the REST API of the repository and offering a Java object based client to the Winery repository. -## Project org.eclipse.winery.repository.configuration +`org.eclipse.winery.repository.configuration` This project contains configurations used in the repository. Example are GitHub OAuth credentials. They must be configured in order to use them locally! -## Project org.eclipse.winery.repository.rest +`org.eclipse.winery.repository.rest` This project contains the REST resources. -## Project org.eclipse.winery.repository.ui +`Project org.eclipse.winery.repository.ui` This project contains the Angular ui for the repository. Here, the whole repository can be managed and configured. The repository-ui documentation is generated during `npm run build` process and can be found in `org.eclipse.winery.repository.ui/dist/doc/` folder. -## Project org.eclipse.winery.topologymodeler +`org.eclipse.winery.topologymodeler` This part of Winery enables modeling topologies graphically. It realizes the component "Topology Modeler" (Figure 1). - -## License - -Copyright (c) 2013-2018 Contributors to the Eclipse Foundation - -See the NOTICE file(s) distributed with this work for additional -information regarding copyright ownership. - -This program and the accompanying materials are made available under the -terms of the Eclipse Public License 2.0 which is available at -http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0 -which is available at https://www.apache.org/licenses/LICENSE-2.0. - -SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 diff --git a/docs/dev/presentations/topologymodeler-presentation/.gitignore b/docs/dev/presentations/topologymodeler-presentation/.gitignore deleted file mode 100644 index 913100fc4f..0000000000 --- a/docs/dev/presentations/topologymodeler-presentation/.gitignore +++ /dev/null @@ -1,3 +0,0 @@ -dist - -node_modules diff --git a/docs/dev/presentations/topologymodeler-presentation/Image.js b/docs/dev/presentations/topologymodeler-presentation/Image.js deleted file mode 100644 index 6732ce4e10..0000000000 --- a/docs/dev/presentations/topologymodeler-presentation/Image.js +++ /dev/null @@ -1,10 +0,0 @@ -import React from 'react' -import PropTypes from 'prop-types' -import styled, { withTheme } from 'styled-components' -import { fontSize, space, color } from 'styled-system' - -const css = key => props => props.theme[key] - -const Image = styled.img([], { - padding: '-3em' -}) diff --git a/docs/dev/presentations/topologymodeler-presentation/README.md b/docs/dev/presentations/topologymodeler-presentation/README.md deleted file mode 100644 index 293ea7164e..0000000000 --- a/docs/dev/presentations/topologymodeler-presentation/README.md +++ /dev/null @@ -1,53 +0,0 @@ - -# Topology Modeler Code Presentation - -This presentation can be useful for new developers that want to dive into the code of the topology modeler. - -## Development - -Don't forget: -```sh -npm install -``` - -To run the presentation deck in development mode: - -```sh -npm start -``` - -Edit the [`deck.mdx`](deck.mdx) file to edit the slides. - -## Exporting - -To build the presentation deck as static HTML: - -```sh -npm run build -``` - -To export a PDF: - -```sh -npm run pdf -``` - -To export an image of the title slide: - -```sh -npm run image -``` - -## Important Information - -All build commands add the generated files to the `/dist` folder. - -As of 31. October, 2018 the `npm run pdf` command does not seem to be able to render -the animation steps of the code-navigation library `mdx-deck-code-surfer` used in these slides. -Therefore it is highly recommended to use the `npm run build` command for now and view the static HTML version -of the presentation in a browser until this issue is resolved. -You can follow this issue [here](https://github.com/jxnblk/mdx-deck/issues/211). - -For more documentation see the [mdx-deck][] repo. - -[mdx-deck]: https://github.com/jxnblk/mdx-deck diff --git a/docs/dev/presentations/topologymodeler-presentation/codesnippets/backend.service.ts b/docs/dev/presentations/topologymodeler-presentation/codesnippets/backend.service.ts deleted file mode 100644 index 9db7f61777..0000000000 --- a/docs/dev/presentations/topologymodeler-presentation/codesnippets/backend.service.ts +++ /dev/null @@ -1,84 +0,0 @@ -@Injectable() -export class BackendService { - - readonly headers = new HttpHeaders().set('Accept', 'application/json'); - - configuration: TopologyModelerConfiguration; - serviceTemplateURL: string; - serviceTemplateUiUrl: string; - - endpointConfiguration = new Subject(); - endpointConfiguration$ = this.endpointConfiguration.asObservable(); - - private allEntities = new Subject(); - allEntities$ = this.allEntities.asObservable(); - - constructor(private http: HttpClient, - private alert: ToastrService, - private errorHandler: ErrorHandlerService) { - this.endpointConfiguration$.subscribe((params: TopologyModelerConfiguration) => { - if (!(isNullOrUndefined(params.id) && isNullOrUndefined(params.ns) && - isNullOrUndefined(params.repositoryURL) && isNullOrUndefined(params.uiURL))) { - - this.configuration = new TopologyModelerConfiguration( - params.id, - params.ns, - params.repositoryURL, - params.uiURL, - params.compareTo, - params.compareTo ? true : params.isReadonly, - params.parentPath, - params.elementPath - ); - - const url = this.configuration.parentPath + '/' - + encodeURIComponent(encodeURIComponent(this.configuration.ns)) + '/' - + this.configuration.id; - this.serviceTemplateURL = this.configuration.repositoryURL + '/' + url; - this.serviceTemplateUiUrl = this.configuration.uiURL + url; - - // All Entity types - this.requestAllEntitiesAtOnce().subscribe(data => { - // add JSON to Promise, WineryComponent will subscribe to its Observable - this.allEntities.next(data); - }); - } - }); - } - - /** - * Requests all entities together. - * We use forkJoin() to await all responses from the backend. - * This is required - * @returns data The JSON from the server - */ - private requestAllEntitiesAtOnce(): Observable { - if (this.configuration) { - return forkJoin( - this.requestGroupedNodeTypes(), - this.requestArtifactTemplates(), - this.requestTopologyTemplateAndVisuals(), - this.requestArtifactTypes(), - this.requestPolicyTypes(), - this.requestCapabilityTypes(), - this.requestRequirementTypes(), - this.requestPolicyTemplates(), - this.requestRelationshipTypes(), - this.requestNodeTypes() - ); - } - } - - /** - * Requests all grouped node types from the backend - * @returns {Observable} - */ - private requestGroupedNodeTypes(): Observable { - if (this.configuration) { - return this.http.get( - backendBaseURL + '/nodetypes?grouped&full', - { headers: this.headers } - ); - } - } -} \ No newline at end of file diff --git a/docs/dev/presentations/topologymodeler-presentation/codesnippets/canvas.component.html b/docs/dev/presentations/topologymodeler-presentation/codesnippets/canvas.component.html deleted file mode 100644 index d102400964..0000000000 --- a/docs/dev/presentations/topologymodeler-presentation/codesnippets/canvas.component.html +++ /dev/null @@ -1,42 +0,0 @@ -
-
-
- -
-
-
- - -
-
-
-
\ No newline at end of file diff --git a/docs/dev/presentations/topologymodeler-presentation/codesnippets/canvas.component.ts b/docs/dev/presentations/topologymodeler-presentation/codesnippets/canvas.component.ts deleted file mode 100644 index 495131cae7..0000000000 --- a/docs/dev/presentations/topologymodeler-presentation/codesnippets/canvas.component.ts +++ /dev/null @@ -1,55 +0,0 @@ -constructor(private jsPlumbService: JsPlumbService, - private eref: ElementRef, - private layoutDirective: LayoutDirective, - private ngRedux: NgRedux, - private actions: WineryActions, - private topologyRendererActions: TopologyRendererActions, - private zone: NgZone, - private hotkeysService: HotkeysService, - private renderer: Renderer2, - private alert: ToastrService, - private differs: KeyValueDiffers, - private backendService: BackendService, - private importTopologyService: ImportTopologyService, - private existsService: ExistsService, - private splitMatchService: SplitMatchTopologyService, - private reqCapService: ReqCapService, - private errorHandler: ErrorHandlerService) { - this.newJsPlumbInstance = this.jsPlumbService.getJsPlumbInstance(); - this.newJsPlumbInstance.setContainer('container'); - - this.subscriptions - .push(this.ngRedux - .select(state => state.wineryState.currentJsonTopology.nodeTemplates) - .subscribe(currentNodes => this.updateNodes(currentNodes))); - this.subscriptions - .push(this.ngRedux - .select(state => state.wineryState.currentJsonTopology.relationshipTemplates) - .subscribe(currentRelationships => this.updateRelationships(currentRelationships))); - this.subscriptions - .push(this.ngRedux - .select(state => state.topologyRendererState) - .subscribe(currentButtonsState => this.setRendererState(currentButtonsState))); - this.subscriptions - .push(this.ngRedux - .select(state => state.wineryState.currentNodeData) - .subscribe(currentNodeData => this.toggleMarkNode(currentNodeData))); - this.gridTemplate = new GridTemplate(100, false, false, 30); - this.subscriptions - .push(this.ngRedux - .select(state => state.wineryState.currentPaletteOpenedState) - .subscribe(currentPaletteOpened => this.setPaletteState(currentPaletteOpened))); - this.hotkeysService - .add(new Hotkey('mod+a', (event: KeyboardEvent): boolean => { - event.stopPropagation(); - this.allNodeTemplates.forEach(node => this.enhanceDragSelection(node.id)); - return false; // Prevent bubbling - }, undefined, 'Select all Node Templates')); - this.hotkeysService.add(new Hotkey('del', (event: KeyboardEvent): boolean => { - this.handleDeleteKeyEvent(); - return false; - }, undefined, 'Delete an element.')); - this.capabilities = new CapabilitiesModalData(); - this.requirements = new RequirementsModalData(); - this.importTopologyData = new ImportTopologyModalData(); -} diff --git a/docs/dev/presentations/topologymodeler-presentation/codesnippets/topology-renderer.component.html b/docs/dev/presentations/topologymodeler-presentation/codesnippets/topology-renderer.component.html deleted file mode 100644 index b3c81a2bd6..0000000000 --- a/docs/dev/presentations/topologymodeler-presentation/codesnippets/topology-renderer.component.html +++ /dev/null @@ -1,22 +0,0 @@ -
- - - - - - -
-
Diff Legend
-
    -
  • Green elements -> added
    • -
  • Yellow elements -> changed
    • -
  • Red elements -> removed
    • -
-
-
\ No newline at end of file diff --git a/docs/dev/presentations/topologymodeler-presentation/codesnippets/winery.component.html b/docs/dev/presentations/topologymodeler-presentation/codesnippets/winery.component.html deleted file mode 100644 index 41973f507f..0000000000 --- a/docs/dev/presentations/topologymodeler-presentation/codesnippets/winery.component.html +++ /dev/null @@ -1,31 +0,0 @@ - - - - - - -
-
- - -
- - - - - - -
\ No newline at end of file diff --git a/docs/dev/presentations/topologymodeler-presentation/codesnippets/winery.reducer.ts b/docs/dev/presentations/topologymodeler-presentation/codesnippets/winery.reducer.ts deleted file mode 100644 index 45bc21529b..0000000000 --- a/docs/dev/presentations/topologymodeler-presentation/codesnippets/winery.reducer.ts +++ /dev/null @@ -1,42 +0,0 @@ -export const WineryReducer = function( - lastState: WineryState = INITIAL_WINERY_STATE, - action: Action -): WineryState { - switch (action.type) { - - // ............................................ - // ............................................ - // ............................................ - // ............................................ - // .............MANY CASES HERE................ - // ............................................ - // ............................................ - // ............................................ - // ............................................ - // ............................................ - - // Example for changing a nodeTemplates name attribute - case WineryActions.CHANGE_NODE_NAME: - const newNodeName: any = (action).nodeNames - const indexChangeNodeName = lastState.currentJsonTopology.nodeTemplates - .map(el => el.id) - .indexOf(newNodeName.id) - - return { - // Spread Operator avoids using Object.assign({}) - ...lastState, - currentJsonTopology: { - ...lastState.currentJsonTopology, - nodeTemplates: lastState.currentJsonTopology.nodeTemplates.map( - nodeTemplate => - nodeTemplate.id === newNodeName.id - ? nodeTemplate.generateNewNodeTemplateWithUpdatedAttribute( - 'name', - newNodeName.newNodeName - ) - : nodeTemplate - ) - } - } - } -} diff --git a/docs/dev/presentations/topologymodeler-presentation/deck.mdx b/docs/dev/presentations/topologymodeler-presentation/deck.mdx deleted file mode 100644 index 890c6519f4..0000000000 --- a/docs/dev/presentations/topologymodeler-presentation/deck.mdx +++ /dev/null @@ -1,173 +0,0 @@ -import { Head, Button, Image } from 'mdx-deck' - -export { future as theme } from 'mdx-deck/themes' - -import { FullScreenCode, Invert, Split } from 'mdx-deck/layouts' - -import { CodeSurfer } from "mdx-deck-code-surfer" - - - Topology Modeler - - -export default Invert - -# Topology Modeler ---- -export default Invert - -## Components Structure ---- -export default Invert - - ---- - - - ---- - - - ---- - - - ---- - - - ---- -export default Invert - -## Redux - ---- -export default Invert - - - - - ---- -export default Invert - -## Redux in Angular -- UI Components dispatch the ***Actions*** -- ***Reducers*** take ***Actions*** and the existing ***State*** and return a ***new State*** -- UI Components subscribe to state changes and update automatically ---- -export default Invert - -## Topology Modeler State Graph - ---- - - - ---- - State"}, - { range: [25, 40], notes: "Spread Operator"} - ]} -/> - - ---- -export default Invert - -## Services - ---- - - - ---- - -# Questions? - ---- - -### Created with: - - - -### By: - - diff --git a/docs/dev/presentations/topologymodeler-presentation/img/Aufbau.png b/docs/dev/presentations/topologymodeler-presentation/img/Aufbau.png deleted file mode 100644 index 1a0b9eb35d..0000000000 Binary files a/docs/dev/presentations/topologymodeler-presentation/img/Aufbau.png and /dev/null differ diff --git a/docs/dev/presentations/topologymodeler-presentation/img/redux_state.png b/docs/dev/presentations/topologymodeler-presentation/img/redux_state.png deleted file mode 100644 index 13ee447cf8..0000000000 Binary files a/docs/dev/presentations/topologymodeler-presentation/img/redux_state.png and /dev/null differ diff --git a/docs/dev/presentations/topologymodeler-presentation/package.json b/docs/dev/presentations/topologymodeler-presentation/package.json deleted file mode 100644 index 9c46f6c690..0000000000 --- a/docs/dev/presentations/topologymodeler-presentation/package.json +++ /dev/null @@ -1,24 +0,0 @@ -{ - "private": true, - "version": "1.0.0", - "description": "Deck created with mdx-deck", - "scripts": { - "start": "mdx-deck deck.mdx", - "build": "mdx-deck build deck.mdx", - "pdf": "mdx-deck pdf deck.mdx", - "image": "mdx-deck screenshot deck.mdx", - "help": "mdx-deck" - }, - "keywords": [], - "author": "Brent Jackson", - "license": "MIT", - "devDependencies": { - "mdx-deck": "^1.6.7" - }, - "name": "topologymodeler-presentation", - "dependencies": { - "grid-styled": "^5.0.2", - "mdx-deck-code-surfer": "^0.4.1", - "raw-loader": "^0.5.1" - } -} diff --git a/docs/dev/presentations/topologymodeler-presentation/theme.js b/docs/dev/presentations/topologymodeler-presentation/theme.js deleted file mode 100644 index 6e4a4cf59f..0000000000 --- a/docs/dev/presentations/topologymodeler-presentation/theme.js +++ /dev/null @@ -1,23 +0,0 @@ -import theme from 'mdx-deck/themes' -import Image from './Image' - -export default { - ...theme, - // add a custom font - font: 'Roboto, sans-serif', - // custom colors - colors: { - text: '#fff', - background: '#242442', - link: '#faf' - }, - components: { - img: Image - } - - // Customize your presentation theme here. - // - // Read the docs for more info: - // https://github.com/jxnblk/mdx-deck/blob/master/docs/theming.md - // https://github.com/jxnblk/mdx-deck/blob/master/docs/themes.md -} diff --git a/docs/dev/property-handling.md b/docs/dev/property-handling.md index 2db09eda0a..dc89271f8f 100644 --- a/docs/dev/property-handling.md +++ b/docs/dev/property-handling.md @@ -1,6 +1,23 @@ -# Winery's property handling by example of policy type + policy template + -## Using the 'propertiesDefinitionComponent' in the frontend + +# Winery's Property Handling + +> Based Policy Type and Policy Template + +## Using the 'propertiesDefinitionComponent' in the Frontend In this section we will take a look at how the propertiesDefinition component can be used in the winery application. @@ -18,9 +35,9 @@ Therefor, open the file [`instance.service.ts`](https://github.com/OpenTOSCA/win Example(current winery implementation): ```typescript - case ToscaTypes.PolicyType: - subMenu = ['README', 'LICENSE', 'Language', 'Applies To', 'Properties Definition', 'Inheritance', 'Templates', 'Documentation', 'XML']; - break; +case ToscaTypes.PolicyType: + subMenu = ['README', 'LICENSE', 'Language', 'Applies To', 'Properties Definition', 'Inheritance', 'Templates', 'Documentation', 'XML']; + break; ``` This will create a clickable entry in the submenu. @@ -28,14 +45,14 @@ This will create a clickable entry in the submenu. Navigate to the file [`policyTypeRouter.module.ts`](https://github.com/OpenTOSCA/winery/blob/cdbce161aac69c5a861a9f2be3b7e7d809674186/org.eclipse.winery.repository.ui/src/app/wineryMainModules/policyTypes/policyTypeRouter.module.ts#L1) and add an entry to the 'children' array of the [`policyTypeRoutes`](https://github.com/OpenTOSCA/winery/blob/cdbce161aac69c5a861a9f2be3b7e7d809674186/org.eclipse.winery.repository.ui/src/app/wineryMainModules/policyTypes/policyTypeRouter.module.ts#L33) that will tell the router to load the correct component. The entry looks like this: -```typescript +```json {path: 'propertiesdefinition', component: PropertiesDefinitionComponent}, ``` This is necessary so the router will inject the 'propertiesDefinitionComponent' into the `` of the instance component when the 'Properties Definition' submenu is clicked. Further, clicking on the 'Properties Definition' submenu will append '/propertiesdefinition' to the end of the current URL and send a GET request to the URL when the submenu is clicked. The handling of received data as well as the data to be sent is done by the propertiesDefinitionComponent. -## Policy Type creation +## Policy Type Creation ### Winery GUI @@ -44,12 +61,11 @@ Further, clicking on the 'Properties Definition' submenu will append '/propertie - select one of the available namespaces or type in a new namespace - click the 'Add' button -Screenshot of the create modal -![create policy modal](graphics/create-policy-modal.PNG) +GUI Screenshot +![create policy modal](figures/CreatePolicyModal.png) The Winery application creates the policy type, however the policy type does not yet contain any properties. This can be observed in the xml representation of the policy type as well as in the GUI. - ### Resulting XML ```xml @@ -58,14 +74,14 @@ The Winery application creates the policy type, however the policy type does not ``` -## Property creation +## Property Creation ### Winery GUI - click on 'Properties Definition' in the sub header and choose the 'custom key/value' radio button. -GUI sceenshot: -![Custom key/value property](graphics/custom-key-value-property.PNG) +GUI Screenshot: +![](figures/CustomKeyValueProperty.png) - click on the 'Add' button - again, choose a fitting name @@ -73,11 +89,11 @@ GUI sceenshot: - click the 'Add' button GUI Screenshot -![Custom key/value property](graphics/custom-key-value-property-modal.PNG) +![](figures/CustomKeyValuePropertyModal.png) The application shows the newly created property in the table. -![KV property in table](graphics/custom-key-value-property-created.PNG) +![](figures/CustomKeyValuePropertyCreated.png) click the 'save' to save the property to the policy type. @@ -96,30 +112,29 @@ After adding a property to the policy type the resulting xml looks like this: ``` + ### Winery Backend The request to create a property is received by the [`OnPost()`](https://github.com/OpenTOSCA/winery/blob/0904a5c432364af22b68dc4d6d0769601e68b346/org.eclipse.winery.repository.rest/src/main/java/org/eclipse/winery/repository/rest/resources/entitytypes/properties/PropertiesDefinitionResource.java#L108) method in the [`PropertiesDefinitionResource.java`](https://github.com/OpenTOSCA/winery/blob/ustutt/org.eclipse.winery.repository.rest/src/main/java/org/eclipse/winery/repository/rest/resources/entitytypes/properties/PropertiesDefinitionResource.java) class. The following code fragment (starting at line 131) in the [`OnPost()`](https://github.com/OpenTOSCA/winery/blob/0904a5c432364af22b68dc4d6d0769601e68b346/org.eclipse.winery.repository.rest/src/main/java/org/eclipse/winery/repository/rest/resources/entitytypes/properties/PropertiesDefinitionResource.java#L108) is responsible for handling requests to create a custom key/value property: ```java else if (data.selectedValue == PropertiesDefinitionEnum.Custom) { - TEntityType et = this.parentRes.getEntityType(); - - // clear current properties definition - et.setPropertiesDefinition(null); - - // create winery properties definition and persist it - ModelUtilities.replaceWinerysPropertiesDefinition(et, data.winerysPropertiesDefinition); - String namespace = data.winerysPropertiesDefinition.getNamespace(); - NamespaceManager namespaceManager = RepositoryFactory.getRepository().getNamespaceManager(); - if (!namespaceManager.hasPrefix(namespace)) { - namespaceManager.addNamespace(namespace); - } - return RestUtils.persist(this.parentRes); - } -``` + TEntityType et = this.parentRes.getEntityType(); + // clear current properties definition + et.setPropertiesDefinition(null); + // create winery properties definition and persist it + ModelUtilities.replaceWinerysPropertiesDefinition(et, data.winerysPropertiesDefinition); + String namespace = data.winerysPropertiesDefinition.getNamespace(); + NamespaceManager namespaceManager = RepositoryFactory.getRepository().getNamespaceManager(); + if (!namespaceManager.hasPrefix(namespace)) { + namespaceManager.addNamespace(namespace); + } + return RestUtils.persist(this.parentRes); +} +``` -# Policy Template creation +## Policy Template Creation ### Winery GUI @@ -129,7 +144,7 @@ else if (data.selectedValue == PropertiesDefinitionEnum.Custom) { - click the 'Add' button GUI screenshot: -![policy template create modal](graphics/create-policy-template-modal.PNG) +![](figures/CreatePolicyTemplateModal.png) The created policy template has a property with the same key (prop1) as the policy type. This can be observed in the 'xml' tab as well as in the 'properties' tab. @@ -147,15 +162,18 @@ XML: ``` -Poperties tab: -![Policy template properties tab](graphics/custom-key-value-property-template.PNG) +Properties tab: +![](figures/CustomKeyValuePropertyTemplate.png) + ## Assigning a value + ### Winery GUI + Enter the value that should be assigned to the property in the input filed and click on save. Screenshot: -![Policy template properties tab](graphics/custom-key-value-property-template-value.PNG) +![](figures/CustomKeyValuePropertyTemplateValue.png) XML: ```xml @@ -172,26 +190,12 @@ XML: ``` ### Winery Backend -The request to add a value to a template property gets handled by the [`setProperties()`](https://github.com/OpenTOSCA/winery/blob/0904a5c432364af22b68dc4d6d0769601e68b346/org.eclipse.winery.repository.rest/src/main/java/org/eclipse/winery/repository/rest/resources/entitytemplates/PropertiesResource.java#L59) method in the [`PropertiesResource.java`](https://github.com/OpenTOSCA/winery/blob/0904a5c432364af22b68dc4d6d0769601e68b346/org.eclipse.winery.repository.rest/src/main/java/org/eclipse/winery/repository/rest/resources/entitytemplates/PropertiesResource.java#L59) class. +The request to add a value to a template property gets handled by the [`setProperties()`](https://github.com/OpenTOSCA/winery/blob/0904a5c432364af22b68dc4d6d0769601e68b346/org.eclipse.winery.repository.rest/src/main/java/org/eclipse/winery/repository/rest/resources/entitytemplates/PropertiesResource.java#L59) method in the [`PropertiesResource.java`](https://github.com/OpenTOSCA/winery/blob/0904a5c432364af22b68dc4d6d0769601e68b346/org.eclipse.winery.repository.rest/src/main/java/org/eclipse/winery/repository/rest/resources/entitytemplates/PropertiesResource.java#L59) class. ```java public Response setProperties(Map properties) { - this.template.getProperties().setKVProperties(properties); - return RestUtils.persist(this.res); - } + this.template.getProperties().setKVProperties(properties); + return RestUtils.persist(this.res); +} ``` - -## License - -Copyright (c) 2018 Contributors to the Eclipse Foundation - -See the NOTICE file(s) distributed with this work for additional -information regarding copyright ownership. - -This program and the accompanying materials are made available under the -terms of the Eclipse Public License 2.0 which is available at -http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0 -which is available at https://www.apache.org/licenses/LICENSE-2.0. - -SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 diff --git a/docs/dev/recommended-reading.md b/docs/dev/recommended-reading.md index 2c264c1f45..8e3ccf8175 100644 --- a/docs/dev/recommended-reading.md +++ b/docs/dev/recommended-reading.md @@ -1,18 +1,19 @@ -# Recommended programming literature + -* Simon Harrer et al. [Java by Comparison](http://java.by-comparison.com/). The Pgramatic Programmers, 2018. -* Joshua Bloch. [Effective Java, 3rd edition](https://www.safaribooksonline.com/library/view/effective-java-third/9780134686097/). Addison-Wesley Professional, 2017. - -## License - -Copyright (c) 2013-2018 Contributors to the Eclipse Foundation -See the NOTICE file(s) distributed with this work for additional -information regarding copyright ownership. +# Recommended Readings -This program and the accompanying materials are made available under the -terms of the Eclipse Public License 2.0 which is available at -http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0 -which is available at https://www.apache.org/licenses/LICENSE-2.0. - -SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 +* Simon Harrer et al. [Java by Comparison](http://java.by-comparison.com/). The Pragmatic Programmers, 2018. +* Joshua Bloch. [Effective Java, 3rd edition](https://www.safaribooksonline.com/library/view/effective-java-third/9780134686097/). Addison-Wesley Professional, 2017. diff --git a/docs/dev/RepositoryLayout.md b/docs/dev/repository-layout.md similarity index 65% rename from docs/dev/RepositoryLayout.md rename to docs/dev/repository-layout.md index 4439f10828..88edc06c81 100644 --- a/docs/dev/RepositoryLayout.md +++ b/docs/dev/repository-layout.md @@ -1,65 +1,77 @@ + + + # Eclipse Winery's Layout of Filebased Repository - [Typical layout](#typical-layout) - [Directory `imports`](#directory-imports) - * [Directory layout](#directory-layout) + * [Directory layout](#directory-layout-of-the-imports-directory) * [Handling of the extensibility parts](#handling-of-the-extensibility-parts) * [Special treatment of XSD definitions](#special-treatment-of-xsd-definitions) + [Knowing the definitions for a QName](#knowing-the-definitions-for-a-qname) -- [License](#license) Related architectural decision records are -[ADR-0001](../adr/0001-use-filesystem-as-backend) -[ADR-0002](../adr/0002-filesystem-folder-structure-using-type-namespace-id-structure) -. +[ADR-0001](../adr/0001-use-filesystem-as-backend.md) +[ADR-0002](../adr/0002-filesystem-folder-structure-using-type-namespace-id-structure.md). The general structure is `ROOT/s///`. Encoding is explained below. -Figure 1 shows the root directory of the filesystem and the directory layout for the NodeType NT1. +The figure below shows the root directory of the filesystem and the directory layout for the NodeType NT1. -![Filesystem Directory Layout](graphics/FilesystemDirectoryLayout.png) -**Figure 1: Filesystem directory layout** +![](figures/FilesystemDirectoryLayout.png) ## Encoding Encoding of directory and file names is done following [RFC 3986](https://tools.ietf.org/html/rfc3986#section-2.1). -This makes the structure consistent to the URL structure (cf. [URL structure in the developer guide](./#url-structure)). +This makes the structure consistent to the URL structure (cf. [REST API](rest.md#url-structure)). The URL encoding is necessary as some letter allowed in namespaces (e.g. `.`, `:`, `;`, `/`) and IDs are not allowed on all operating systems. IDs are [NCNames](https://www.w3.org/TR/xmlschema-2/#NCName), which are based on [XML 1.0 Names](https://www.w3.org/TR/2000/WD-xml-2e-20000814#NT-Name), which in turn allows [nearly all unicode characters](https://www.w3.org/TR/2000/WD-xml-2e-20000814#NT-Letter). Therefore, each namespace and ID is URL encoded when written to the filesystem and URL decoded when read from the filesystem. -More information on encoding is given at [Encoding](Encoding). +More information on encoding is given at [Encoding](encoding.md). ## Typical layout Typically, all definitions children have the path `componenttype/ns/id`. -The `component type` is nodetypes, relationshiptypes, servicetemplates, ... +The `component type` is `nodetypes`, `relationshiptypes`, `servicetemplates`, ... + `ns` is the namespace. It is stored encoded (see above). `id` is the XML id of the component. It is stored encoded (see above). -For instance, the NodeType "NT1" in the namespace "http://www.example.com/NodeTypes" is found in the directory -"nodetypes/http%3A%2F%2Fexample.com%2FNodeTypes/NT1/". +For instance, the NodeType `NT1` in the namespace `http://www.example.com/NodeTypes` is found in the directory `nodetypes/http%3A%2F%2Fexample.com%2FNodeTypes/NT1`. The content of the Definitions is stored in `NodeType.tosca`. -The resource-specific part typically is a file named .tosca . +The resource-specific part typically is a file named `.tosca`. It contains the Definitions XML file where all the data is stored. Files may be added to artifact templates. -Therefore, a subdirectory "files" is created in ROOT/artifacttemplates///. +Therefore, a subdirectory "files" is created in `ROOT/artifacttemplates//`. There, the files are stored. ## Directory `imports` This directory stores files belonging to a CSAR. -That means, when a definitions points to an external reference, the file has to be stored at the external location and not inside the repository +That means, when a definitions points to an external reference, the file has to be stored at the external location and not inside the repository. ### Directory layout of the imports directory @@ -71,19 +83,19 @@ Handling of that is currently not supported. `id` is a randomly generated id reflecting a single imported file. Inside the directory, a `.tosca` is stored containing the import element only. -In future, this can be used to contain the extensibility attributes, which are currently unsupported. +In the future, this can be used to contain the extensibility attributes, which are currently unsupported. `location` points to i) the local file or ii) to some external definition (absolute URL!) -Currently, ii is not implemented and the storage is used as mirror only to be able to +Currently, (ii) is not implemented and the storage is used as mirror only to be able to a) offer choice of known XML Schema definitions b) generate a UI for known XML Schemas (current idea: use http://sourceforge.net/projects/xsd2gui/) Typically, all definitions children have the path `type/ns/id`. We add `imports` before to group the imports. -The chosen ordering allows to present all available imports for a given import type +The chosen order allows to present all available imports for a given import type by just querying the contents of ``. ### Handling of the extensibility parts @@ -105,17 +117,3 @@ which provides a mapping of local names to id. For instance, if `theElement`is defined in `myxmldefs.xsd` (being the human-readable id of the folder), `index.properties` contains `theElement = myxmldefs.xsd`. The local name is sufficient as the namespace is given by the parent directory. - -## License - -Copyright (c) 2013-2017 Contributors to the Eclipse Foundation - -See the NOTICE file(s) distributed with this work for additional -information regarding copyright ownership. - -This program and the accompanying materials are made available under the -terms of the Eclipse Public License 2.0 which is available at -http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0 -which is available at https://www.apache.org/licenses/LICENSE-2.0. - -SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 diff --git a/docs/dev/CodeHeaders.md b/docs/dev/source-code-headers.md similarity index 67% rename from docs/dev/CodeHeaders.md rename to docs/dev/source-code-headers.md index e8b6e86ec8..8878212fe7 100644 --- a/docs/dev/CodeHeaders.md +++ b/docs/dev/source-code-headers.md @@ -1,4 +1,19 @@ -# About this file + + + +# Source Code Headers This file explains how to create and maintain copyright headers in source files. @@ -22,7 +37,7 @@ This file explains how to create and maintain copyright headers in source files. See also . -## Header for IntelliJ configuratoin +## IntelliJ IDEA Configuration ``` Copyright (c) $today.year Contributors to the Eclipse Foundation @@ -45,17 +60,3 @@ Just `Copyright` is enough to match existing headers. ## Full information Full information is available at: - -## License - -Copyright (c) 2013-2017 Contributors to the Eclipse Foundation - -See the NOTICE file(s) distributed with this work for additional -information regarding copyright ownership. - -This program and the accompanying materials are made available under the -terms of the Eclipse Public License 2.0 which is available at -, or the Apache Software License 2.0 -which is available at . - -SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 diff --git a/docs/dev/tosca-notes.md b/docs/dev/tosca-notes.md deleted file mode 100644 index 5f93a1de3d..0000000000 --- a/docs/dev/tosca-notes.md +++ /dev/null @@ -1,32 +0,0 @@ -# Nodes on OASIS TOSCA 1.0 - -## "name" vs. "id" at entities - -Some entities carry a name, some an id and some both. -A justification is available at [TOSCA issue 47](https://issues.oasis-open.org/browse/TOSCA-47). - -## Possible attachments of artifacts - -Implementation Artifacts (IAs) may be attached at - -* NodeType/Interfaces/Interface/Operation (via IA's operation attribute) -* NodeType/Interfaces/Interface/Operation -* NodeTemplate - -Deployment Artifacts (DAs) may be attached at -* NodeType -* NodeTemplate - -## License - -Copyright (c) 2013-2018 Contributors to the Eclipse Foundation - -See the NOTICE file(s) distributed with this work for additional -information regarding copyright ownership. - -This program and the accompanying materials are made available under the -terms of the Eclipse Public License 2.0 which is available at -http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0 -which is available at https://www.apache.org/licenses/LICENSE-2.0. - -SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 diff --git a/docs/dev/tosca.md b/docs/dev/tosca.md new file mode 100644 index 0000000000..9f4a7b8a55 --- /dev/null +++ b/docs/dev/tosca.md @@ -0,0 +1,34 @@ + + + +# Notes on TOSCA 1.0 + +## "name" vs. "id" + +Some entities carry a name, some an id and some both. +A justification is available at [TOSCA issue 47](https://issues.oasis-open.org/browse/TOSCA-47). + +## Possible attachments of artifacts + +Implementation Artifacts (IAs) may be attached at: + +* NodeType/Interfaces/Interface/Operation (via IA's operation attribute) +* NodeType/Interfaces/Interface/Operation +* NodeTemplate + +Deployment Artifacts (DAs) may be attached at: + +* NodeType +* NodeTemplate diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index 8eb8a2b7c6..0000000000 --- a/docs/index.md +++ /dev/null @@ -1,26 +0,0 @@ -# Eclipse Winery - -This is the main index page of Eclipse Winery. -Organizational information is provided at the [eclipse.org page](http://eclipse.org/winery/). - -Information for users and developers is found at the following items: - -- [UserGuide](user/) - a guide for users -- [DeveloperGuide](dev/) - a guide for developers -- [TOSCA](tosca/) - notes on OASIS TOSCA -- [Architectural Decisions](adr/) - documentation of ADRs -- [CONTRIBUTING.md](https://github.com/eclipse/winery/blob/master/CONTRIBUTING.md) - explains how to contribute to Eclipse Winery - -## License - -Copyright (c) 2013-2017 Contributors to the Eclipse Foundation - -See the NOTICE file(s) distributed with this work for additional -information regarding copyright ownership. - -This program and the accompanying materials are made available under the -terms of the Eclipse Public License 2.0 which is available at -http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0 -which is available at https://www.apache.org/licenses/LICENSE-2.0. - -SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000000..feb8f0c190 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,74 @@ +.. Copyright (c) 2020 Contributors to the Eclipse Foundation + +.. See the NOTICE file(s) distributed with this work for additional +.. information regarding copyright ownership. + +.. This program and the accompanying materials are made available under the +.. terms of the Eclipse Public License 2.0 which is available at +.. http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0 +.. which is available at https://www.apache.org/licenses/LICENSE-2.0. + +.. SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 + + +Eclipse Winery +############## + +This is the main documentation of Eclipse Winery. + +Organizational information is provided at the `eclipse.org page `_. + +Eclipse Winery is a web-based environment to graphically model TOSCA topologies and plans managing these topologies. +The environment includes a type and template management component to offer creation and modification of all elements defined in the TOSCA specification. +All information is stored in a repository, which allows importing and exporting using the TOSCA packaging format. + +**Are you tired of maintaining your TOSCA files manually by just using a text editor?** + +Use Eclipse Winery as an usability layer on top to maintain your TOSCA files (XML or YAML) in a graphical and intuitive user interface. +Eclipse Winery provides a graphical web-editor with which you can create and maintain all TOSCA entities. +Thereby, Eclipse Winery stores all TOSCA entities in a defined folder structure that fosters the reusability of TOSCA types. +Eclipse Winery validates and stores all TOSCA entities in the syntax defined in the standard. + +Further, the graph-based representation of TOSCA topologies in Eclipse Winery provides a quick overview of the entire system and offers a communication basis for the cooperation with other parties. +It therefore offers a quicker introduction to modeling with TOSCA and provides newcomers with necessary guidelines. + +.. list-table:: + :widths: 30 70 + + * - **Demo** + - `Video `_ + * - **Getting Started** + - :ref:`User Guide` + * - **Licence** + - EPL-2.0 OR Apache-2.0 + * - **Maintainer(s)** + - `Eclipse Winery Contributors `_ + +.. toctree:: + :maxdepth: 1 + :caption: Contents: + + user/index.rst + dev/index.md + tosca/index.rst + adr/index.md + How to Contribute + + +Getting support for Eclipse Winery +********************************** + +* In case you have concrete issues, please open an issue at ``_. +* There is a mailing list available at ``_. +* General information about Eclipse Winery is available at ``_. + + +License +******* + +Copyright (c) 2013-2020 Contributors to the Eclipse Foundation. + +See the NOTICE file(s) distributed with this work for additional information regarding copyright ownership. +This program and the accompanying materials are made available under the terms of the Eclipse Public License 2.0 which is available at http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0 which is available at https://www.apache.org/licenses/LICENSE-2.0. + +SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 diff --git a/docs/inject-interaction.plantuml b/docs/inject-interaction.plantuml deleted file mode 100644 index 4ca3c1683b..0000000000 --- a/docs/inject-interaction.plantuml +++ /dev/null @@ -1,46 +0,0 @@ -Onlineeditor: https://www.planttext.com/ - -Copyright (c) 2017 Contributors to the Eclipse Foundation - -See the NOTICE file(s) distributed with this work for additional -information regarding copyright ownership. - -This program and the accompanying materials are made available under the -terms of the Eclipse Public License 2.0 which is available at -http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0 -which is available at https://www.apache.org/licenses/LICENSE-2.0. - -SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 - - -@startuml - -'skinparam monochrome true -'Chooses LightGray as background color -'We're better off with manual setting - -skinparam class { - BackgroundColor White - ArrowColor Black - BorderColor Black - LegendBackgroundColor White -} - -skinparam stereotypeCBackgroundColor LightGray - -skinparam noteBackgroundColor White -skinparam noteBorderColor Black - -'required for SVG -skinparam defaultFontName sans-serif - - -UI -> Container: CSAR -Container -> Winery: import -Winery -> Container: serviceTemplateURL -Container -> UI: serviceTemplateURL -UI -> Winery_serviceTemplateURL_injector_options -Winery_serviceTemplateURL_injector_options -> UI: topundma -UI -> Winery_serviceTemplateURL_injector_replace: replacements - -@enduml diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000000..c0fef69fc8 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,46 @@ +@ECHO OFF +REM Copyright (c) 2020 Contributors to the Eclipse Foundation +REM +REM See the NOTICE file(s) distributed with this work for additional +REM information regarding copyright ownership. +REM +REM This program and the accompanying materials are made available under the +REM terms of the Eclipse Public License 2.0 which is available at +REM http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0 +REM which is available at https://www.apache.org/licenses/LICENSE-2.0. +REM +REM SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000000..e0e1fdabc9 Binary files /dev/null and b/docs/requirements.txt differ diff --git a/docs/third-party-content/third-party-libraries.xlsx b/docs/third-party/third-party-libraries.xlsx similarity index 100% rename from docs/third-party-content/third-party-libraries.xlsx rename to docs/third-party/third-party-libraries.xlsx diff --git a/docs/tosca/.gitignore b/docs/tosca/.gitignore deleted file mode 100644 index 664db108e9..0000000000 --- a/docs/tosca/.gitignore +++ /dev/null @@ -1,2 +0,0 @@ -*.png -*.svg diff --git a/docs/tosca/TOSCA-v1.0-os-attributes.xlsx b/docs/tosca/TOSCA-v1.0-os-attributes.xlsx deleted file mode 100644 index fb03f8cdae..0000000000 Binary files a/docs/tosca/TOSCA-v1.0-os-attributes.xlsx and /dev/null differ diff --git a/docs/tosca/index.md b/docs/tosca/index.md deleted file mode 100644 index 31857081f5..0000000000 --- a/docs/tosca/index.md +++ /dev/null @@ -1,47 +0,0 @@ -# Notes on TOSCA - -## Recommended reading - -1. [Portable Cloud Services Using TOSCA by Tobias Binz, Gerd Breiter, Frank Leymann, Thomas Spatzier. IEEE Internet Computing 16(03):80--85 (May 2012)](http://doi.org/10.1109/MIC.2012.43) - short overview -2. [TOSCA: Portable Automated Deployment and Management of Cloud Applications by Tobias Binz, Uwe Breitenbücher, Oliver Kopp, Frank Leymann, Advanced Web Services2014](http://doi.org/10.1007/978-1-4614-7535-4_22) - longer overview -3. [Topology and Orchestration Specification for Cloud Applications (TOSCA) Primer Version 1.0](http://docs.oasis-open.org/tosca/tosca-primer/v1.0/tosca-primer-v1.0.html) - offical primer (regard it as tutorial) -4. [Topology and Orchestration Specification for Cloud Applications Version 1.0](http://docs.oasis-open.org/tosca/TOSCA/v1.0/os/TOSCA-v1.0-os.html) - offical specification -5. [TOSCA Simple Profile in YAML Version 1.1](http://docs.oasis-open.org/tosca/TOSCA-Simple-Profile-YAML/v1.1/TOSCA-Simple-Profile-YAML-v1.1.html) - the simple profile in YAML. - -See for a list of publications in the OpenTOSCA ecosystem. - - -## TOSCA 1.0 XML - -- [class diagram](TOSCA-v1.0-os-class-diagram.pdf) ([PlantUML source](TOSCA-v1.0-os-class-diagram.plantuml)) - - -## TOSCA 1.0 YAML - -- [class diagram](TOSCA-Simple-Profile-in-YAML-v1.0-os-class-diagram.pdf), [PlantUML source](TOSCA-Simple-Profile-in-YAML-v1.0-os-class-diagram.plantuml) - - -### Example YAML files - -* -* - - -## Available TOSCA implementations - -Available implementations are tracked by OASIS at . - - -## License - -Copyright (c) 2014-2017 Contributors to the Eclipse Foundation - -See the NOTICE file(s) distributed with this work for additional -information regarding copyright ownership. - -This program and the accompanying materials are made available under the -terms of the Eclipse Public License 2.0 which is available at -http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0 -which is available at https://www.apache.org/licenses/LICENSE-2.0. - -SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 diff --git a/docs/tosca/index.rst b/docs/tosca/index.rst new file mode 100644 index 0000000000..479bf2ead6 --- /dev/null +++ b/docs/tosca/index.rst @@ -0,0 +1,50 @@ +.. Copyright (c) 2020 Contributors to the Eclipse Foundation + +.. See the NOTICE file(s) distributed with this work for additional +.. information regarding copyright ownership. + +.. This program and the accompanying materials are made available under the +.. terms of the Eclipse Public License 2.0 which is available at +.. http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0 +.. which is available at https://www.apache.org/licenses/LICENSE-2.0. + +.. SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 + +.. _tosca: + + +Notes on TOSCA +************** + +Recommended Readings +==================== + +#. `Portable Cloud Services Using TOSCA. In: IEEE Internet Computing (2012) `_ - Short overview. +#. `TOSCA: Portable Automated Deployment and Management of Cloud Applications. In: Advanced Web Services (2014) `_ - Longer overview. +#. `TOSCA Simple Profile in YAML Version 1.3 `_ - The simple profile in YAML. + +See ``_ for a list of publications in the OpenTOSCA ecosystem. + +TOSCA 1.3 YAML +============== + +* `Official Specification `_ +* :download:`Class Diagram ` +* :download:`PlantUML ` + +TOSCA 1.0 XML (Deprecated) +========================== + +* `Official Specification `_ +* :download:`Class Diagram ` +* :download:`PlantUML ` + +Example TOSCA YAML Files +======================== + +* `Project RADON `_ + +Available TOSCA Implementations +=============================== + +* ``_ diff --git a/docs/tosca/startplantuml.bat b/docs/tosca/startplantuml.bat deleted file mode 100644 index ffdb260080..0000000000 --- a/docs/tosca/startplantuml.bat +++ /dev/null @@ -1,19 +0,0 @@ -:: Copyright (c) 2013-2014 Contributors to the Eclipse Foundation -:: -:: See the NOTICE file(s) distributed with this work for additional -:: information regarding copyright ownership. -:: -:: This program and the accompanying materials are made available under the -:: terms of the Eclipse Public License 2.0 which is available at -:: http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0 -:: which is available at https://www.apache.org/licenses/LICENSE-2.0. -:: -:: SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 - -@echo off -echo Generating SVG... -SET PLANTUML=C:\Users\Oliver\BTSync\plantuml.jar -java -jar %PLANTUML% -tsvg TOSCA-v1.0-os-class-diagram.plantuml -echo Generating PDF... -inkscape -z -D --file=TOSCA-v1.0-os-class-diagram.svg --export-pdf=TOSCA-v1.0-os-class-diagram.pdf -echo Done diff --git a/docs/user/FAQ.md b/docs/user/FAQ.md deleted file mode 100644 index b79eff50e5..0000000000 --- a/docs/user/FAQ.md +++ /dev/null @@ -1,71 +0,0 @@ -# FAQ - -## Q: What is TOSCA? - -A: The Topology and Orchestration Specification for Cloud Applications (TOSCA) is an OASIS standard to describe the deployment and management of applications in a portable manner. -Based on standard-compliant TOSCA runtimes, such as the OpenTOSCA ecosystem, the deployment and management can be automated. -For more details see our [Notes on TOSCA](https://eclipse.github.io/winery/tosca/). - -## Q: What is a CSAR? - -A: Cloud Service Archive (CSAR) is a packaging format defined by the TOSCA specification, which enables to bundle modeled TOSCA components in a self-contained manner. -Besides the TOSCA elements, the executable artifacts are packed as well. -In winery, you can model a service template and export it as a CSAR. -This CSAR can be loaded into the OpenTOSCA container in order to deploy your application. - -## Q: How can I start the OpenTOSCA ecosystem? - -A: You can start the ecosystem by simply using Docker Compose or by using installation scripts. -Please refer to the [OpenTOSCA Getting Started guide](https://www.opentosca.org/sites/use_opentosca.html) for more details. - -## Q: Is there an open repository for TOSCA types? - -A: Yes! We provide a [github repository](https://github.com/OpenTOSCA/tosca-definitions-public) compatible to Winery, which contains several service templates, node types, etc. -To use this repository with a Winery docker container, please refer to the corresponding [configuration instructions](https://github.com/OpenTOSCA/opentosca-docker#how-to-clone-a-private-tosca-definitions-repository-to-be-used-with-winery). - -## Q: Where can I find a quick start guide to model node types? - -A: You can find a Winery quick start guide about modeling node types in our [Quickstart](quickstart.md). - -## Q: How can I export my modeled application as a CSAR? - -A: Select the tab *Services Templates*. -From the listed service templates, select the one you want to export. -In the detailed view, press *Export* and then choose the option *CSAR (XML)*. - -## Q: My modeled node type became the suffix name *wip*? what does this mean? - -A: This means your node type has a *work in progress* (wip) version. That is, this node type can and might be changed. -Once you are done, you can do a release of your node type. In this way, Winery will not allow changes in the (released) node type anymore. - -## Q: How can I release a node type? - -A: Select the tab *Node Types*. -From the listed node types, select the one you want to release. -In the detailed view, press *Versions* and then choose the option *Release management version*. - -## Q: On Mac OS X, I can neither delete a node template nor a relationship template. - -A: Select the node template (or the relationship template) and press fn + backspace. - -## Q: Where can I get more help? - -A: If you need support, contact us at *opentosca@iaas.uni-stuttgart.de*. - -## Q: How can I contribute to Winery? - -A: Please see the [contributing guide](https://github.com/eclipse/winery/blob/master/CONTRIBUTING.md). - -## License - -Copyright (c) 2018 Contributors to the Eclipse Foundation - -See the NOTICE file(s) distributed with this work for additional -information regarding copyright ownership. - -This program and the accompanying materials are made available under the -terms of the Eclipse Public License 2.0 which is available at -http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0 -which is available at https://www.apache.org/licenses/LICENSE-2.0. - -SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 diff --git a/docs/user/Splitting.md b/docs/user/Splitting.md deleted file mode 100644 index afd2d7b9ce..0000000000 --- a/docs/user/Splitting.md +++ /dev/null @@ -1,61 +0,0 @@ -# Splitting and Matching - -## Splitting Functionality - -In the topologymodeler target labels can be shown/hidden by "Target Locations" - The Target Location assigned - to a Node Template determines the service templates serving as cloud provider repositories, which should be searched - for a suitable host. The namespace of all cloud provider repositories must start with "http://www.opentosca.org/providers/". - To distinguish between different repositories the namespace must end with the target label, e.g. - "../IAAS" or "../Amazon/PaaS". The target labels are not case sensitive. - -A prerequisite for a splitting is the assignment of requirements and capabilities to all Node Templates in the -Topology Template, which should be split, and the Node Templates in the repositories. -The latter just have requirements assigned because they form the lowest level of the topology. -The naming convention for the mapping of Reqs and Caps are: - - - Requirement: ReqCanHostxyz - - Capability: CapCanHostxyz - -By clicking the "Split" button first the topology is split according to the assigned labels (nodes with -hostedOn-predecessors with different labels are duplicated) and second the host nodes from the provider repositories -are matched. -For this, lower level nodes can be removed and replaced. - -The split as well as the matched topology are persistently stored with an attached "-split" and "-matched" in -the Service Template Id. - -![splitting](graphics/splitting.png) - -## Matching Functionality - -Additional and based on the split function a match function is added to the winery. -A topology is inspected if open requirements are contained. A open requirement is a requirement for which no relationship -to a node template exists which has the matching capability assigned. -In case open requirements are found, the provider repositories are searched for suitable matching candidates. -A matching candidate can be a single node, but also a whole topology fragment. -The matching can be done to new hosts, but also to dat resources, etc. -That means, based on the matching capabilities matching candidates are found and based on the requirements and capabilities -and their inheritance hierarchies the correct relationship types are determined. - -To use this functionality a strict type and inheritance system is important. -These are the rules: - - Each capability type with the semantic, that it acts as host/container has to be derived from the capability "Container" - - Each capability type with the semantic, that it acts as a endpoint has to be derived from the capability "Endpoint" - - The two default relationship types "hostedOn" and "connectsTo" should ne available and requires as valid target the - capability "Container" oder "Endpoint" - -By using this function a vertical as well as horizontal matching is possible. - -## License - -Copyright (c) 2017 Contributors to the Eclipse Foundation - -See the NOTICE file(s) distributed with this work for additional -information regarding copyright ownership. - -This program and the accompanying materials are made available under the -terms of the Eclipse Public License 2.0 which is available at -http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0 -which is available at https://www.apache.org/licenses/LICENSE-2.0. - -SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 diff --git a/docs/user/VersionManagement.md b/docs/user/VersionManagement.md deleted file mode 100644 index dc573fcb00..0000000000 --- a/docs/user/VersionManagement.md +++ /dev/null @@ -1,35 +0,0 @@ -# Update Management of Node Templates in Topology Modeler - -This guide shows an overview of how to update a Node Template in a Topology Template. - - -## Steps to update a Node Template - -User will be informed with a *red exclamation mark* when there's any new versions available for a node template. -![NewVersionAvailable](graphics/versionManagement/NewVersionAvailable.jpeg) - -Select the version to update. -![VersionSelection](graphics/versionManagement/VersionSelection.jpeg) - - -A table with new, removed and resolved Properties will be shown. A new *Property* and a removed *Property* can be selected so that the value will be transferred. -![PropertiesToMap](graphics/versionManagement/PropertiesToMap.png) - -Now the Node Template is updated in the Topology Template. New Properties are available and values are transferred. -![UpdatedNodeTemplate](graphics/versionManagement/UpdatedNodeTemplate.jpeg) - -To confirm the update above, save the topology template. - -## License - -Copyright (c) 2019 Contributors to the Eclipse Foundation - -See the NOTICE file(s) distributed with this work for additional -information regarding copyright ownership. - -This program and the accompanying materials are made available under the -terms of the Eclipse Public License 2.0 which is available at -http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0 -which is available at https://www.apache.org/licenses/LICENSE-2.0. - -SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 diff --git a/docs/user/faq.rst b/docs/user/faq.rst new file mode 100644 index 0000000000..e8461f465a --- /dev/null +++ b/docs/user/faq.rst @@ -0,0 +1,84 @@ +.. Copyright (c) 2020 Contributors to the Eclipse Foundation + +.. See the NOTICE file(s) distributed with this work for additional +.. information regarding copyright ownership. + +.. This program and the accompanying materials are made available under the +.. terms of the Eclipse Public License 2.0 which is available at +.. http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0 +.. which is available at https://www.apache.org/licenses/LICENSE-2.0. + +.. SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 + + +Frequently Asked Questions (FAQ) +################################ + +Q: What is TOSCA? +***************** + +A: The Topology and Orchestration Specification for Cloud Applications (TOSCA) is an OASIS standard to describe the deployment and management of applications in a portable manner. +Based on standard-compliant TOSCA runtimes, such as the OpenTOSCA ecosystem, the deployment and management can be automated. +For more details see our :ref:`notes on TOSCA`. + +Q: What is a CSAR? +****************** + +A: Cloud Service Archive (CSAR) is a packaging format defined by the TOSCA specification, which enables to bundle modeled TOSCA components in a self-contained manner. +Besides the TOSCA elements, the executable artifacts are packed as well. +In winery, you can model a service template and export it as a CSAR. +This CSAR can be loaded into the OpenTOSCA container in order to deploy your application. + +Q: How can I start the OpenTOSCA ecosystem? +******************************************* + +A: You can start the ecosystem by simply using Docker Compose or by using installation scripts. +Please refer to the `OpenTOSCA getting started guide `_ for more details. + +Q: Is there an open repository for TOSCA types? +*********************************************** + +A: Yes! We provide a `GitHub repository `_ compatible to Winery, which contains several service templates, node types, etc. +To use this repository with a Winery docker container, please refer to the corresponding configuration instructions in the user guide. + +Q: Where can I find a quick start guide to model Node Types? +************************************************************ + +A: You can find a Winery quick start guide about modeling node types in our :ref:`user guide`. + +Q: How can I export my modeled application as a CSAR? +***************************************************** + +A: Select the tab *Services Templates*. +From the listed service templates, select the one you want to export. +In the detailed view, press *Export* and then choose the option *CSAR (XML)*. + +Q: My modeled Node Type got the suffix name `wip` what does this mean? +********************************************************************** + +A: This means your node type has a *work in progress* (wip) version. +That is, this node type can and might be changed. +Once you are done, you can do a release of your node type. +In this way, Winery will not allow changes in the (released) node type anymore. + +Q: How can I release a Node Type? +********************************* + +A: Select the tab *Node Types*. +From the listed node types, select the one you want to release. +In the detailed view, press *Versions* and then choose the option *Release management version*. + +Q: On Mac OS X, I can neither delete a Node Template nor a Relationship Template. +********************************************************************************* + +A: Select the node template (or the relationship template) and press fn + backspace. + +Q: Where can I get more help? +***************************** + +A: If you need support, contact us at *opentosca@iaas.uni-stuttgart.de*. + +Q: How can I contribute to Winery? +********************************** + +A: Please see the `contributing guide `_. diff --git a/docs/user/ComplianceChecking.md b/docs/user/features/compliance-checking.md similarity index 78% rename from docs/user/ComplianceChecking.md rename to docs/user/features/compliance-checking.md index bbc80f7bca..1d7aa3c777 100644 --- a/docs/user/ComplianceChecking.md +++ b/docs/user/features/compliance-checking.md @@ -1,3 +1,18 @@ + + + # Topology Compliance Checking The Topology Compliance Checking of Winery enables to describe restrictions, constraints, and requirements for Topology Templates in form of reusable topology-based Compliance Rules. @@ -13,7 +28,7 @@ A Topology Element 𝑒1 can be matched to a Topology Element 𝑒2 if the type An example of a valid Compliance Rule is shown here: -![complianceRule.PNG](graphics/compliance-checking/complianceRule.PNG) +![](figures/ComplianceRule.png) The Identifier consists of a single Node Template with a property "DataType: PersonalData". As the Required Structure contains a Node Template of the same type and with a property with equivalent key and value it exists a matching mapping. Hence, the compliance rule is valid. @@ -23,7 +38,7 @@ Hence, the compliance rule is valid. The detection of relevant compliance areas in Topology Models is based on the detection of subgraph isomorphisms which also takes the types and attributes of Topology Elements forming the Topology Model into account. An example of a Compliance Rule that is **detected** and **satisfied** for a Topology Template is shown here: -![complianceRulesDetection.png](graphics/compliance-checking/complianceRuleDetection.PNG) +![](figures/ComplianceRuleDetection.png) **Detected** means: A Compliance Rule is detected if there is at least on matching mapping from the Identifier to the Topology Model. @@ -34,11 +49,11 @@ An example of a Compliance Rule that is **detected** and **satisfied** for a Top In the following, a simple example is given describing how to use Topology Compliance Checking. We will describe how to create your first topology-based Compliance Rule and how to check the compliance of Topology Templates based on existing Compliance Rules. -Note: You should have a look at the [[Winery User Guide]](http://eclipse.github.io/winery/UserGuide) before reading this tutorial to get all the basic knowledge about Winery. +Note: You should have a look at the [Winery User Guide](http://eclipse.github.io/winery) before reading this tutorial to get all the basic knowledge about Winery. ### Step 1: Start Winery -If you need help getting Winery up and running have a look at the [[Quickstart Guide]](http://eclipse.github.io/winery/user/quickstart.html) +If you need help getting Winery up and running have a look at the [Quickstart Guide](http://eclipse.github.io/winery) ### Step 2: Create a compliance rule @@ -46,7 +61,7 @@ First, we need to create a Compliance Rule. Select the tab "Other Elements" => "Compliance Rules" to get an overview of the existing Compliance Rules in the repository. Click on "Add new" to create a new Compliance Rule. A modal to add a new Compliance Rule appears: -![createComplianceRule.PNG](graphics/compliance-checking/createComplianceRule.PNG) +![](figures/CreateComplianceRule.png) 1. Enter a name for your rule e.g., "PersonalDataComplianceRule" 2. Choose a namespace for the Compliance Rule. @@ -59,7 +74,7 @@ This means each Compliance Rule defined for a certain namespace automatically ap After the previous steps a Compliance Rule with empty Identifier and Required Structure is created. Subsequent, the Topology Modeler of Winery can be used to model the Identifier and Required Structure of the Compliance Rule: -![step2.PNG](graphics/compliance-checking/step2.PNG) +![](figures/CreateComplianceRule.png) 1. Choose Tab "Identifier" or "Required Structure" 2. Click "Open Editor" @@ -69,7 +84,7 @@ An exemplary Compliance Rule that is concerned with the storage of personal user Identifier | Required Structure :-------------------------:|:-------------------------: -![identifier_modeler.PNG](graphics/compliance-checking/identifier_modeler.PNG) | ![required-structure.PNG](graphics/compliance-checking/required-structure.PNG) +![](figures/IdentifierModeler.png) | ![](figures/RequiredStructure.png) The motivation for this Compliance Rule is to ensure that all MySQL databases that store personal data are hosted on a specific OpenStack Component with the HypervisorEndpoint: "192.168.4.3". @@ -90,7 +105,7 @@ An example of a Topology Template that does not satisfy the Compliance Rule defi Topology Template | Result :-------------------------:|:-------------------------: -![unsatisfied-topology.PNG](graphics/compliance-checking/unsatisfied-topology.PNG) | ![unsatisfied.PNG](graphics/compliance-checking/unsatisfied.PNG) +![](figures/UnsatisfiedTopology.png) | ![](figures/Unsatisfied.png) The left side shows the modeled Topology Template. The specified property HypervisorEndpoint: "192.168.0.0" of the OpenStack component violates the constraints specified by the Compliance Rule. @@ -100,18 +115,4 @@ After updating the property HypervisorEndpoint to "192.168.4.3" the Topology Tem Topology Template | Result :-------------------------:|:-------------------------: -![satisfied-topology.PNG](graphics/compliance-checking/required-structure.PNG) | ![satisfied.PNG](graphics/compliance-checking/satisfied.PNG) - -## License - -Copyright (c) 2018 Contributors to the Eclipse Foundation - -See the NOTICE file(s) distributed with this work for additional -information regarding copyright ownership. - -This program and the accompanying materials are made available under the -terms of the Eclipse Public License 2.0 which is available at -http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0 -which is available at https://www.apache.org/licenses/LICENSE-2.0. - -SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 \ No newline at end of file +![](figures/RequiredStructure.png) | ![](figures/Satisfied.png) diff --git a/docs/user/graphics/accountability/Authentication.PNG b/docs/user/features/figures/Authentication.png similarity index 100% rename from docs/user/graphics/accountability/Authentication.PNG rename to docs/user/features/figures/Authentication.png diff --git a/docs/user/graphics/accountability/Authorization.PNG b/docs/user/features/figures/Authorization.png similarity index 100% rename from docs/user/graphics/accountability/Authorization.PNG rename to docs/user/features/figures/Authorization.png diff --git a/docs/user/graphics/completion/Completion_dialog.png b/docs/user/features/figures/CompletionDialog.png similarity index 100% rename from docs/user/graphics/completion/Completion_dialog.png rename to docs/user/features/figures/CompletionDialog.png diff --git a/docs/user/graphics/compliance-checking/complianceRule.PNG b/docs/user/features/figures/ComplianceRule.png similarity index 100% rename from docs/user/graphics/compliance-checking/complianceRule.PNG rename to docs/user/features/figures/ComplianceRule.png diff --git a/docs/user/graphics/compliance-checking/complianceRuleDetection.PNG b/docs/user/features/figures/ComplianceRuleDetection.png similarity index 100% rename from docs/user/graphics/compliance-checking/complianceRuleDetection.PNG rename to docs/user/features/figures/ComplianceRuleDetection.png diff --git a/docs/user/graphics/accountability/Configuration.PNG b/docs/user/features/figures/Configuration.png similarity index 100% rename from docs/user/graphics/accountability/Configuration.PNG rename to docs/user/features/figures/Configuration.png diff --git a/docs/user/graphics/compliance-checking/createComplianceRule.PNG b/docs/user/features/figures/CreateComplianceRule.png similarity index 100% rename from docs/user/graphics/compliance-checking/createComplianceRule.PNG rename to docs/user/features/figures/CreateComplianceRule.png diff --git a/docs/user/graphics/completion/Deferred_example.png b/docs/user/features/figures/DeferredExample.png similarity index 100% rename from docs/user/graphics/completion/Deferred_example.png rename to docs/user/features/figures/DeferredExample.png diff --git a/docs/user/graphics/modeling/7-AddUbuntuNodeType.jpg b/docs/user/features/figures/DownloadGeneratedStub.jpg similarity index 100% rename from docs/user/graphics/modeling/7-AddUbuntuNodeType.jpg rename to docs/user/features/figures/DownloadGeneratedStub.jpg diff --git a/docs/user/graphics/accountability/Exporting.PNG b/docs/user/features/figures/Exporting.png similarity index 100% rename from docs/user/graphics/accountability/Exporting.PNG rename to docs/user/features/figures/Exporting.png diff --git a/docs/user/graphics/accountability/FileComparison.PNG b/docs/user/features/figures/FileComparison.png similarity index 100% rename from docs/user/graphics/accountability/FileComparison.PNG rename to docs/user/features/figures/FileComparison.png diff --git a/docs/user/graphics/modeling/3-AddUbuntuNodeType.jpg b/docs/user/features/figures/GenerateImplArtifact.jpg similarity index 100% rename from docs/user/graphics/modeling/3-AddUbuntuNodeType.jpg rename to docs/user/features/figures/GenerateImplArtifact.jpg diff --git a/docs/user/graphics/compliance-checking/identifier_modeler.PNG b/docs/user/features/figures/IdentifierModeler.png similarity index 100% rename from docs/user/graphics/compliance-checking/identifier_modeler.PNG rename to docs/user/features/figures/IdentifierModeler.png diff --git a/docs/user/graphics/completion/Incomplete_topology_example.png b/docs/user/features/figures/IncompleteTopologyExample.png similarity index 100% rename from docs/user/graphics/completion/Incomplete_topology_example.png rename to docs/user/features/figures/IncompleteTopologyExample.png diff --git a/docs/user/graphics/versionManagement/NewVersionAvailable.jpeg b/docs/user/features/figures/NewVersionAvailable.jpeg similarity index 100% rename from docs/user/graphics/versionManagement/NewVersionAvailable.jpeg rename to docs/user/features/figures/NewVersionAvailable.jpeg diff --git a/docs/user/graphics/pattern-basedModlling/PbDCM.jpg b/docs/user/features/figures/Pbdcm.jpg similarity index 100% rename from docs/user/graphics/pattern-basedModlling/PbDCM.jpg rename to docs/user/features/figures/Pbdcm.jpg diff --git a/docs/user/graphics/pattern-basedModlling/Refinement.jpg b/docs/user/features/figures/PbdcmRefinement.jpg similarity index 100% rename from docs/user/graphics/pattern-basedModlling/Refinement.jpg rename to docs/user/features/figures/PbdcmRefinement.jpg diff --git a/docs/user/graphics/versionManagement/PropertiesToMap.png b/docs/user/features/figures/PropertiesToMap.png similarity index 100% rename from docs/user/graphics/versionManagement/PropertiesToMap.png rename to docs/user/features/figures/PropertiesToMap.png diff --git a/docs/user/graphics/accountability/Provenance1.PNG b/docs/user/features/figures/Provenance1.png similarity index 100% rename from docs/user/graphics/accountability/Provenance1.PNG rename to docs/user/features/figures/Provenance1.png diff --git a/docs/user/graphics/accountability/Provenance2.PNG b/docs/user/features/figures/Provenance2.png similarity index 100% rename from docs/user/graphics/accountability/Provenance2.PNG rename to docs/user/features/figures/Provenance2.png diff --git a/docs/user/graphics/compliance-checking/required-structure.PNG b/docs/user/features/figures/RequiredStructure.png similarity index 100% rename from docs/user/graphics/compliance-checking/required-structure.PNG rename to docs/user/features/figures/RequiredStructure.png diff --git a/docs/user/graphics/compliance-checking/satisfied.PNG b/docs/user/features/figures/Satisfied.png similarity index 100% rename from docs/user/graphics/compliance-checking/satisfied.PNG rename to docs/user/features/figures/Satisfied.png diff --git a/docs/user/graphics/compliance-checking/satisfied-topology.PNG b/docs/user/features/figures/SatisfiedTopology.png similarity index 100% rename from docs/user/graphics/compliance-checking/satisfied-topology.PNG rename to docs/user/features/figures/SatisfiedTopology.png diff --git a/docs/user/graphics/splitting.png b/docs/user/features/figures/Splitting.png similarity index 100% rename from docs/user/graphics/splitting.png rename to docs/user/features/figures/Splitting.png diff --git a/docs/user/graphics/threatmodelingNFV/threat-assessment.png b/docs/user/features/figures/ThreatAssessment.png similarity index 100% rename from docs/user/graphics/threatmodelingNFV/threat-assessment.png rename to docs/user/features/figures/ThreatAssessment.png diff --git a/docs/user/graphics/threatmodelingNFV/threat-catalog.png b/docs/user/features/figures/ThreatCatalog.png similarity index 100% rename from docs/user/graphics/threatmodelingNFV/threat-catalog.png rename to docs/user/features/figures/ThreatCatalog.png diff --git a/docs/user/graphics/threatmodelingNFV/threat-creation.png b/docs/user/features/figures/ThreatCreation.png similarity index 100% rename from docs/user/graphics/threatmodelingNFV/threat-creation.png rename to docs/user/features/figures/ThreatCreation.png diff --git a/docs/user/graphics/completion/Topology_complete.png b/docs/user/features/figures/TopologyComplete.png similarity index 100% rename from docs/user/graphics/completion/Topology_complete.png rename to docs/user/features/figures/TopologyComplete.png diff --git a/docs/user/graphics/compliance-checking/unsatisfied.PNG b/docs/user/features/figures/Unsatisfied.png similarity index 100% rename from docs/user/graphics/compliance-checking/unsatisfied.PNG rename to docs/user/features/figures/Unsatisfied.png diff --git a/docs/user/graphics/compliance-checking/unsatisfied-topology.PNG b/docs/user/features/figures/UnsatisfiedTopology.png similarity index 100% rename from docs/user/graphics/compliance-checking/unsatisfied-topology.PNG rename to docs/user/features/figures/UnsatisfiedTopology.png diff --git a/docs/user/graphics/versionManagement/UpdatedNodeTemplate.jpeg b/docs/user/features/figures/UpdatedNodeTemplate.jpeg similarity index 100% rename from docs/user/graphics/versionManagement/UpdatedNodeTemplate.jpeg rename to docs/user/features/figures/UpdatedNodeTemplate.jpeg diff --git a/docs/user/graphics/accountability/Validation.PNG b/docs/user/features/figures/Validation.png similarity index 100% rename from docs/user/graphics/accountability/Validation.PNG rename to docs/user/features/figures/Validation.png diff --git a/docs/user/graphics/accountability/ValidationResult.PNG b/docs/user/features/figures/ValidationResult.png similarity index 100% rename from docs/user/graphics/accountability/ValidationResult.PNG rename to docs/user/features/figures/ValidationResult.png diff --git a/docs/user/graphics/versionManagement/VersionSelection.jpeg b/docs/user/features/figures/VersionSelection.jpeg similarity index 100% rename from docs/user/graphics/versionManagement/VersionSelection.jpeg rename to docs/user/features/figures/VersionSelection.jpeg diff --git a/docs/user/features/generate-ia.md b/docs/user/features/generate-ia.md new file mode 100644 index 0000000000..8214831a36 --- /dev/null +++ b/docs/user/features/generate-ia.md @@ -0,0 +1,59 @@ + + + +# Generate an Implementation Artifact for a Node Type Interface + +To specify what a node type should do, the user can define an *interface* and the *operations* provided by this interface. +Once the operations of a node type are defined, artifacts (e.g., shell scripts, .war files) implementing these operations need to be modeled. +For this, Winery provides an option to **automatically generate a stub java maven project** to build a **.war file** for a defined interface. +This can be done in the *Interface* tab of the node type view by pressing *Generate Implementation Artifact*. +A node type implementation will be automatically generated as well, if it does not exist yet. +Once you get a confirmation that the artifact was generated, please press *Save*. + +![](figures/GenerateImplArtifact.jpg) + +To download the generated stub java main project, go to the detailed view of the artifact template and press *ZIP*. + +![](figures/DownloadGeneratedStub.jpg) + +Unzip the archive generated by Winery into a location of your choice. In the root folder, you can find a *README.txt* explaining in details how to edit, build and upload the .war file to the implementation artifact in Winery. +A summary of this is provided below. +For the next steps, maven and Eclipse are required. Furthermore, maven commands are executed in the root folder of the implementation artifact. + +## Create an Eclipse Project +- Run: mvn eclipse:eclipse +- Open Eclipse +- *File* -> *Import* -> *Existing Project into Workspace* -> click *Next* +- Click *Browse* and select folder where you unzipped the generated implementation artifact +- Select the project from the list and click *Finish* + +## Test your Implementation Artifact +- Run: mvn clean package tomcat7:run-war +- Open this page to see the list of available services: http://localhost:9090/services/ +- This page also links the WSDL +- With the WSDL your're able to test your IA using SOAPui or other tools. + +## Upload your Implementation Artifact +You have two options to do this: + +### 1) Automatically (to the Winery instance this IA project was generated with) +- Run: mvn deploy +- The WAR is directly uploaded into the correct ArtifactTemplate, previous versions will be overwritten. + +### 2) Manually +- Run: mvn clean package +- Locate the WAR file in the /target folder +- Open Winery in your browser, locate the artifact template representing this implementation artifact. +- Upload the WAR file to the artifact template in the tab *Files* diff --git a/docs/user/ThreatModelingNFV.md b/docs/user/features/nfv-threat-modeling.md similarity index 82% rename from docs/user/ThreatModelingNFV.md rename to docs/user/features/nfv-threat-modeling.md index 487437d8d7..f7900b96f7 100644 --- a/docs/user/ThreatModelingNFV.md +++ b/docs/user/features/nfv-threat-modeling.md @@ -1,10 +1,26 @@ -# Threat Modeling for security-aware NFV + + + +# Threat Modeling for Security-aware NFV Threat modeling enables a user to annotate threats in a topology using a structured approach and receive recommendations which security-related Virtual Network Function (S-VNF) should be used. This documents specifies how this functionality is intended to be used. ## Why threat modeling? + In order to protect something of value, threats that impose risk on a application need to be modeled and assessed. Network Function Virtualization (NFV) can be used as a component based approach to mitigate a certain class of threats. For Example a virtual firewall could mitigate the threat of publicly exposed ports of a database. @@ -14,7 +30,7 @@ To realize this, this module relies on the presents of two special PolicyTypes a The setup of these types is automatically triggered if a new threat is created using the designated UI. It is assumed that each VNF implementations is encapsulated in it's own ServiceTemplate. -## Creating threats +## Creating Threats A threat is a PolicyTemplate of a special PolicyType ("{http://opentosca.org/threatmodeling}Security.Threat-w1_wip1") and can therefore be created like a regular PolicyTemplate. The topology modeler UI and repository UI can both be used to create threats. @@ -23,7 +39,7 @@ This way it is ensured that threats are created using the required parameters an [STRIDE](https://docs.microsoft.com/de-de/azure/security/azure-security-threat-modeling-tool-threats) is used as a threat modeling methodology. Each threat requires a name, a textual description, stride classification and a severity rating in the form of "Low", "Middle" and "High". -![threat-creation.png](graphics/threatmodelingNFV/threat-creation.png) +![](figures/ThreatCreation.png) ## Assigning threats to NodeTemplates The created threat PolicyTemplate is intended to be used on a NodeTemplate of a topology to indicate that this NodeTemplate is the target of the threat. @@ -31,9 +47,10 @@ This is done in the topology modeler UI. The Threat Modeling Modal can be used to generate an overview of all available threats under the menu "Threat Catalog" and receive info on description, stride and severity. Subsequently the desired threat PolicyTemplate has to be assigned like any other PolicyTemplate using the regular UI. -![threat-catalog.png](graphics/threatmodelingNFV/threat-catalog.png) +![](figures/ThreatCatalog.png) + +## Assigning Mitigations to VNFs -## Assigning mitigations to VNFs When threats are created using the threat modeling UI (topology modeler) a corresponding mitigation PolicyTemplate is created. A naming convention of prepending the given threat name with the string "MITIGATE_" is established to ease working with threat and mitigations. Referencing the corresponding threat is done by using the "ThreatReference" property of the PolicyTemplate. @@ -49,24 +66,11 @@ The implemented functionality makes no assumptions how these NodeTypes are model It is intended to model NodeTypes that inherit from S-VNF (referred to as S-VNF Groups) in a way that multiple VNF implementations can substitute the same S-VFN Group. All this is done in order to enable users to use abstract NodeTypes in their topologies to hide the underlying complexity and later substitute. Therefore the general rules of substitution apply. -## Threat assessment and mitigation recommendation +## Threat Assessment and Mitigation Recommendation + The "Threat Assessment" menu can be viewed in the repository UI on each ServiceTemplate. An overview of present threats, their targets, and potential mitigation strategies using available VNFs are presented. This way a detailed look on the current state of the threats is enabled. Each recommendation can be directly added to the topology by clicking the corresponding button in the "Available Mitigations" part of the threat modeling modal. -![threat-assessment.png](graphics/threatmodelingNFV/threat-assessment.png) - -## License - -Copyright (c) 2018 Contributors to the Eclipse Foundation - -See the NOTICE file(s) distributed with this work for additional -information regarding copyright ownership. - -This program and the accompanying materials are made available under the -terms of the Eclipse Public License 2.0 which is available at -http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0 -which is available at https://www.apache.org/licenses/LICENSE-2.0. - -SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 +![](figures/ThreatAssessment.png) diff --git a/docs/user/Pattern-basedDeploymentModelling.md b/docs/user/features/pattern-deployment-modeling.md similarity index 76% rename from docs/user/Pattern-basedDeploymentModelling.md rename to docs/user/features/pattern-deployment-modeling.md index 83f45ceeb9..c0d644b930 100644 --- a/docs/user/Pattern-basedDeploymentModelling.md +++ b/docs/user/features/pattern-deployment-modeling.md @@ -1,3 +1,18 @@ + + + # Pattern-based Deployment and Configuration Models (PbDCMs) This is a guide to the Pattern-bsed Deployment and Configuration Model (PbDCM) approach that is presented in the UCC 2019 paper `Pattern-based Deployment Models Revisited: Automated Pattern-driven Deployment Configuration`. @@ -12,7 +27,7 @@ A _Component Pattern_ is hereby represented as a Node Template that is defined i Videos on how to model and refine a PbDCM are available on [YouTube](https://www.youtube.com/playlist?list=PLLP47UpoeRSDfr9s0ZYV20mgClcfvh15q). -An example PbDCM is shown here: ![An exemplary PbDCM](graphics/pattern-basedModlling/PbDCM.jpg) +An example PbDCM is shown here: ![](figures/Pbdcm.jpg) ### Pattern Types @@ -41,4 +56,4 @@ To create, edit, and manage a CBPRM, you need to go to + + +# Splitting and Matching + +## Splitting Functionality + +In the topologymodeler target labels can be shown/hidden by "Target Locations" - The Target Location assigned to a Node Template determines the service templates serving as cloud provider repositories, which should be searched for a suitable host. +The namespace of all cloud provider repositories must start with "http://www.opentosca.org/providers". +To distinguish between different repositories the namespace must end with the target label, e.g., "../IAAS" or "../Amazon/PaaS". The target labels are not case-sensitive. + +A prerequisite for a splitting is the assignment of requirements and capabilities to all Node Templates in the Topology Template, which should be split, and the Node Templates in the repositories. +The latter just have requirements assigned because they form the lowest level of the topology. +The naming convention for the mapping of Reqs and Caps are: + +- Requirement: ReqCanHostxyz +- Capability: CapCanHostxyz + +By clicking the "Split" button first the topology is split according to the assigned labels (nodes with hostedOn-predecessors with different labels are duplicated) and second the host nodes from the provider repositories are matched. +For this, lower level nodes can be removed and replaced. + +The split as well as the matched topology are persistently stored with an attached "-split" and "-matched" in the Service Template Id. + +![](figures/Splitting.png) + +## Matching Functionality + +Additional and based on the split function a match function is added to the winery. +A topology is inspected if open requirements are contained. A open requirement is a requirement for which no relationship +to a node template exists which has the matching capability assigned. +In case open requirements are found, the provider repositories are searched for suitable matching candidates. +A matching candidate can be a single node, but also a whole topology fragment. +The matching can be done to new hosts, but also to dat resources, etc. +That means, based on the matching capabilities matching candidates are found and based on the requirements and capabilities +and their inheritance hierarchies the correct relationship types are determined. + +To use this functionality a strict type and inheritance system is important. +These are the rules: + +- Each capability type with the semantic, that it acts as host/container has to be derived from the capability "Container" +- Each capability type with the semantic, that it acts as a endpoint has to be derived from the capability "Endpoint" +- The two default relationship types "hostedOn" and "connectsTo" should ne available and requires as valid target the capability "Container" oder "Endpoint" + +By using this function a vertical as well as horizontal matching is possible. diff --git a/docs/user/TargetAllocation.md b/docs/user/features/target-allocation.md similarity index 84% rename from docs/user/TargetAllocation.md rename to docs/user/features/target-allocation.md index 2889527dde..a33ed0bb6d 100644 --- a/docs/user/TargetAllocation.md +++ b/docs/user/features/target-allocation.md @@ -1,6 +1,21 @@ + + + # Target Allocation -(see [Splitting](Splitting)) +(see [Splitting](splitting.md)) In the repository UI the topology of a Service Template can be allocated to Cloud Providers by clicking the cloud icon and entering the needed information. Cloud Providers for the Node Templates of the topology are selected based on already assigned target locations and three different criteria. @@ -57,17 +72,3 @@ This enables the fulfillment of multiple criteria and the narrowing of the gener As target locations can also only be assigned without injecting matching Node Templates from the Cloud Providers, the preferred target location distribution can also be selected manually. After the selection, matching Node Templates can be injected using on of the criteria or the Split & Match functionality. - -## License - -Copyright (c) 2018 Contributors to the Eclipse Foundation - -See the NOTICE file(s) distributed with this work for additional -information regarding copyright ownership. - -This program and the accompanying materials are made available under the -terms of the Eclipse Public License 2.0 which is available at -http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0 -which is available at https://www.apache.org/licenses/LICENSE-2.0. - -SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 diff --git a/docs/user/TopologyCompletion.md b/docs/user/features/topology-completion.md similarity index 80% rename from docs/user/TopologyCompletion.md rename to docs/user/features/topology-completion.md index 584f0fa0cb..31a3b2e378 100644 --- a/docs/user/TopologyCompletion.md +++ b/docs/user/features/topology-completion.md @@ -1,3 +1,18 @@ + + + # TOSCA Topology Completion The TOSCA Topology Completion of Winery enables the user to model incomplete TOSCA Topology Templates and complete them automatically. @@ -16,8 +31,7 @@ The step-by-step function of the completion allows these users to comprehend the ## Modeling incomplete TOSCA Topology Templates -![Incomplete_topology_example.png](graphics/completion/Incomplete_topology_example.png) - +![](figures/IncompleteTopologyExample.png) Figure 1: Example of an incomplete Topology using Requirements To be able to complete a topology you have to model an incomplete topology first, providing a base for the Topology Completion. @@ -31,8 +45,7 @@ that a "SQLDatabase" Node Template will be added to the topology. Note that in t The example topology in figure 1 displays the usage of Requirements: -![Topology_complete.png](graphics/completion/Topology_complete.png) - +![](figures/TopologyComplete.png) Figure 2: Possible Completion Result For each Requirement, the Topology Completion will insert Node Templates containing suitable Capabilities. Note that the inserted Node Templates can be attached with further Requirements that will also be fulfilled by the Topology Completion. @@ -45,12 +58,13 @@ In case you want to model part of the infrastructure by yourself (e.g. the Cloud We need a means to predefine part of a complete topology that isn't directly connected to the application components (which contain the TOSCA Requirements). To achieve this we introduce a new Relationship Template "deferred", which you will have to create in the Repository as follows: - - - - -![Deferred_example.png](graphics/completion/Deferred_example.png) +```xml + + + +``` +![](figures/DeferredExample.png) Figure 3: Incomplete Topologies using Deferred-Relationship Templates After creating the Relationship Type in the repository you can use it to connect to your modeled infrastructure components. @@ -63,27 +77,8 @@ In the appearing dialog fill in the save options for the completed topology and In case the step-by-step approach is selected, the topology completion algorithm will pause in every step giving feedback about the Node and Relationship Templates to be inserted. Figure 4 displays the completion dialog: -![Completion_dialog.png](graphics/completion/Completion_dialog.png) - +![](figures/CompletionDialog.png) Figure 4: Completion Dialog After the form has been completed you can start the completion by selecting "Complete Topology" in the dialog. After the completion the completed topology will be displayed in the topology modeler or in a new browser window dependent on the selected save options. - -## Topology Completion - Getting started - -Please head to the [tutorial](TopologyCompletionTutorial). - -## License - -Copyright (c) 2013-2017 Contributors to the Eclipse Foundation - -See the NOTICE file(s) distributed with this work for additional -information regarding copyright ownership. - -This program and the accompanying materials are made available under the -terms of the Eclipse Public License 2.0 which is available at -http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0 -which is available at https://www.apache.org/licenses/LICENSE-2.0. - -SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 diff --git a/docs/user/features/version-management.md b/docs/user/features/version-management.md new file mode 100644 index 0000000000..1dce140969 --- /dev/null +++ b/docs/user/features/version-management.md @@ -0,0 +1,35 @@ + + + +# Update Management of Node Templates in Topology Modeler + +This guide shows an overview of how to update a Node Template in a Topology Template. + +## Steps to update a Node Template + +User will be informed with a *red exclamation mark* when there's any new versions available for a node template. +![](figures/NewVersionAvailable.jpeg) + +Select the version to update. +![](figures/VersionSelection.jpeg) + + +A table with new, removed and resolved Properties will be shown. A new *Property* and a removed *Property* can be selected so that the value will be transferred. +![](figures/PropertiesToMap.png) + +Now the Node Template is updated in the Topology Template. New Properties are available and values are transferred. +![](figures/UpdatedNodeTemplate.jpeg) + +To confirm the update above, save the topology template. diff --git a/docs/user/XaaSPackager.md b/docs/user/features/xaas-packager.md similarity index 86% rename from docs/user/XaaSPackager.md rename to docs/user/features/xaas-packager.md index b97563d98f..b280d0f7ca 100644 --- a/docs/user/XaaSPackager.md +++ b/docs/user/features/xaas-packager.md @@ -34,15 +34,16 @@ For example, the input of: - **name:** `xaasPackageDeploymentArtifact`, **value:** `HelloWorldDA` - **name:** `xaasPackageNode`, **value:** `PythonApp_2_7` -generates the following XML: +Generates the following XML: - ``` xml +```xml ``` + ## XaaS Packager with Winery The functionality of the XaaS Packager is available in the Winery application and can be used as follows: @@ -57,17 +58,3 @@ The functionality of the XaaS Packager is available in the Winery application an - **NodeTypes** (optional): allows the selection of additional Node Types that MUST be used inside the selected topology. After setting all required inputs, a click on the *add* button triggers a search for a suitable cloud topology into which the artifact can be wrapped. - -## License - -Copyright (c) 2017 Contributors to the Eclipse Foundation - -See the NOTICE file(s) distributed with this work for additional -information regarding copyright ownership. - -This program and the accompanying materials are made available under the -terms of the Eclipse Public License 2.0 which is available at -http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0 -which is available at https://www.apache.org/licenses/LICENSE-2.0. - -SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 diff --git a/docs/user/graphics/components.png b/docs/user/figures/components.png similarity index 100% rename from docs/user/graphics/components.png rename to docs/user/figures/components.png diff --git a/docs/user/graphics/pptx/components.pptx b/docs/user/figures/components.pptx similarity index 100% rename from docs/user/graphics/pptx/components.pptx rename to docs/user/figures/components.pptx diff --git a/docs/user/generateIA.md b/docs/user/generateIA.md deleted file mode 100644 index 9fc2ef6c84..0000000000 --- a/docs/user/generateIA.md +++ /dev/null @@ -1,59 +0,0 @@ -# Generate an Implementation Artifact for a Node Type Interface - -To specify what a node type should do, the user can define an *interface* and the *operations* provided by this interface. -Once the operations of a node type are defined, artifacts (e.g., shell scripts, .war files) implementing these operations need to be modeled. -For this, Winery provides an option to **automatically generate a stub java maven project** to build a **.war file** for a defined interface. -This can be done in the *Interface* tab of the node type view by pressing *Generate Implementation Artifact*. -A node type implementation will be automatically generated as well, if it does not exist yet. -Once you get a confirmation that the artifact was generated, please press *Save*. - - ![3-AddUbuntuNodeType](graphics/modeling/3-AddUbuntuNodeType.jpg) - -To download the generated stub java main project, go to the detailed view of the artifact template and press *ZIP*. - - ![7-AddUbuntuNodeType](graphics/modeling/7-AddUbuntuNodeType.jpg) - -Unzip the archive generated by Winery into a location of your choice. In the root folder, you can find a *README.txt* explaining in details how to edit, build and upload the .war file to the implementation artifact in Winery. -A summary of this is provided below. -For the next steps, maven and Eclipse are required. Furthermore, maven commands are executed in the root folder of the implementation artifact. - -## Create an Eclipse Project - - Run: mvn eclipse:eclipse - - Open Eclipse - - *File* -> *Import* -> *Existing Project into Workspace* -> click *Next* - - Click *Browse* and select folder where you unzipped the generated implementation artifact - - Select the project from the list and click *Finish* - -## Test your Implementation Artifact - - Run: mvn clean package tomcat7:run-war - - Open this page to see the list of available services: http://localhost:9090/services/ - - This page also links the WSDL - - With the WSDL your're able to test your IA using SOAPui or other tools. - -## Upload your Implementation Artifact - You have two options to do this: - -### 1) Automatically (to the Winery instance this IA project was generated with) - - Run: mvn deploy - - The WAR is directly uploaded into the correct ArtifactTemplate, previous versions will be overwritten. - -### 2) Manually - - Run: mvn clean package - - Locate the WAR file in the /target folder - - Open Winery in your browser, locate the artifact template representing this implementation artifact. - - Upload the WAR file to the artifact template in the tab *Files* - - -## License - -Copyright (c) 2018 Contributors to the Eclipse Foundation - -See the NOTICE file(s) distributed with this work for additional -information regarding copyright ownership. - -This program and the accompanying materials are made available under the -terms of the Eclipse Public License 2.0 which is available at -http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0 -which is available at https://www.apache.org/licenses/LICENSE-2.0. - -SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 diff --git a/docs/user/getting-started.rst b/docs/user/getting-started.rst new file mode 100644 index 0000000000..72c7c4ff30 --- /dev/null +++ b/docs/user/getting-started.rst @@ -0,0 +1,113 @@ +.. Copyright (c) 2020 Contributors to the Eclipse Foundation + +.. See the NOTICE file(s) distributed with this work for additional +.. information regarding copyright ownership. + +.. This program and the accompanying materials are made available under the +.. terms of the Eclipse Public License 2.0 which is available at +.. http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0 +.. which is available at https://www.apache.org/licenses/LICENSE-2.0. + +.. SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 + +.. _getting_started: + + +Getting Started +############### + +Launching with Docker +********************* + +.. note:: + It is recommended that your host or virtual machine has at least 2GB of memory. + +Open a command prompt and execute the following command: + +.. code-block:: + + docker run -it -p 8080:8080 \ + -e PUBLIC_HOSTNAME=localhost \ + -e WINERY_FEATURE_RADON=true \ + -e WINERY_REPOSITORY_PROVIDER=yaml \ + -e WINERY_REPOSITORY_URL=https://github.com/radon-h2020/radon-particles \ + opentosca/winery + +Launch a browser: ``_. + +.. note:: + To start Eclipse Winery based on an TOSCA XML repository layout, use the following command: + + .. code-block:: + + docker run -it -p 8080:8080 \ + -e PUBLIC_HOSTNAME=localhost \ + -e WINERY_REPOSITORY_URL=https://github.com/OpenTOSCA/tosca-definitions-public \ + opentosca/winery + + +Use a custom TOSCA model repository +----------------------------------- + +Please follow the next instructions to mount an existing TOSCA model repository into the Eclipse Winery container. +This is useful if you want to save your modeling changes onto your Docker host machine. + +Clone or create git repository on your local filesystem, e.g., by cloning ``_. + +Open a command prompt and execute the following command: + +.. warning:: + Replace ```` with an empty directory path on your host system. + +.. code-block:: + + docker run -it -p 8080:8080 \ + -e PUBLIC_HOSTNAME=localhost \ + -e WINERY_FEATURE_RADON=true \ + -e WINERY_REPOSITORY_PROVIDER=yaml \ + -v :/var/repository \ + opentosca/winery + +Launch a browser: ``_. + +.. note:: + To start Eclipse Winery based on an TOSCA XML repository layout, use the following command: + + .. code-block:: + + docker run -it -p 8080:8080 \ + -e PUBLIC_HOSTNAME=localhost \ + -v :/var/repository \ + opentosca/winery + + +Launching with Docker Compose +***************************** + +.. note:: + It is recommended that your host or virtual machine has at least 2GB of memory. + +Install Docker and `Docker Compose `_. + +Clone the repository: + +.. code-block:: + + git clone https://github.com/eclipse/winery + cd winery/deploy/compose + +**[Optional]** Build the Docker image based on your current working copy: + +.. code-block:: + + docker-compose build + +**[Optional]** Adapt the Docker Compose configuration to your needs, e.g., to mount a local TOSCA model repository. + +Start Winery: + +.. code-block:: + + docker-compose up + +Launch a browser: ``_. diff --git a/docs/user/graphics/compliance-checking/step2.PNG b/docs/user/graphics/compliance-checking/step2.PNG deleted file mode 100644 index a2df791bc6..0000000000 Binary files a/docs/user/graphics/compliance-checking/step2.PNG and /dev/null differ diff --git a/docs/user/index.md b/docs/user/index.md deleted file mode 100644 index 05965f2aa1..0000000000 --- a/docs/user/index.md +++ /dev/null @@ -1,51 +0,0 @@ -# Eclipse Winery User Guide - -Eclipse Winery is a Web-based environment to graphically model [OASIS TOSCA](../tosca/) topologies and plans managing these topologies. -It is an Eclipse project and thus support is available through its project page . -Winery is also part of the OpenTOSCA ecosystem where more information is available at . -For more information on TOSCA see [our TOSCA information page](../tosca/). - -- [overview](overview.md) - overview on Winery -- [FAQ](FAQ.md) - frequently asked questions -- [Quick Setup](quicksetup.md) - shows how to setup the winery repository for TOSCA definitions -- [Quickstart](quickstart.md) - shows how to use Winery to model a node type and a topology - -## Features - -- [Splitting](Splitting) - splitting functionality -- [Target Allocation](TargetAllocation) - select best suited Cloud Provider for topologies -- [TopologyCompletion](TopologyCompletion) - topology completion with a [Tutorial](TopologyCompletionTutorial) -- [XaaSPackager](XaaSPackager) - Enables reusing modeled topologies as templates for single applications -- [Compliance Checking](ComplianceChecking.md) - Enables compliance checking of Topology Templates based on reusable Compliance Rules -- [Implementation Artifact Generation](generateIA.md) - Shows how to generate and update an implementation artifact of type .war -- [Accountability](../../org.eclipse.winery.accountability/README.md) - Enables enforcing accountability in decentralized scenarios for collaborative development of CSARs -- [Version Management](VersionManagement.md) - shows how to update the version of a node template in the topology modeler -- [Threat Modeling For NFV](ThreatModelingNFV.md) - Enables threat modeling capabilities and NFV-based mitigation recommendation -- [Pattern-based Deployment and Configuration Models](Pattern-basedDeploymentModelling.md) - describes how PbDCMs can be crated and refined to executable deployment models - -## Background Literature - -[BBKL14] Breitenbücher, Uwe; Binz, Tobias; Kopp, Oliver; Leymann, Frank: Vinothek - A Self-Service Portal for TOSCA. In: Herzberg, Nico (Hrsg); Kunze, Matthias (Hrsg): Proceedings of the 6th Central-European Workshop on Services and their Composition (ZEUS 2014). - -[KBBL12] Kopp, Oliver; Binz, Tobias; Breitenbücher, Uwe; Leymann, Frank: BPMN4TOSCA: A Domain-Specific Language to Model Management Plans for Composite Applications. In: Mendling, Jan (Hrsg); Weidlich, Matthias (Hrsg): 4th International Workshop on the Business Process Model and Notation, 2012 - -More readings at . - -## Related Work - -- [tosca-parser by the OpenStack project](https://github.com/openstack/tosca-parser) - parses TOSCA YAML files using Pyhton -- [TOSCA .Net Analyzer](https://github.com/QualiSystems/Toscana) - .NET libary for working with TOSCA YAML files - -## License - -Copyright (c) 2017-2019 Contributors to the Eclipse Foundation - -See the NOTICE file(s) distributed with this work for additional -information regarding copyright ownership. - -This program and the accompanying materials are made available under the -terms of the Eclipse Public License 2.0 which is available at -http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0 -which is available at https://www.apache.org/licenses/LICENSE-2.0. - -SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 diff --git a/docs/user/index.rst b/docs/user/index.rst new file mode 100644 index 0000000000..ff620d1fea --- /dev/null +++ b/docs/user/index.rst @@ -0,0 +1,32 @@ +.. Copyright (c) 2020 Contributors to the Eclipse Foundation + +.. See the NOTICE file(s) distributed with this work for additional +.. information regarding copyright ownership. + +.. This program and the accompanying materials are made available under the +.. terms of the Eclipse Public License 2.0 which is available at +.. http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0 +.. which is available at https://www.apache.org/licenses/LICENSE-2.0. + +.. SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 + +.. _user_guide: + + +User Guide +########## + +Eclipse Winery is a web-based environment to graphically model :ref:`OASIS TOSCA` topologies and plans managing these topologies. +It is an Eclipse project and thus support is available through its `project page `_. +Winery is also part of the OpenTOSCA ecosystem where more information is available at `opentosca.org `_. +For more information on TOSCA see our :ref:`TOSCA information page`. + +.. toctree:: + :maxdepth: 1 + :caption: Contents: + + getting-started.rst + yml/index.rst + xml/index.rst + overview.md + faq.rst diff --git a/docs/user/overview.md b/docs/user/overview.md index 7f6d16caef..e74b6d20f9 100644 --- a/docs/user/overview.md +++ b/docs/user/overview.md @@ -1,38 +1,49 @@ -# Overview - -![Winery Components](graphics/components.png) - -The TOSCA modeling tool Winery mainly consists of four parts: (1) the templates, types, plans, and CSARs management, -(2) the TOSCA topology model editor, (3) the BPMN4TOSCA management plan editor, and (4) the repository to store + + + +# Component and Feature Overview + +## Components + +![](figures/components.png) + +The TOSCA modeling tool Winery mainly consists of four parts: +(1) the templates, types, plans, and CSARs management, +(2) the TOSCA topology model editor, +(3) the BPMN4TOSCA management plan editor, and +(4) the repository to store templates, types, plans, etc. -For the templates, types, plans, and CSARs management an user interface *Templates, Types, Plans & CSARs Management UI* -that enables managing all TOSCA types, templates, and related artifacts is available. -This includes node types, relationship types, policy types, artifact types, artifact templates, and artifacts -such as virtual machine images. -The *Templates, Types, Plans & CSARs Management* backend component provides functionality to access, store, or delete -TOSCA elements in the *Templates, Types, Plans & CSARs Repository* which is a file system storing all available -TOSCA elements. +For the templates, types, plans, and CSARs management a user interface *Templates, Types, Plans & CSARs Management UI* that enables managing all TOSCA types, templates, and related artifacts is available. +This includes node types, relationship types, policy types, artifact types, artifact templates, and artifacts such as virtual machine images. +The *Templates, Types, Plans & CSARs Management* backend component provides functionality to access, store, or delete TOSCA elements in the *Templates, Types, Plans & CSARs Repository* which is a file system storing all available TOSCA elements. -The *TOSCA Topology Model Editor* enables the creation of service templates as directed graphs. +The *TOSCA Topology Model Editor* enables the creation of service templates as directed graphs. Service templates consists of instances of node types (node templates) and instances of relationship types (relationship templates). They can be annotated with requirements and capabilities, properties, deployment artifacts, and policies. -Modeled service templates can be exported based on the TOSCA XML standard using the *TOSCA XML Model Importer & Exporter* -or as YAML Model using the *TOSCA YAML Model Importer & Exporter*. -Because the internal data model of the Winery is based on the XML standard the *TOSCA YAML Model to TOSCA XML Model Transformer* -is required to enable the import and export as XMl as well as YAML model. +Modeled service templates can be exported based on the TOSCA XML standard using the *TOSCA XML Model Importer & Exporter* or as YAML Model using the *TOSCA YAML Model Importer & Exporter*. +Because the internal data model of the Winery is based on the XML standard the *TOSCA YAML Model to TOSCA XML Model Transformer* is required to enable the import and export as XMl as well as YAML model. The standard packaging format for service templates and all related TOSCA elements is a Cloud Service Archive (CSAR). -The *CSAR Packager* backend component is responsible to package all TOSCA elements in the archive. The archive can be -used by a TOSCA runtime for the deployment of the described cloud application. +The *CSAR Packager* backend component is responsible to package all TOSCA elements in the archive. +The archive can be used by a TOSCA runtime for the deployment of the described cloud application. The *BPMN4TOSCA Management Plan Editor* offers web-based creation of BPMN models with the TOSCA extension BPMN4TOSCA. -That means, the editor supports the BPMN elements and structures required by TOSCA plans and not -the full set of BPMN [KBBL12]. +That means, the editor supports the BPMN elements and structures required by TOSCA plans and not the full set of BPMN. The *BPMN4TOSCA Management Plan Importer* enables to load existing management plans to the Winery. -Because not only BPMN but also BPEL is a common modeling language for the automated workflow execution, -a *BPMN4TOSCA to BPEL Transformer* component is available to support different modeling standards. -In case a running instance of the [OpenTOSCA Container](https://github.com/OpenTOSCA/container) is available -provisioning plans can be automatically generated by the *BPEL Provisioning Plan Generator*. +Because not only BPMN but also BPEL is a common modeling language for the automated workflow execution, a *BPMN4TOSCA to BPEL Transformer* component is available to support different modeling standards. +In case a running instance of the [OpenTOSCA Container](https://github.com/OpenTOSCA/container) is available provisioning plans can be automatically generated by the *BPEL Provisioning Plan Generator*. In addition to the described basis functionality of the TOSCA modeling tool Winery several advanced functionalities are provided: @@ -40,43 +51,38 @@ In addition to the described basis functionality of the TOSCA modeling tool Wine XML specification. This includes the definition of used node types and properties, the QNames, and if License and README files are available. This supports the user to model valid service templates. -- *XaaS Packager*: It enables the deployment of an, e.g., web application by reusing an existing service template and -replacing the deployment artifact in the specified node type with the new deployment artifact. The underlying -platform or infrastructure services do not have to modeled for each application, predefined templates can be used. -More information can be found [here](XaaSPackager). - -- *Topology Completion*: The TOSCA Topology Completion of Winery enables the user to model incomplete -TOSCA Topology Templates and complete them automatically step-by-step by injecting new node templates to fulfill open requirements. -More information can be found [here](TopologyCompletion). - -- *Splitting & Matching*: The Split & Match function facilitates the redistribution of application components to target locations. -For this, the application components can be annotated with target labels to indicate the desired -target locations. -In the *Matching Templates Repository* platform or infrastructure services can be defined as node templates or complete topology fragements -for each target location. Based on the desired split, the node templates of the original service template are split according -to the labels and the matching node templates or topology fragments for hosting the application's components in the -target location are matched with the corresponding part of the split topology. -More information can be found [here](Splitting). - -- *Versioning & Difference Calculation*: To support version control of all TOSCA elements, including node types, artifact -templates, service templates, and so on, the versioning component enables to add different versions of a TOSCA element -and to release them after the development phase. Released elements can not be modified to ensure consistency of specific -versions in the ecosystem. In addition, the differences between two versions can be calculated and visualized in the -TOSCA Topology Model Editor. - -- *Accountability*: In collaborative development of application deployment models in business-critical scenarios -(such as data-analysis), accountability is of high importance. Thus, at CSAR export time, Winery enables to store the TOSCA meta file in a blockchain to identify the author of each exported version and whether a contained artifact is changed and by whom. - Winery also stores these artifacts versions in a decentralized storage which facilitates comparing them and visualizing the provenance of a specific resource. +- *XaaS Packager*: + It enables the deployment of, e.g., a web application by reusing an existing service template and replacing the deployment artifact in the specified node type with the new deployment artifact. + The underlying platform or infrastructure services do not have to modeled for each application, predefined templates can be used. + More information can be found [here](features/xaas-packager.md). + +- *Topology Completion*: + The TOSCA Topology Completion of Winery enables the user to model incomplete TOSCA Topology Templates and complete them automatically step-by-step by injecting new node templates to fulfill open requirements. + More information can be found [here](features/topology-completion.md). + +- *Splitting & Matching*: + The Split & Match function facilitates the redistribution of application components to target locations. + For this, the application components can be annotated with target labels to indicate the desired target locations. + In the *Matching Templates Repository* platform or infrastructure services can be defined as node templates or complete topology fragments for each target location. + Based on the desired split, the node templates of the original service template are split according to the labels and the matching node templates or topology fragments for hosting the application's components in the target location are matched with the corresponding part of the split topology. + More information can be found [here](features/splitting.md). + +- *Versioning & Difference Calculation*: + To support version control of all TOSCA elements, including node types, artifact templates, service templates, and so on, the versioning component enables to add different versions of a TOSCA element and to release them after the development phase. + Released elements can not be modified to ensure consistency of specific versions in the ecosystem. + In addition, the differences between two versions can be calculated and visualized in the TOSCA Topology Model Editor. + +- *Accountability*: + In collaborative development of application deployment models in business-critical scenarios (such as data-analysis), accountability is of high importance. + Thus, at CSAR export time, Winery enables to store the TOSCA meta file in a blockchain to identify the author of each exported version and whether a contained artifact is changed and by whom. + Winery also stores these artifacts versions in a decentralized storage which facilitates comparing them and visualizing the provenance of a specific resource. - *Compliance Checking (Compliance Rule Editor, Compliance Checker & Compliance Rules Repository)*: -The Topology Compliance Checking of Winery enables to describe restrictions, constraints, and -requirements for Topology Templates in form of reusable topology-based Compliance Rules. -These rules can be modeled using the *Compliance Rule Editor* and stored in the *Compliance Rules Repository*. Each rule consists of an Identifier and a -Required Structure. If the defined identifier is contained in a topology, the required structure must be -contained as well. -Furthermore, the *Compliance Checker* of Winery can be used to ensure that a given Topology Template -is compliant to the current set of Compliance Rules. -More information can be found [here](ComplianceChecking). + The Topology Compliance Checking of Winery enables to describe restrictions, constraints, and requirements for Topology Templates in form of reusable topology-based Compliance Rules. + These rules can be modeled using the *Compliance Rule Editor* and stored in the *Compliance Rules Repository*. + Each rule consists of an Identifier and a Required Structure. If the defined identifier is contained in a topology, the required structure must be contained as well. + Furthermore, the *Compliance Checker* of Winery can be used to ensure that a given Topology Template is compliant to the current set of Compliance Rules. + More information can be found [here](features/compliance-checking.md). - *Key-based Policy Template Generator*: This functionality allows to generate security policy templates based on keys stored in the key manager. @@ -88,24 +94,20 @@ More information can be found [here](ComplianceChecking). It allows modelers to enforce modeled security requirements at CSAR import and export times. However, this is an administrative functionality that potentially can be used for other purposes. +- *Implementation Artifact Generator*: + To specify what a node type should do, the user can define an interface and the operations provided by this interface. + Once the operations of a node type are defined, artifacts (e.g., shell scripts, .war files) implementing these operations need to be modeled. + With the *Implementation Artifact Generator* a stub java maven project to build a .war file for a defined interface is generated automatically. -- *Implementation Artifact Generator*: To specify what a node type should do, the user can define -an interface and the operations provided by this interface. -Once the operations of a node type are defined, artifacts (e.g., shell scripts, .war files) -implementing these operations need to be modeled. -With the *Implementation Artifact Generator* a stub java maven project to build a .war file -for a defined interface is generated automatically. - -## License - -Copyright (c) 2017-2018 Contributors to the Eclipse Foundation - -See the NOTICE file(s) distributed with this work for additional -information regarding copyright ownership. -This program and the accompanying materials are made available under the -terms of the Eclipse Public License 2.0 which is available at -http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0 -which is available at https://www.apache.org/licenses/LICENSE-2.0. +## Features -SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 +- [Splitting](features/splitting.md) - Splitting functionality +- [Target Allocation](features/target-allocation.md) - Select best suited cloud provider for topologies +- [Topology Completion](features/topology-completion.md) - Topology completion overview +- [XaaS Packager](features/xaas-packager.md) - Enables reusing modeled topologies as templates for single applications +- [Compliance Checking](features/compliance-checking.md) - Enables compliance checking of topology templates based on reusable rules +- [Implementation Artifact Generation](features/generate-ia.md) - Shows how to generate and update an implementation artifact of type `war` +- [Version Management](features/version-management.md) - Shows how to update the version of a node template in the topology modeler +- [Threat Modeling For NFV](features/nfv-threat-modeling.md) - Enables threat modeling capabilities and NFV-based mitigation recommendation +- [Pattern-based Deployment and Configuration Models](features/pattern-deployment-modeling.md) - Describes how PbDCMs can be crated and refined to executable deployment models diff --git a/docs/user/quicksetup.md b/docs/user/quicksetup.md deleted file mode 100644 index 44dfedd4d6..0000000000 --- a/docs/user/quicksetup.md +++ /dev/null @@ -1,54 +0,0 @@ -# Quick Setup - -These steps ensure that - -- You have a set of TOSCA definitions (node types, relationship types, etc) -- Winery sees that TOSCA definitions when you start it. - -## Windows - -Winery has built-in "magic" to check for existance of `C:\winery-repository`. -If that directory exists, this is used as repository location. -If that directory does not exists, it uses the home directory, which is `%HOME%` defaulting to `C:\Users\USERNAME\winery-repository`. - -1. Ensure that git and [git-lfs](https://git-lfs.github.com/) are installed. - 1. Installation using [chocolatey](https://chocolatey.org/): `choco install git git-lfs` - 1. Manual installation: - - Download git installer form and execute it. - - Download git-lfs installer from and execute it. -1. Make repository available. - 1. `mkdir c:\winery-repository`. The name `winery-repository` is important, because of Winery's magic (see above) - 2. `cd c:\winery-repository` - 2. `git config --global core.longpaths true` to enable long paths. Works perfectly on Windows. - 3. `git clone https://github.com/winery/test-repository.git .` to clone the [test repository](https://github.com/winery/test-repository). - 3. Execute `git lfs install` - 4. Uni Stuttgart developers: - 1. `git remote add tosca-definitions-internal https://github.com/OpenTOSCA/tosca-definitions-internal/` to make the [tosca-definitions-internal](https://github.com/OpenTOSCA/tosca-definitions-internal/) known. - 1. `git fetch tosca-definitions-internal` - to fetch the tosca-definitions repository - 6. `git checkout black` - to switch to the main branch of the test repository - 7. Result: Now you are at the [test repository](https://github.com/winery/test-repository) containing testing types. - If you do `git checkout master`, you are seeing the [OpenTOSCA TOSCA Definitions repository](https://github.com/OpenTOSCA/tosca-definitions/). - -## Mac OS X - -Winery stores its repository at `~/winery-repository`. - -This howto is currently incomplete. - -1. Ensure that git and [git-lfs](https://git-lfs.github.com/) are installed. - 1. `brew install git-lfs` - - -## License - -Copyright (c) 2017-2018 Contributors to the Eclipse Foundation - -See the NOTICE file(s) distributed with this work for additional -information regarding copyright ownership. - -This program and the accompanying materials are made available under the -terms of the Eclipse Public License 2.0 which is available at -http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0 -which is available at https://www.apache.org/licenses/LICENSE-2.0. - -SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 diff --git a/docs/user/graphics/modeling/1-AddNewNodeType.jpg b/docs/user/xml/1-AddNewNodeType.jpg similarity index 100% rename from docs/user/graphics/modeling/1-AddNewNodeType.jpg rename to docs/user/xml/1-AddNewNodeType.jpg diff --git a/docs/user/graphics/modeling/1-AddUbuntuNodeType.jpg b/docs/user/xml/1-AddUbuntuNodeType.jpg similarity index 100% rename from docs/user/graphics/modeling/1-AddUbuntuNodeType.jpg rename to docs/user/xml/1-AddUbuntuNodeType.jpg diff --git a/docs/user/graphics/modeling/10-AddNewArtifactTemplate.PNG b/docs/user/xml/10-AddNewArtifactTemplate.png similarity index 100% rename from docs/user/graphics/modeling/10-AddNewArtifactTemplate.PNG rename to docs/user/xml/10-AddNewArtifactTemplate.png diff --git a/docs/user/graphics/modeling/11-AddNewArtifactTemplate.PNG b/docs/user/xml/11-AddNewArtifactTemplate.png similarity index 100% rename from docs/user/graphics/modeling/11-AddNewArtifactTemplate.PNG rename to docs/user/xml/11-AddNewArtifactTemplate.png diff --git a/docs/user/graphics/modeling/12-AddNewNodeTypeImplementation.PNG b/docs/user/xml/12-AddNewNodeTypeImplementation.png similarity index 100% rename from docs/user/graphics/modeling/12-AddNewNodeTypeImplementation.PNG rename to docs/user/xml/12-AddNewNodeTypeImplementation.png diff --git a/docs/user/graphics/modeling/13-AddNewNodeTypeImplementation.PNG b/docs/user/xml/13-AddNewNodeTypeImplementation.png similarity index 100% rename from docs/user/graphics/modeling/13-AddNewNodeTypeImplementation.PNG rename to docs/user/xml/13-AddNewNodeTypeImplementation.png diff --git a/docs/user/graphics/modeling/14-AddNewNodeTypeImplementation-LinkArtifactTemplate.PNG b/docs/user/xml/14-AddNewNodeTypeImplementation-LinkArtifactTemplate.png similarity index 100% rename from docs/user/graphics/modeling/14-AddNewNodeTypeImplementation-LinkArtifactTemplate.PNG rename to docs/user/xml/14-AddNewNodeTypeImplementation-LinkArtifactTemplate.png diff --git a/docs/user/graphics/modeling/15-AddNewNodeTypeImplementation-LinkArtifactTemplate.PNG b/docs/user/xml/15-AddNewNodeTypeImplementation-LinkArtifactTemplate.png similarity index 100% rename from docs/user/graphics/modeling/15-AddNewNodeTypeImplementation-LinkArtifactTemplate.PNG rename to docs/user/xml/15-AddNewNodeTypeImplementation-LinkArtifactTemplate.png diff --git a/docs/user/graphics/modeling/16-AddNewServiceTemplate.JPG b/docs/user/xml/16-AddNewServiceTemplate.jpg similarity index 100% rename from docs/user/graphics/modeling/16-AddNewServiceTemplate.JPG rename to docs/user/xml/16-AddNewServiceTemplate.jpg diff --git a/docs/user/graphics/modeling/17-AddNewServiceTemplate.JPG b/docs/user/xml/17-AddNewServiceTemplate.jpg similarity index 100% rename from docs/user/graphics/modeling/17-AddNewServiceTemplate.JPG rename to docs/user/xml/17-AddNewServiceTemplate.jpg diff --git a/docs/user/graphics/modeling/18-AddNewServiceTemplate.JPG b/docs/user/xml/18-AddNewServiceTemplate.jpg similarity index 100% rename from docs/user/graphics/modeling/18-AddNewServiceTemplate.JPG rename to docs/user/xml/18-AddNewServiceTemplate.jpg diff --git a/docs/user/graphics/modeling/19-AddNewServiceTemplate.JPG b/docs/user/xml/19-AddNewServiceTemplate.jpg similarity index 100% rename from docs/user/graphics/modeling/19-AddNewServiceTemplate.JPG rename to docs/user/xml/19-AddNewServiceTemplate.jpg diff --git a/docs/user/graphics/modeling/2-AddNewNodeType.PNG b/docs/user/xml/2-AddNewNodeType.png similarity index 100% rename from docs/user/graphics/modeling/2-AddNewNodeType.PNG rename to docs/user/xml/2-AddNewNodeType.png diff --git a/docs/user/graphics/modeling/2-AddUbuntuNodeType.jpg b/docs/user/xml/2-AddUbuntuNodeType.jpg similarity index 100% rename from docs/user/graphics/modeling/2-AddUbuntuNodeType.jpg rename to docs/user/xml/2-AddUbuntuNodeType.jpg diff --git a/docs/user/graphics/modeling/20-AddNewServiceTemplate.JPG b/docs/user/xml/20-AddNewServiceTemplate.jpg similarity index 100% rename from docs/user/graphics/modeling/20-AddNewServiceTemplate.JPG rename to docs/user/xml/20-AddNewServiceTemplate.jpg diff --git a/docs/user/graphics/modeling/3-AddNewNodeType.JPG b/docs/user/xml/3-AddNewNodeType.jpg similarity index 100% rename from docs/user/graphics/modeling/3-AddNewNodeType.JPG rename to docs/user/xml/3-AddNewNodeType.jpg diff --git a/docs/user/xml/3-AddUbuntuNodeType.jpg b/docs/user/xml/3-AddUbuntuNodeType.jpg new file mode 100644 index 0000000000..0881369a6f Binary files /dev/null and b/docs/user/xml/3-AddUbuntuNodeType.jpg differ diff --git a/docs/user/graphics/modeling/4-AddNewNodeType.JPG b/docs/user/xml/4-AddNewNodeType.jpg similarity index 100% rename from docs/user/graphics/modeling/4-AddNewNodeType.JPG rename to docs/user/xml/4-AddNewNodeType.jpg diff --git a/docs/user/graphics/modeling/4-AddUbuntuNodeType.jpg b/docs/user/xml/4-AddUbuntuNodeType.jpg similarity index 100% rename from docs/user/graphics/modeling/4-AddUbuntuNodeType.jpg rename to docs/user/xml/4-AddUbuntuNodeType.jpg diff --git a/docs/user/graphics/modeling/5-AddUbuntuNodeType.jpg b/docs/user/xml/5-AddUbuntuNodeType.jpg similarity index 100% rename from docs/user/graphics/modeling/5-AddUbuntuNodeType.jpg rename to docs/user/xml/5-AddUbuntuNodeType.jpg diff --git a/docs/user/graphics/modeling/6-AddNewNodeType-AddInterface.JPG b/docs/user/xml/6-AddNewNodeType-AddInterface.jpg similarity index 100% rename from docs/user/graphics/modeling/6-AddNewNodeType-AddInterface.JPG rename to docs/user/xml/6-AddNewNodeType-AddInterface.jpg diff --git a/docs/user/graphics/modeling/6-AddUbuntuNodeType.jpg b/docs/user/xml/6-AddUbuntuNodeType.jpg similarity index 100% rename from docs/user/graphics/modeling/6-AddUbuntuNodeType.jpg rename to docs/user/xml/6-AddUbuntuNodeType.jpg diff --git a/docs/user/graphics/modeling/7-AddNewArtifactTemplate.PNG b/docs/user/xml/7-AddNewArtifactTemplate.png similarity index 100% rename from docs/user/graphics/modeling/7-AddNewArtifactTemplate.PNG rename to docs/user/xml/7-AddNewArtifactTemplate.png diff --git a/docs/user/xml/7-AddUbuntuNodeType.jpg b/docs/user/xml/7-AddUbuntuNodeType.jpg new file mode 100644 index 0000000000..de274bd16e Binary files /dev/null and b/docs/user/xml/7-AddUbuntuNodeType.jpg differ diff --git a/docs/user/graphics/modeling/8-AddNewArtifactTemplate.PNG b/docs/user/xml/8-AddNewArtifactTemplate.png similarity index 100% rename from docs/user/graphics/modeling/8-AddNewArtifactTemplate.PNG rename to docs/user/xml/8-AddNewArtifactTemplate.png diff --git a/docs/user/graphics/modeling/9-AddNewArtifactTemplate.PNG b/docs/user/xml/9-AddNewArtifactTemplate.png similarity index 100% rename from docs/user/graphics/modeling/9-AddNewArtifactTemplate.PNG rename to docs/user/xml/9-AddNewArtifactTemplate.png diff --git a/docs/user/quickstart.md b/docs/user/xml/index.rst similarity index 56% rename from docs/user/quickstart.md rename to docs/user/xml/index.rst index 085e2d4a73..bd41c00721 100644 --- a/docs/user/quickstart.md +++ b/docs/user/xml/index.rst @@ -1,36 +1,57 @@ -# Quickstart +.. Copyright (c) 2020 Contributors to the Eclipse Foundation + +.. See the NOTICE file(s) distributed with this work for additional +.. information regarding copyright ownership. + +.. This program and the accompanying materials are made available under the +.. terms of the Eclipse Public License 2.0 which is available at +.. http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0 +.. which is available at https://www.apache.org/licenses/LICENSE-2.0. + +.. SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 + + +Modeling based on TOSCA XML (deprecated) +######################################## This guide shows an overview of how to model TOSCA node types and service templates using Winery. -Before starting this guide, please take a look at the [Miscellaneous Notes](#miscellaneous-notes). +Before starting this guide, please take a look at :ref:`Miscellaneous Notes`. -## Modeling a Topology in Winery The following shows how to model new node types and how to use them at the modeling of a new service template. In this example, the runtime **Python3** shall be installed on an **Ubuntu 14.04** virtual machine running on an **Openstack** infrastructure. For this, we require three node types. In this example, we model two node types, Python3 and Ubuntu 14.04, and assume that the OpenStack node type was previously modeled. -### Creating a new Node Type + +Creating a new Node Type +************************ By selecting the tab *Node Types*, a list of available node types is shown. To create a new node type, press the button *Add new*. -![1-AddNewNodeType](graphics/modeling/1-AddNewNodeType.jpg) +.. image:: 1-AddNewNodeType.jpg + :width: 600 This will open a dialog in which the *Name*, *Component version*, and *Namespace* of the new node type can be configured. -![2-AddNewNodeType](graphics/modeling/2-AddNewNodeType.PNG) +.. image:: 2-AddNewNodeType.png + :width: 600 Once the node type is created, it can be further configured through different tabs of its detailed view. -![3-AddNewNodeType](graphics/modeling/3-AddNewNodeType.JPG) +.. image:: 3-AddNewNodeType.jpg + :width: 600 For example, to add properties to the node type, select the tab *Properties Definition*. -![4-AddNewNodeType](graphics/modeling/4-AddNewNodeType.JPG) +.. image:: 4-AddNewNodeType.jpg + :width: 600 In this example, the Python3 node type does not require any properties. -### Modeling the Node Type Interface + +Modeling the Node Type Interface +******************************** To specify what the *Python3* node type should do, we define an *interface* and the *operations* provided by this interface. An interface containing lifecycle operations (install, configure, start, stop, uninstall) can be automatically generated, however, any arbitrary interface can be created. @@ -38,124 +59,148 @@ An interface containing lifecycle operations (install, configure, start, stop, u To generate a lifecycle interface, press *Generate Lifecycle Interface* and *Save*. For the node type Python3, we only use the operation *install*. -![6-AddNewNodeType](graphics/modeling/6-AddNewNodeType-AddInterface.JPG) +.. image:: 6-AddNewNodeType-AddInterface.jpg + :width: 600 + -### Modeling an Artifact Template for a Node Type Operation +Modeling an Artifact Template for a Node Type Operation +******************************************************* Once the operations of a node type are defined, artifacts (e.g., shell scripts, .war files) implementing these operations need to be modeled. In this example, we have a *shell script* to install Python3 on Ubuntu, which we model as an artifact template. To create an artifact template, select the tab *Other Elements*, under the category *Artifacts* select the option *Artifact Templates*, and press the button *Add new*. -![7-AddNewNodeType](graphics/modeling/7-AddNewArtifactTemplate.PNG) +.. image:: 7-AddNewArtifactTemplate.png + :width: 600 -![8-AddNewNodeType](graphics/modeling/8-AddNewArtifactTemplate.PNG) +.. image:: 8-AddNewArtifactTemplate.png + :width: 600 This will open a dialog in which the *Name*, *Versioning*, *Type*, and *Namespace* of the artifact template can be configured. Assuming that some artifact types were previously modeled, choose the type *ScriptArtifact*. -![9-AddNewNodeType](graphics/modeling/9-AddNewArtifactTemplate.PNG) +.. image:: 9-AddNewArtifactTemplate.png + :width: 600 Once the artifact template is created, it can be further configured through different tabs of its detailed view. -![10-AddNewNodeType](graphics/modeling/10-AddNewArtifactTemplate.PNG) +.. image:: 10-AddNewArtifactTemplate.png + :width: 600 Finally, to load th install script to the artifact template, select the tab *Files*, and drop the file into the drop zone. -![11-AddNewNodeType](graphics/modeling/11-AddNewArtifactTemplate.PNG) +.. image:: 11-AddNewArtifactTemplate.png + :width: 600 -### Modeling the Node Type Implementation + +Modeling the Node Type Implementation +************************************* To create a node type implementation, select the tab *Other Elements*, under the the category *Implementations* select the option *Node Type Implementations*, and press the button *Add new*. This will open a dialog in which the *Name*, the corresponding node *type*, and *Namespace* of the node type implementation can be configured. By type, select the node type we created before. -![12-AddNewNodeType](graphics/modeling/12-AddNewNodeTypeImplementation.PNG) +.. image:: 12-AddNewNodeTypeImplementation.png + :width: 600 -![13-AddNewNodeType](graphics/modeling/13-AddNewNodeTypeImplementation.PNG) +.. image:: 13-AddNewNodeTypeImplementation.png + :width: 600 To link the created artifact template to this node type implementation, select the tab *Implementation Artifacts* and press the button *Add*. In the shown dialog, choose the option *Link Artifact Template*, then select the artifact template that was previously created. -![14-AddNewNodeType](graphics/modeling/14-AddNewNodeTypeImplementation-LinkArtifactTemplate.PNG) +.. image:: 14-AddNewNodeTypeImplementation-LinkArtifactTemplate.png + :width: 600 + +.. image:: 15-AddNewNodeTypeImplementation-LinkArtifactTemplate.png + :width: 600 -![15-AddNewNodeType](graphics/modeling/15-AddNewNodeTypeImplementation-LinkArtifactTemplate.PNG) -### Modeling the Ubuntu Node Type +Modeling the Ubuntu Node Type +***************************** The modeling of the Ubuntu node type is similar to the modeling of the Python3 node type. -![1-AddUbuntuNodeType](graphics/modeling/1-AddUbuntuNodeType.jpg) +.. image:: 1-AddUbuntuNodeType.jpg + :width: 600 -![2-AddUbuntuNodeType](graphics/modeling/2-AddUbuntuNodeType.jpg) +.. image:: 2-AddUbuntuNodeType.jpg + :width: 600 -However, the artifact templates for the Ubuntu 14.04 are *.war files* instead of *shell scripts*. In this case, after defining the *interfaces* and *operations* of the Ubuntu node type, we can automatically generate a stub java maven project to build a *.war file* for a defined interface. For this, press *Generate Implementation Artifact*. The node type implementation will be automatically generated as well. +However, the artifact templates for the Ubuntu 14.04 are *.war files* instead of *shell scripts*. +In this case, after defining the *interfaces* and *operations* of the Ubuntu node type, we can automatically generate a stub java maven project to build a *.war file* for a defined interface. +For this, press *Generate Implementation Artifact*. The node type implementation will be automatically generated as well. -![3-AddUbuntuNodeType](graphics/modeling/3-AddUbuntuNodeType.jpg) +.. image:: 3-AddUbuntuNodeType.jpg + :width: 600 -![4-AddUbuntuNodeType](graphics/modeling/4-AddUbuntuNodeType.jpg) +.. image:: 4-AddUbuntuNodeType.jpg + :width: 600 -![5-AddUbuntuNodeType](graphics/modeling/5-AddUbuntuNodeType.jpg) +.. image:: 5-AddUbuntuNodeType.jpg + :width: 600 -![6-AddUbuntuNodeType](graphics/modeling/6-AddUbuntuNodeType.jpg) +.. image:: 6-AddUbuntuNodeType.jpg + :width: 600 After editing the generated stub project, we can built it and load the resulting .war file to the artifact template in the tab *Files*. -![7-AddUbuntuNodeType](graphics/modeling/7-AddUbuntuNodeType.jpg) +.. image:: 7-AddUbuntuNodeType.jpg + :width: 600 -### Creating the Service Template + +Creating the Service Template +***************************** To finally model the service template, at the tab *Services Templates*, press *Add new*. -![16-AddNewNodeType](graphics/modeling/16-AddNewServiceTemplate.JPG) +.. image:: 16-AddNewServiceTemplate.jpg + :width: 600 Go to tab *Topology Template* and press the button *Open Editor*. -![17-AddNewNodeType](graphics/modeling/17-AddNewServiceTemplate.JPG) +.. image:: 17-AddNewServiceTemplate.jpg + :width: 600 In the editor, the *Palette* on the left shows the available node types, which can be drag and dropped in the modeling area. -![18-AddNewNodeType](graphics/modeling/18-AddNewServiceTemplate.JPG) +.. image:: 18-AddNewServiceTemplate.jpg + :width: 600 + +To model the relationship that the Python3 runtime is hosted on the Ubuntu virtual machine, click at the Python3 node template. +This will show a list of possible relationship types (previously modeled). Click in the option *HostedOn* and pull the shown arrow to the Ubuntu node template area, in order to connect these node templates. -To model the relationship that the Python3 runtime is hosted on the Ubuntu virtual machine, click at the Python3 node template. This will show a list of possible relationship types (previously modeled). Click in the option *HostedOn* and pull the shown arrow to the Ubuntu node template area, in order to connect these node templates. +.. image:: 19-AddNewServiceTemplate.jpg + :width: 600 -![19-AddNewServiceTemplate](graphics/modeling/19-AddNewServiceTemplate.JPG) -### Exporting a Service Template Package +Exporting a Service Template Package +************************************ To export the Service Template as a CSAR package, press *Other*, then *Export CSAR*. -![20-AddNewServiceTemplate](graphics/modeling/20-AddNewServiceTemplate.JPG) +.. image:: 20-AddNewServiceTemplate.jpg + :width: 600 -## Miscellaneous Notes +Miscellaneous Notes +******************* Properties of a Template can be either full XML or key/value based. If key/value based, a wrapper XML element is required. -Since QNames have to be unique, Winery proposes as namespace the namespace of the template appended by `propertiesdefinition/winery`. -The name of the wrapper element is `properties`. +Since QNames have to be unique, Winery proposes as namespace the namespace of the template appended by ``propertiesdefinition/winery``. +The name of the wrapper element is ``properties``. + +.. note:: - + Implementation hint: This is implemented in ``PropertiesDefinitionComponent.onCustomKeyValuePairSelected`` (TS) and ``org.eclipse.winery.model.tosca.TEntityType.getWinerysPropertiesDefinition`` (Java). -### Uniqueness of QNames + +Uniqueness of QNames +******************** Intentionally, a QName should be unique within the repository. We did not follow this assumption, but only require that QNames are unique within a type. -That means, the repository allows `{http://www.example.org}id` for both a service template and a node type. +That means, the repository allows ``{http://www.example.org}id`` for both a service template and a node type. We introduced DefinitionsChildId uniquely identifying a TOSCA element. Future versions might redesign the backend to use a QName as the unique key. - -## License - -Copyright (c) 2017-2018 Contributors to the Eclipse Foundation - -See the NOTICE file(s) distributed with this work for additional -information regarding copyright ownership. - -This program and the accompanying materials are made available under the -terms of the Eclipse Public License 2.0 which is available at -http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0 -which is available at https://www.apache.org/licenses/LICENSE-2.0. - -SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 diff --git a/docs/user/yml/1-CreateServiceTemplate.gif b/docs/user/yml/1-CreateServiceTemplate.gif new file mode 100644 index 0000000000..bbdaf4796a Binary files /dev/null and b/docs/user/yml/1-CreateServiceTemplate.gif differ diff --git a/docs/user/yml/2-ModelNodeTemplates.gif b/docs/user/yml/2-ModelNodeTemplates.gif new file mode 100644 index 0000000000..56f0329180 Binary files /dev/null and b/docs/user/yml/2-ModelNodeTemplates.gif differ diff --git a/docs/user/yml/3-AdaptPropertiesAddArtifacts.gif b/docs/user/yml/3-AdaptPropertiesAddArtifacts.gif new file mode 100644 index 0000000000..3ba55c90c3 Binary files /dev/null and b/docs/user/yml/3-AdaptPropertiesAddArtifacts.gif differ diff --git a/docs/user/yml/4-ModelRelationships.gif b/docs/user/yml/4-ModelRelationships.gif new file mode 100644 index 0000000000..47c825516e Binary files /dev/null and b/docs/user/yml/4-ModelRelationships.gif differ diff --git a/docs/user/yml/5-ExportCsar.gif b/docs/user/yml/5-ExportCsar.gif new file mode 100644 index 0000000000..2162a60015 Binary files /dev/null and b/docs/user/yml/5-ExportCsar.gif differ diff --git a/docs/user/yml/index.rst b/docs/user/yml/index.rst new file mode 100644 index 0000000000..1a32669667 --- /dev/null +++ b/docs/user/yml/index.rst @@ -0,0 +1,74 @@ +.. Copyright (c) 2020 Contributors to the Eclipse Foundation + +.. See the NOTICE file(s) distributed with this work for additional +.. information regarding copyright ownership. + +.. This program and the accompanying materials are made available under the +.. terms of the Eclipse Public License 2.0 which is available at +.. http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0 +.. which is available at https://www.apache.org/licenses/LICENSE-2.0. + +.. SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 + + +Modeling with Winery +#################### + +Launch a browser and navigate to ``_. + + +Modeling an Application +*********************** + +Eclipse Winery starts in the *Service Template* view. +In this view, users can create new TOSCA service template or maintain existing ones. + +To create a new TOSCA service template click on *Add new*. +In the "Add new" pop up you can specify your template's name, enable/disable versioning, and specify the namespace to be used. + +.. image:: 1-CreateServiceTemplate.gif + +.. warning:: + Do not use spaces in your service template name. + Use ``_`` or ``-`` to separate names. + +In the *Service Template Detail* view you can add some readme text and assign a respective license. +Further, to compose your application open the *Topology Modeler* by ``Topology Template > Open Editor``. + +Model Node Templates +-------------------- + +In the editor, you can drag and drop existing TOSCA node types to the canvas to define a new TOSCA node template. +You can select a modeled node to modify its display name and additional data using the right pane. + +.. image:: 2-ModelNodeTemplates.gif + +You can change properties or add artifacts by enabling the *Properties* or *Artifacts* view in the header bar. + +.. image:: 3-AdaptPropertiesAddArtifacts.gif + + +Define Relations Between Node Templates +--------------------------------------- + +Relationships in TOSCA (according to TOSCA YAML 1.3) are modeled using matching *Requirements* and *Capabilities* +(please refer to the standard to get more detailed information or checkout the :ref:`tosca` page). + +In the *Topology Modeler*, you can enable the *Requirements & Capabilities* view in the header bar. +Then, open the *Requirements* of the source node and the *Capabilities* of the target node. +Finally, drag a respective relationship type (e.g., ``HostedOn``) from the requirement (e.g., ``host``) to a matching capability (e.g., ``host``). + +.. image:: 4-ModelRelationships.gif + + +Export CSAR +*********** + +The TOSCA exchange format is a Cloud Service Archive (CSAR). +A CSAR is essentially a ZIP file following a certain directory layout and contains all necessary files and template to execute the deployment of the modeled application. + +Open the *Service Template* view. +Search for your service template and open it. +In the *Service Template Detail* view you can click on *Export* either to *Download* the CSAR or to save it to the filesystem (``/csars`` on your host system). + +.. image:: 5-ExportCsar.gif diff --git a/org.eclipse.winery.accountability/README.md b/org.eclipse.winery.accountability/README.md index 59a0deec1c..5db10c65e5 100644 --- a/org.eclipse.winery.accountability/README.md +++ b/org.eclipse.winery.accountability/README.md @@ -103,19 +103,19 @@ Registering new CSARs in the blockchain, as well as storing their contents in th happens at export-time using the button entitled "Provenance CSAR (XML)". The button will not appear if the accountability feature is not configured and enabled (see above): -![Registering Exported CSARs in the Blockchain](../docs/user/graphics/accountability/Exporting.PNG). +![](../docs/user/features/figures/Exporting.png). ### Validating the Integrity of Imported CSARS Validation of CSAR happens automatically at import-time if the accountability feature is configured (see above), and a specific option is checked in the import CSAR dialog: -![Validating the Integrity of Imported CSARS](../docs/user/graphics/accountability/Validation.PNG) +![](../docs/user/features/figures/Validation.png) After the validation process is over, a summary is shown that allows exploring the contents of the imported CSAR and viewing the provenance of each contained file, and even download previous versions of it: -![Validating the Integrity of Imported CSARS](../docs/user/graphics/accountability/ValidationResult.PNG) +![](../docs/user/features/figures/ValidationResult.png) ### Authorizing Users to Particiate in Collaborative CSAR Development @@ -123,12 +123,12 @@ Authorization of users to work on specific CSARS (service templates) takes place Here the Ethereum address (0x + 40-places hexadecmial number) is entered along with a human-readable name that is not required to be unique: -![Authorizing Users to Particiate in Collaborative CSAR Development](../docs/user/graphics/accountability/Authorization.PNG) +![](../docs/user/features/figures/Authorization.png) Authorized participants are automatically verified during CSAR-import process. However, one can manually verify the authenticity of a given participant using a different sub-UI of the Winery Admin UI: -![Manual Authentication of Participants](../docs/user/graphics/accountability/Authentication.PNG) +![](../docs/user/features/figures/Authentication.png) ### Checking the Provenance of a CSAR and its Contents @@ -136,17 +136,17 @@ The provenance of a given service template, i.e, the immutable history of versio of those versions, can be accessed using the "Provenance" UI of the Winery Admin UI. Here the desired service template id is selected and the button "Show Provenance" is pressed: -![Checking the Provenance of a CSAR](../docs/user/graphics/accountability/Provenance1.PNG) +![](../docs/user/features/figures/Provenance1.png) When the user clicks on one of the provenance entries, more details are shown including details about each of the files contained in this version: -![Checking the Contents of an Exported CSAR](../docs/user/graphics/accountability/Provenance2.PNG) +![](../docs/user/features/figures/Provenance2.png) Any of these files can be downloaded using the "(download)" link below it. Moreover, it can be compared with other versions of it using the "(compare)" link which shows the following dialog: -![Comparing the Various Versions of the Files of a CSAR](../docs/user/graphics/accountability/FileComparison.PNG) +![](../docs/user/features/figures/FileComparison.png) ## Demonstrative Scenarios @@ -230,4 +230,3 @@ http://www.eclipse.org/legal/epl-2.0, or the Apache Software License 2.0 which is available at https://www.apache.org/licenses/LICENSE-2.0. SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 -