--- tags: [ "eclipse" , "che" ] title: Assemblies excerpt: "An assembly is a packaging of Che libraries and plug-ins distributable as a desktop IDE or workspace server." layout: docs permalink: /:categories/assemblies/ --- The assemblies generated by Che can be packaged and distributed as a new desktop IDE or workspace server. You can reuse this infrastructure to customize how assemblies and installers are generated. To do so, you must learn about the assembly module and dependency hierarchy. # Che Layout A Che assembly has the following directory structure after it is installed. ```text /bin # Scripts to start, stop, and manage Che /conf # Configuration files /lib # Workspace agent, terminal and other resources a workspace may require /plugins # Staging for Che plugins that you author /sdk # Che packaging with SDK tools required to compile custom Che assemblies /templates # Project samples that appear in dashboard or IDE /tomcat # App server used as a runner for Che extensions, packaged with war and jar artifacts\ ``` # Modules The purpose of the `http://github.com/eclipse/che/assembly` module is to generate Che assemblies. It has five sub-modules. ```text assembly-main # Contains the base structure of a Che assembly assembly-ide-war # Generates the IDE web app (ide.war) loaded by Che server (client side) assembly-wsagent-server # Contains the base structure of a workspaces server assembly-wsagent-war # Generates a machine web app (ide.war) used by workspace agent (server side APIs) assembly-wsmaster-war # Generates IDE web app with server side components\ ``` Run `mvn clean install` in the `/assembly` module to build the project and generate an assembly. The output of the `mvn clean install` command generates a new assembly and places the resulting files in the `target` folder. The `assembly-ide-war` module is the longest operation as it uses a GWT compilation operation to generate cross-browser JavaScript from numerous Java libraries. You can speed the assembly generation process by building `assembly-main`, which will download the latest IDE web application from Che's nexus repositories. ```text /assembly-main /target /archive-tmp /eclipse-che-{version} # Exploded tree of assembly /dependency # Copied into /lib folder of assembly /dependency-maven-plugin-markers /findbugs eclipse-che-{version}.tar.gz # TAR file of assembly eclipse-che-{version}.zip # ZIP file of assembly\ ``` # Custom Assemblies You can generate assemblies that include custom plug-ins and [extensions](doc:developing-extensions). Custom assemblies can be distributed as ZIP or TGZ packages. ```shell che-install-plugin [OPTIONS] -a --assembly Creates new distributable Che assembly with your plugins -s:deps, --skip:deps Skips automatic injection of POM dependencies of your plugins -s:maven, --skip:maven Skips running maven to inject your plugins into local repository -s:update, --skip:update Skips updating this assembly; leaves packages in /temp build dir -s:wsagent, --skip:wsagent Skips creating new ws agent -s:wsmaster, --skip:wsmaster Skips creating new ws master, which contains IDE & ws manager -d, --debug Additional verbose logging for this program -h, --help This help message \ ``` This utility will create new web application packages with your custom plugins and optionally create new assemblies. Custom plug-ins are placed into the /plugins directory. Che packages extensions and plug-ins into Web application packages that are then deployed by Che. The location of your plug-ins determines how your plug-ins will be packaged and deployed. Place plug-in JARs & ZIPs: | PlugIn_Location>>>>>> | What Is Built | --- | --- | `/plugins/ide` | IDE extension, compiled with GWT & packaged into new ws-master Web application. | `/plugins/ws-master` | Server-side extension & packaged into new ws-master Web application with IDE. | `/plugins/ws-agent` | Server-side extension that runs in workspace machine & packaged into new ws-agent Web application. | `/` | Packaged in both ws-master and ws-agent Web applications. (Not Recommended) You extension is compiled into one of two Web applications: 1. Workspace Master. 2. Workspace Agent. The workspace master is deployed into the core Che server. The workspace agent is deployed into the machine powering each workspace created by your users. Each workspace agent is unique to the workspace that created it. While you can deploy plug-ins into both locations, this is costly at compile and runtime. The Che assembly is generated by Che utility in stages. ```text 1. Install your plug-ins to a local maven repository. 2. Create a staging module to build new Web applications `/sdk/assembly-ide-war/temp` --> Where ws-master web app will be generated `/sdk/assembly-machine-war/temp` --> Where ws-agent web app will generated 3. Your plug-ins are added as dependencies to the maven pom.xml in each staging module. 4. The new Web application packages are compiled and packaged in the staging directory. `mvn sortpom:sort` `mvn -Denforcer.skip=true clean package install -Dskip-validate-sources=true` 5. If your plug-ins are added into a workspace agent Web app, we then create a new ws-agent.zip. `/sdk/assembly-machine-server` --> Packages ws agent Web app w/ Tomcat into ws-agent.zip. `mvn -Denforcer.skip=true clean package install` 6. The new Web applications are copied into your core Che assembly, overwriting old version. `/sdk/assembly-ide-war/temp/target/*.war` --> /tomcat/webapps `/sdk/assembly-machine-server/target/*.zip` --> /lib/ws-agent.zip Use `--skip:update` to avoid overwriting existing files. 7. If `--assembly`, then we create a new distributable package of Che. `/sdk/assembly-main` `mvn clean package`\ ``` # Runtime Deployment When Che is running, the embedded assets are deployed into different locations. ```text BROWSER CLIENT CHE SERVER WORKSPACE (DOCKER) launches ws-agent.zip in workspace -----> /webapps/ide.war launches terminal in workspace -----> /webapps/terminal JS / CSS / HTML -- download from ----> /tomcat/webapps/ide.war JS / CSS / HTML -- download from ----> /tomcat/webapps/dashboard.war JS / CSS / HTML -- download from ------------------------------------------------> /webapps/ide.war JS / CSS / HTML -- download from ------------------------------------------------> /webapps/terminal\ ``` Your browser clients download JavaScript, HTML, and CSS resources from two different locations, both from the Che server and from a second Che server that is running within the workspace. Each workspace has its own `ws-agent.zip` that is injected into the workspace at runtime by Che. The `ws-agent.zip` contains a second application server that is booted when the workspace is activated. While both the Che server and the `ws-agent.zip` each have an `ide.war` web application within them, they are not identical. There are numerous common libraries between the two, but the Che server hosts the primary IDE files that are shared by clients across all workspace development, and the `ws-agent.zip` deployment contains additional libraries for plug-ins that perform workspace modification (such as doing local JDT intellisense) along with additional Che classes that make it possible for the workspace agent to communicate over REST to the Che server. The `dashboard.war` web application is an Angular JS application that provides the user dashboard that is booted when Che launches. It is used for managing workspaces, projects and user preferences. # Assembly Dependency Hierarchy There are two servers that are deployed when Che is started: 1. The Che server, and: 2. The workspace agent, which is a server running in each workspace The Che assembly, packaged as `eclipse-che-{version}.zip` contains both servers. The following charts layout which assembly modules build each of the assets. ```text eclipse-che-{version}.zip ==> Generated by assembly-main -> ide.war ==> Placed in /tomcat/webapps ==> Generated by assembly-ide-war -> dashboard.war ==> Placed in /tomcat/webapps ==> Generated by che-dashboard repo -> wsmaster.war ==> Placed in /tomcat/webapps ==> Generated by assembly-wsmaster-war -> ws-agent.zip ==> Placed in /lib ==> Generated by assembly-machine-server -> terminal ==> Placed in /lib ==> Generated by che-websocket-terminal repo\ ``` ```text ws-agent.zip ==> Generated by assembly-wsagent-server -> tomcat ==> Placed in / ==> Downloaded from Che maven repo -> ide.war ==> Placed in /webapps ==> Generated by assembly-wsagent-war -> che-core-*.jar ==> Downloaded from Che maven repo -> che-plugins-*.jar ==> Downloaded from Che maven repo -> ws-agent specialized classes ==> Built by assembly-machine-war\ ``` Note that the `ide.war` web application generated for the workspace agent is not identical to the one generated for the Che application server, even though they have the same name. The workspace agent does not include many of the IDE libraries and adds in additional libraries for communicating to the Che server and running plug-ins within the workspace itself. # Che Repositories The `ide.war`, `ws-agent.zip`, and other assembly files depend upon a wide range of libraries. Many of these resources and libraries are stored in other Che repositories. These are the repositories that are stored at `http://github.com/eclipse` organization. Each repository is referenced by its first entry, ie: `http://github.com/eclipse/che` or `http://github.com/eclipse/che-dependencies`. ```shell /che /che/assembly # Generates binary assemblies of Che /che/assembly/assembly-main # Final packaging phase /che/assembly/assembly-ide-war # Creates the IDE.war from plug-ins & core /che/assembly/assembly-wsmaster-war /che/assembly/assembly-wsagent-war # Creates the agent WAR from plug-ins & core /che/assembly/assembly-wsagent-server # Creates the agent server that goes into ws /che/core # Platform APIs /che/dashboard # AngularJS app for managing Che /che/plugins # IDE & agent plug-ins /che/wsmaster # Libraries used by the Che server /che/wsagent # Libraries used by agents installed into workspaces /che-lib # Forked dependencies that require mods /che-lib/swagger /che-lib/terminal /che-lib/websocket /che-lib/pty /che-lib/che-tomcat8-slf4j-logback # All modules in /che and /che-lib depend upon /che-dependencies /che-dependencies # Maven dependencies used by che /che-dev # Code style and license header # /che-dependencies and /che-dev depends upon /che-parent /che-parent # Maven plugins and profiles \ ``` You can build individual directories of Che, or any of its sub-modules. These modules will generate JARs, WARs or other artifacts. The same happens if you build plug-ins of your own. These are artifacts are installed into a local maven repository that `/che/assembly` uses when creating a combined assembly. It is also possible for you to [copy the JAR files of plug-ins you author to an assembly staging area](https://eclipse-che.readme.io/docs/plug-ins#add-plug-in-by-copying-jar-file) instead of installing them into a nexus repository. If you build Che locally and if the necessary artifact dependencies are not locally installed into your maven repository, then Che will look in Codenvy's hosted nexus for packages. Codenvy maintains tagged versions of packages for the current SNAPSHOT and older versions. You can see the reference to Codenvy's repositories in the `che-dependencies` repository at the end of the `pom.xml`. ```xml codenvy-public-repo codenvy public https://maven.codenvycorp.com/content/groups/public/ codenvy-public-snapshots-repo codenvy public snapshots https://maven.codenvycorp.com/content/repositories/codenvy-public-snapshots/ \ ``` #### Installers Currently, the installers are generated from the `http://github.com/codenvy/che-installer` repository. This repository contains an Innosetup package for creating the Windows bundle and IZPack for creating a universal installer. # Codenvy Assemblies