summaryrefslogtreecommitdiffstats
path: root/winery/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'winery/README.md')
-rw-r--r--winery/README.md184
1 files changed, 184 insertions, 0 deletions
diff --git a/winery/README.md b/winery/README.md
new file mode 100644
index 0000000..7d3a95e
--- /dev/null
+++ b/winery/README.md
@@ -0,0 +1,184 @@
+# Winery
+Winery is a Web-based environment to graphically model TOSCA topologies and plans managing these topologies.
+It is an Eclipse project and thus support is available through its project page https://projects.eclipse.org/projects/soa.winery.
+Winery is also part of the OpenTOSCA ecosystem where more information is available at http://www.opentosca.org.
+
+**The code and the linked libraries are NOT approved by Eclipse Legal. Dependencies are fetched from external mirrors and not from an Eclipse repository.**
+
+## Runtime Requirements
+* Java 7
+* Servlet 3.0 capable container (e.g., Tomcat 7)
+
+## Development Information
+
+Winery uses maven and [bower] for fetching dependencies and building.
+Bower has to be installed manually as described in the next section.
+
+## Install bower
+
+1. Install [nodejs]. Just use the latest version to get the latest node package manager (npm).
+1. Run `npm install -g bower`
+1. Ensure that `git` is in your path: Some javascript libraries are fetched via git.
+
+
+## Make models available
+
+The models are versioned aside from the main project.
+Go into each model directory (`org.eclipse.winery.model.csar.toscametafile`, `org.eclipse.winery.model.selfservice`, `org.eclipse.winery.model.tosca`) and do a `mvn install`.
+
+
+## Making the wars
+Run `mvn clean package`.
+In case [bower] fails, try to investigate using `mvn package -X`.
+You can start bower manually in `org.eclipse.winery.repository` and `org.eclipse.winery.topologymodeler` by issuing `bower install`.
+
+There are two WARs generated:
+
+* `org.eclipse.winery.repository/target/winery.war` and
+* `org.eclipse.winery.topologymodeler/target/winery-topologymodeler.war`
+
+They can be deployed on a Tomcat runtime environment.
+
+## Branches
+The `master` branch is always compiling and all tests should go through.
+It contains the most recent improvements.
+All other branches are real development branches and might event not compile.
+
+There are no explicit branches for stable versions as winery is currently in development-only mode.
+
+## Projects
+
+### Model projects
+Each of these projects are versioned separately.
+
+* org.eclipse.winery.model.csar.toscametafile: model for TOSCA meta files contained in a CSAR
+* org.eclipse.winery.model.selfservice: model for the self service portal
+* org.eclipse.winery.model.tosca: model for TOCSA
+
+### Support projects
+* org.eclipse.winery.highlevelrestapi: support library to REST calls.
+
+### Winery itself
+Versioned together to ease development.
+
+* org.eclipse.winery.common: Used in repository and topology modeler
+* org.eclipse.winery.generators.ia: Implementation Artifact Generator, used as component in the repository
+* org.eclipse.winery.repository: the repository including a JSP-based UI
+* org.eclipse.winery.repository.client: Java-client for the repository
+* org.eclipse.winery.topologymodeler: Graph-based modeler for topology templates
+
+## Next steps
+Winery currently is far from being a production ready modeling tool.
+The next steps are:
+
+* UI design improvements
+ * Have Orion support `XML` as language. See also [Bug 421284][bug421284]
+* Add more usability features to the topology modeler
+* Remove non-required files from components/ directory to reduce the file size of the WAR file
+ * This has to be done by submitting patches to `bower.json` of the upstream libraries
+* Develop a plugin-system for user-defined editors. For instance, a constraint has a type. If a type is known to Winery, it can present a specific plugin to edit the type content instead of a generic XML editor.
+* Rework file storage. Currently, files are stored along with their definitions. A new storage should store all files in one place and use an SHA1 id to uniquely identify the file. Then, it does not make any difference if storing a WAR, an XSD, or an WSDL.
+* Add a real DAO layer to enable querying the available TOSCA contents using SQL or similar query language
+
+Currently, `.jsp` files package HTML and JS.
+We plan to use frameworks such as [TerrificJS] to provide a better modularity.
+This follows Nicholas Zakas' "[Scalable JavaScript Application Architecture]".
+
+## Known issues
+* XSD Type declarations are not directly supported
+** Declared types are converted to imports during a CSAR Import
+** Editing of XSDs is not possible
+* **The XSD of OASIS TOSCA v1.0 has been modified**
+** An Implementation Artifact may carry a `name` attribute
+** The contents of properties of Boundary Definitions are processed in `lax` mode
+
+## Eclipse setup
+This howto is based on [Eclipse Standard 4.3].
+First of all, generate a war to have all dependencies fetched by maven.
+
+### Required plugins
+* JST Server Adapters Extensions
+* Eclipse Java EE Developer Tools
+* Eclipse Java Web Developer Tools
+* [m2e-wtp]: Maven Integration for WTP
+* [AnyEdit](http://andrei.gmxhome.de/anyedit/) for ensuring that tabs are always used
+** Configure: Window -> Preferences -> General / Editors / AnyEdit Tools -> "Auto - Convert EXCLUSION file list" -> "Add filter" -> "*.java", "Convert...": 4 spaces for a tab
+
+### Optional plugins
+* [Eclipse Code Recommenders](http://www.eclipse.org/recommenders/)
+* [VJET JavaScript IDE](http://www.eclipse.org/proposals/webtools.vjet/)
+
+### Make Winery projects known to Eclipse
+1. Import all projects
+ * Use "Existing Maven Projects". `mvn eclips:m2eclipse` currently does not enable "maven" in eclipse.
+2. For each project: right click, –> Team –> Share Project –> Git –> Next –> check "Use or create repository in parent folder of project" –> Finish
+3. At `org.eclipse.winery.repository` and ` org.eclipse.winery.topologymodeler`:
+ * Right click -> Properties -> JavaScript -> Include Path -> Source -> Expand folder -> Select "Excluded" -> "Edit..."
+ * Exclusion Patterns: Add multiple -> Select "3rd party" -> "OK"
+ * Exclusion Patterns: Add multiple -> Select "components" -> "OK"
+ * "Finish" -> "OK"
+
+### Setup Tomcat
+1. Open servers window: Window -> Show View -> Other -> Server -> Servers
+2. New server wizard... -> Apache -> Tomcat v7.0 Server -> Next -> Winery -> Add -> Finish
+3. Rename the Server to "Apache Tomcat v7.0"
+
+Now you can see the Tomcat v7.0 Server at localhost [Stopped, Republish] in your server window.
+Select it and click on the green play button in the window.
+
+Now winery can be viewed at http://localhost:8080/winery/
+
+### Configure Winery (optional)
+The repository location can be changed:
+Copy `winery.properties` to `path-to-workspace\.metadata\.plugins\org.eclipse.wst.server.core\tmp0\wtpwebapps\winery`.
+
+### Trouble shooting
+* In case some JavaScript libraries cannot be found by the browser, execute `bower prune`, `bower install`, `bower update` in both `org.eclipse.winery.repository` and `org.eclipse.winery.topologymodeler`.
+* See [README.md of the repository](org.eclipse.winery.repository/README.md)
+* See [README.md of the topology modeler](org.eclipse.winery.topologymodeler/README.md)
+
+#### Libraries
+
+* Do NOT update to jQuery 2.1.0. When using with firefox, line 5571 in jquery.js fails: `divStyle is null`. That means `window.getComputedStyle( div, null );` returned null, too.
+* Do NOT update to jsPlumb 1.5.5. The new connection type determination does not play well together with Winery's usage of jsPlumb.
+
+## Acknowledgements
+The initial code contribution has been supported by the [Federal Ministry of Economics and Technology] as part of the [CloudCycle project] (01MD11023).
+
+## License
+Copyright (c) 2012-2014 University of Stuttgart.
+
+All rights reserved. This program and the accompanying materials
+are made available under the terms of the [Eclipse Public License v1.0]
+and the [Apache License v2.0] which both accompany this distribution,
+and are available at http://www.eclipse.org/legal/epl-v10.html
+and http://www.apache.org/licenses/LICENSE-2.0
+
+Contributors:
+* Oliver Kopp - initial API and implementation
+
+## Literature
+
+### About TOSCA
+* Binz, T., Breiter, G., Leymann, F., Spatzier, T.: Portable Cloud Services Using TOSCA. IEEE Internet Computing 16(03), 80--85 (May 2012). [DOI:10.1109/MIC.2012.43]
+* Topology and Orchestration Specification for Cloud Applications Version 1.0. 25 November 2013. OASIS Standard. http://docs.oasis-open.org/tosca/TOSCA/v1.0/os/TOSCA-v1.0-os.html
+* OASIS: Topology and Orchestration Specification for Cloud Applications (TOSCA) Primer Version 1.0 (2013)
+
+See http://www.opentosca.org/#publications for a list of publications in the OpenTOSCA ecosystem.
+
+### Programming
+* Joshua Bloch. Effective Java, 2nd edition. Addison-Wesley
+
+ [bug421284]: https://bugs.eclipse.org/bugs/show_bug.cgi?id=421284
+ [bower]: https://github.com/bower/bower
+ [DOI:10.1109/MIC.2012.43]: http://dx.doi.org/10.1109/MIC.2012.43
+ [nodejs]: http://nodejs.org/download/
+ [Eclipse Public License v1.0]: http://www.eclipse.org/legal/epl-v10.html
+ [Eclipse Standard 4.3]: http://www.eclipse.org/downloads/
+ [Apache License v2.0]: http://www.apache.org/licenses/LICENSE-2.0.html
+ [Federal Ministry of Economics and Technology]: http://www.bmwi.de/EN/root.html
+ [CloudCycle project]: http://www.cloudcycle.org/en/
+ [m2eclipse]: http://eclipse.org/m2e/
+ [m2e-wtp]: http://eclipse.org/m2e-wtp/
+ [Scalable JavaScript Application Architecture]: http://www.slideshare.net/nzakas/scalable-javascript-application-architecture-2012
+ [TerrificJS]: http://terrifically.org/