seg_yinzy
/
che-server
mirror of https://github.com/eclipse-che/che-server.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
che-server/docs/_docs/write-che-ide-plugins/plugins-assemblies.md

13 KiB
Raw Blame History

tags title excerpt layout permalink
eclipse
che
Assemblies An assembly is a packaging of Che libraries and plug-ins distributable as a desktop IDE or workspace server. docs /: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.

/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.

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.

/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. Custom assemblies can be distributed as ZIP or TGZ packages.

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.

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.

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.

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\

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.

/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 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.

<repositories>
    <repository>
        <id>codenvy-public-repo</id>
        <name>codenvy public</name>
        <url>https://maven.codenvycorp.com/content/groups/public/</url>
    </repository>
    <repository>
        <id>codenvy-public-snapshots-repo</id>
        <name>codenvy public snapshots</name>
        <url>https://maven.codenvycorp.com/content/repositories/codenvy-public-snapshots/</url>
    </repository>
</repositories>\

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