Google Git
Sign in
eclipse/gerrit/www.eclipse.org/che/refs/heads/CheConf18/./docs/assemblies/assembly-lifecycle/index.html
blob: 1ebac6a21dc8b9238b0a04ffa3564bb8cdbbb217 [file]
<!-- jQuery Eclipse IP approval https://dev.eclipse.org/ipzilla/show_bug.cgi?id=10801 -->
<script type="text/javascript" charset="utf8" src="../../../docs/assets/scripts/jquery-1.8.1.min.js"></script>
<script type="text/javascript" charset="utf8">
$(document).ready(function(){
var images = document.getElementsByTagName('img');
for (var i = 0; i < images.length; i++) {
var image = images[i];
var parentElement = image.parentElement;
var a = document.createElement('a');
if (! image.getAttribute('src').includes("logo-codenvy.svg") && ! image.getAttribute('src').includes("codenvy-contribute.svg") ){
a.href = image.getAttribute('src');
a.target = "_blank";
a.appendChild(image);
parentElement.appendChild(a);
}
}
});
</script>
<!DOCTYPE HTML>
<html lang="en-US">
<head>
<title>Assembly Dev Lifecycle -
Docs
- Eclipse Che</title>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta name="generator" content="Jekyll v3.5.1">
<link rel="stylesheet" href="//fonts.googleapis.com/css?family=Lato:300,300italic,400,400italic,700,700italic,900">
<link rel="stylesheet" href="../../../docs/assets/css/screen.css">
<link rel="icon" type="image/x-icon" href="../../../docs/assets/imgs/favicon.ico">
<!--[if lt IE 9]>
<script src="/js/html5shiv.min.js"></script>
<script src="/js/respond.min.js"></script>
<![endif]-->
</head>
<body class="wrap">
<header>
<nav class="mobile-nav show-on-mobiles">
<ul>
<li class="current">
<a href="../../../docs/index.html">Docs</a>
</li>
<li class="">
<a href="../../../docs/tutorials/multi-machine/index.html">Tutorials</a>
</li>
<li class="">
<a href="../../../docs/openshift/config/index.html">OpenShift</a>
</li>
<li>
<a href="https://github.com/eclipse/che-docs/tree/master/src/main">GitHub</a>
</li>
</ul>
</nav>
<div class="grid">
<div class="unit one-third center-on-mobiles">
<a href="https://eclipse.org/che/">
<span class="sr-only">Eclipse Che</span>
<img src="../../../docs/assets/imgs/logo-eclipseche.svg" alt="Eclipse Che Logo" width="249" height="115">
</a>
</div>
<nav class="main-nav unit two-thirds hide-on-mobiles">
<ul>
<li class="current">
<a href="../../../docs/index.html">Docs</a>
</li>
<li class="">
<a href="../../../docs/tutorials/multi-machine/index.html">Tutorials</a>
</li>
<li class="">
<a href="../../../docs/openshift/config/index.html">OpenShift</a>
</li>
<li>
<a href="https://github.com/eclipse/che-docs/tree/master/src/main">GitHub</a>
</li>
</ul>
</nav>
</div>
</header>
<section class="docs">
<div class="grid">
<div class="docs-nav-mobile unit whole show-on-mobiles">
<select onchange="if (this.value) window.location.href=this.value">
<option value="">Navigate the docs…</option>
<optgroup label="SETUP">
<ul>
<option value="../../../docs/index.html">Introduction</option>
<option value="../../../docs/setup/getting-started/index.html">Getting Started&#58 Local</option>
<option value="../../../docs/setup/getting-started-saas-cloud/index.html">Getting Started&#58 SaaS Cloud</option>
<option value="../../../docs/setup/configuration/index.html">Configuration</option>
<option value="../../../docs/setup/managing/index.html">Managing</option>
<option value="../../../docs/setup/cli/index.html">CLI Reference</option>
<option value="../../../docs/setup/glossary/index.html">Glossary</option>
<option value="../../../docs/setup/docker/index.html">Docker Installation</option>
<option value="../../../docs/setup/openshift/index.html">OpenShift Installation</option>
<option value="../../../docs/setup/selenium/index.html">How to run selenium tests</option>
</ul>
<ul>
<li class=""><a href="../../../docs/index.html">Introduction</a></li>
<li class=""><a href="../../../docs/setup/getting-started/index.html">Getting Started&#58 Local</a></li>
<li class=""><a href="../../../docs/setup/getting-started-saas-cloud/index.html">Getting Started&#58 SaaS Cloud</a></li>
<li class=""><a href="../../../docs/setup/configuration/index.html">Configuration</a></li>
<li class=""><a href="../../../docs/setup/managing/index.html">Managing</a></li>
<li class=""><a href="../../../docs/setup/cli/index.html">CLI Reference</a></li>
<li class=""><a href="../../../docs/setup/glossary/index.html">Glossary</a></li>
<li class=""><a href="../../../docs/setup/docker/index.html">Docker Installation</a></li>
<li class=""><a href="../../../docs/setup/openshift/index.html">OpenShift Installation</a></li>
<li class=""><a href="../../../docs/setup/selenium/index.html">How to run selenium tests</a></li>
</ul>
</optgroup>
<optgroup label="WORKSPACE ADMINISTRATION">
<ul>
<option value="../../../docs/devops/intro/index.html">Introduction</option>
<option value="../../../docs/devops/runtime-stacks/index.html">Runtime Stacks</option>
<option value="../../../docs/devops/runtime-recipes/index.html">Runtime Recipes</option>
<option value="../../../docs/devops/project-samples/index.html">Project Samples</option>
<option value="../../../docs/devops/runtime-machines/index.html">Runtime Machines</option>
<option value="../../../docs/devops/volume-mounts/index.html">Volume Mounts</option>
<option value="../../../docs/devops/ws-agents/index.html">Workspace Agents</option>
<option value="../../../docs/devops/workspaces-data-model/index.html">Workspace Data Model</option>
<option value="../../../docs/devops/runtime-stacks-data-model/index.html">Runtime Stacks Data Model</option>
<option value="../../../docs/devops/project-samples-data-model/index.html">Project Samples Data Model</option>
</ul>
<ul>
<li class=""><a href="../../../docs/devops/intro/index.html">Introduction</a></li>
<li class=""><a href="../../../docs/devops/runtime-stacks/index.html">Runtime Stacks</a></li>
<li class=""><a href="../../../docs/devops/runtime-recipes/index.html">Runtime Recipes</a></li>
<li class=""><a href="../../../docs/devops/project-samples/index.html">Project Samples</a></li>
<li class=""><a href="../../../docs/devops/runtime-machines/index.html">Runtime Machines</a></li>
<li class=""><a href="../../../docs/devops/volume-mounts/index.html">Volume Mounts</a></li>
<li class=""><a href="../../../docs/devops/ws-agents/index.html">Workspace Agents</a></li>
<li class=""><a href="../../../docs/devops/workspaces-data-model/index.html">Workspace Data Model</a></li>
<li class=""><a href="../../../docs/devops/runtime-stacks-data-model/index.html">Runtime Stacks Data Model</a></li>
<li class=""><a href="../../../docs/devops/project-samples-data-model/index.html">Project Samples Data Model</a></li>
</ul>
</optgroup>
<optgroup label="USER GUIDE">
<ul>
<option value="../../../docs/ide/projects/index.html">Projects</option>
<option value="../../../docs/ide/import-a-project/index.html">Import</option>
<option value="../../../docs/ide/ssh/index.html">SSH</option>
<option value="../../../docs/ide/sync/index.html">Local IDE Sync</option>
<option value="../../../docs/ide/editor-settings/index.html">Editor</option>
<option value="../../../docs/ide/intellisense/index.html">Intellisense</option>
<option value="../../../docs/ide/commands/index.html">Commands</option>
<option value="../../../docs/ide/git-svn/index.html">Git and SVN</option>
<option value="../../../docs/ide/previews/index.html">Previews</option>
<option value="../../../docs/ide/build/index.html">Build</option>
<option value="../../../docs/ide/run/index.html">Run</option>
<option value="../../../docs/ide/sharing/index.html">Share</option>
<option value="../../../docs/ide/debug/index.html">Debug</option>
<option value="../../../docs/ide/docker/index.html">Docker</option>
<option value="../../../docs/ide/electron/index.html">Install Che Desktop Client</option>
</ul>
<ul>
<li class=""><a href="../../../docs/ide/projects/index.html">Projects</a></li>
<li class=""><a href="../../../docs/ide/import-a-project/index.html">Import</a></li>
<li class=""><a href="../../../docs/ide/ssh/index.html">SSH</a></li>
<li class=""><a href="../../../docs/ide/sync/index.html">Local IDE Sync</a></li>
<li class=""><a href="../../../docs/ide/editor-settings/index.html">Editor</a></li>
<li class=""><a href="../../../docs/ide/intellisense/index.html">Intellisense</a></li>
<li class=""><a href="../../../docs/ide/commands/index.html">Commands</a></li>
<li class=""><a href="../../../docs/ide/git-svn/index.html">Git and SVN</a></li>
<li class=""><a href="../../../docs/ide/previews/index.html">Previews</a></li>
<li class=""><a href="../../../docs/ide/build/index.html">Build</a></li>
<li class=""><a href="../../../docs/ide/run/index.html">Run</a></li>
<li class=""><a href="../../../docs/ide/sharing/index.html">Share</a></li>
<li class=""><a href="../../../docs/ide/debug/index.html">Debug</a></li>
<li class=""><a href="../../../docs/ide/docker/index.html">Docker</a></li>
<li class=""><a href="../../../docs/ide/electron/index.html">Install Che Desktop Client</a></li>
</ul>
</optgroup>
<optgroup label="PORTABLE WORKSPACES">
<ul>
<option value="../../../docs/chedir/getting-started/index.html">Chedir - Getting Started</option>
<option value="../../../docs/chedir/why/index.html">Chedir - Why Chedir?</option>
<option value="../../../docs/chedir/installation/index.html">Chedir - Installation</option>
<option value="../../../docs/chedir/project-setup/index.html">Chedir - Project Setup</option>
<option value="../../../docs/chedir/up-and-down/index.html">Chedir - Up and Down</option>
<option value="../../../docs/chedir/chefiles/index.html">Chedir - Chefile</option>
<option value="../../../docs/chedir/ssh/index.html">Chedir - SSH</option>
<option value="../../../docs/chedir/factories/index.html">Chedir - Factories</option>
<option value="">Error Generating Page Link. Contact Maintainer./docs/factory-getting-started/</option>
<option value="">Error Generating Page Link. Contact Maintainer./docs/factory-creating/</option>
<option value="">Error Generating Page Link. Contact Maintainer./docs/factory-json-reference/</option>
</ul>
<ul>
<li class=""><a href="../../../docs/chedir/getting-started/index.html">Chedir - Getting Started</a></li>
<li class=""><a href="../../../docs/chedir/why/index.html">Chedir - Why Chedir?</a></li>
<li class=""><a href="../../../docs/chedir/installation/index.html">Chedir - Installation</a></li>
<li class=""><a href="../../../docs/chedir/project-setup/index.html">Chedir - Project Setup</a></li>
<li class=""><a href="../../../docs/chedir/up-and-down/index.html">Chedir - Up and Down</a></li>
<li class=""><a href="../../../docs/chedir/chefiles/index.html">Chedir - Chefile</a></li>
<li class=""><a href="../../../docs/chedir/ssh/index.html">Chedir - SSH</a></li>
<li class=""><a href="../../../docs/chedir/factories/index.html">Chedir - Factories</a></li>
<li class=""><a href="../../../docs/factory/getting-started/index.html">Factory - Getting Started</a></li>
<li class=""><a href="../../../docs/factory/creating/index.html">Factory - Creating</a></li>
<li class=""><a href="../../../docs/factory/json-reference/index.html">Factory - JSON Reference</a></li>
</ul>
</optgroup>
<optgroup label="DEVELOPER GUIDE - REST API">
<ul>
<option value="../../../docs/assemblies/intro/index.html">Introduction</option>
<option value="../../../docs/assemblies/archetype/index.html">Archetype</option>
<option value="../../../docs/assemblies/assembly-lifecycle/index.html">Assembly Dev Lifecycle</option>
<option value="../../../docs/assemblies/plugin-lifecycle/index.html">Plugin Lifecycle</option>
<option value="../../../docs/assemblies/sdk-rest-apis/index.html">SDK REST APIs</option>
<option value="../../../docs/assemblies/sdk-class-reference/index.html">SDK Class Reference</option>
<option value="../../../docs/assemblies/sdk-dependency-injection/index.html">SDK Dependency Injection</option>
<option value="../../../docs/assemblies/sdk-dto/index.html">SDK DTOs</option>
<option value="../../../docs/assemblies/sdk-properties/index.html">SDK Properties</option>
<option value="../../../docs/assemblies/sdk-code-editors/index.html">SDK Editors</option>
<option value="../../../docs/assemblies/sdk-embed-htmljs/index.html">SDK Embedded JavaScript</option>
<option value="../../../docs/assemblies/sdk-project-types/index.html">SDK Project Types</option>
<option value="../../../docs/assemblies/sdk-actions/index.html">SDK Actions</option>
<option value="../../../docs/assemblies/sdk-services/index.html">SDK Services</option>
<option value="../../../docs/assemblies/sdk-parts/index.html">SDK Parts</option>
<option value="../../../docs/assemblies/sdk-themes/index.html">SDK Themes</option>
<option value="../../../docs/assemblies/sdk-custom-agents/index.html">SDK Custom Agents</option>
<option value="../../../docs/assemblies/sdk-language-server-protocol/index.html">SDK Language Server Protocol</option>
<option value="../../../docs/assemblies/sdk-workspace/index.html">SDK Workspace</option>
</ul>
<ul>
<li class=""><a href="../../../docs/assemblies/intro/index.html">Introduction</a></li>
<li class=""><a href="../../../docs/assemblies/archetype/index.html">Archetype</a></li>
<li class="current"><a href="../../../docs/assemblies/assembly-lifecycle/index.html">Assembly Dev Lifecycle</a></li>
<li class=""><a href="../../../docs/assemblies/plugin-lifecycle/index.html">Plugin Lifecycle</a></li>
<li class=""><a href="../../../docs/assemblies/sdk-rest-apis/index.html">SDK REST APIs</a></li>
<li class=""><a href="../../../docs/assemblies/sdk-class-reference/index.html">SDK Class Reference</a></li>
<li class=""><a href="../../../docs/assemblies/sdk-dependency-injection/index.html">SDK Dependency Injection</a></li>
<li class=""><a href="../../../docs/assemblies/sdk-dto/index.html">SDK DTOs</a></li>
<li class=""><a href="../../../docs/assemblies/sdk-properties/index.html">SDK Properties</a></li>
<li class=""><a href="../../../docs/assemblies/sdk-code-editors/index.html">SDK Editors</a></li>
<li class=""><a href="../../../docs/assemblies/sdk-embed-htmljs/index.html">SDK Embedded JavaScript</a></li>
<li class=""><a href="../../../docs/assemblies/sdk-project-types/index.html">SDK Project Types</a></li>
<li class=""><a href="../../../docs/assemblies/sdk-actions/index.html">SDK Actions</a></li>
<li class=""><a href="../../../docs/assemblies/sdk-services/index.html">SDK Services</a></li>
<li class=""><a href="../../../docs/assemblies/sdk-parts/index.html">SDK Parts</a></li>
<li class=""><a href="../../../docs/assemblies/sdk-themes/index.html">SDK Themes</a></li>
<li class=""><a href="../../../docs/assemblies/sdk-custom-agents/index.html">SDK Custom Agents</a></li>
<li class=""><a href="../../../docs/assemblies/sdk-language-server-protocol/index.html">SDK Language Server Protocol</a></li>
<li class=""><a href="../../../docs/assemblies/sdk-workspace/index.html">SDK Workspace</a></li>
</ul>
</optgroup>
</select>
</div>
<div class="unit four-fifths">
<article>
<div class="improve right hide-on-mobiles">
<a href="https://github.com/codenvy/che-docs/blob/master/src/main/_docs/assemblies/assemblies-assembly-lifecycle.md"><i class="fa fa-pencil"></i> &nbsp;Improve this page</a>
<!--<a href="https://github.com/eclipse/che/blob/master/docs/_docs/assemblies/assemblies-assembly-lifecycle.md"><i class="fa fa-pencil"></i> &nbsp;Improve this page</a>-->
</div>
<div class="doc-title">
<h1>Assembly Dev Lifecycle</h1>
<div class="doc-title-border">
</div>
</div>
<p>You can create new Che products for re-distribution by generating a custom assembly. An assembly is a binary packaging of IDE extensions (written in Java / JavaScript), Che extensions (deployed in the Che server), workspace extensions (deployed in a workspace agent), custom agents, stacks, templates, custom CLI, and brand elements. When these are packaged together, a complete binary that can be run identically to how you run the standard Che assembly is provided.</p>
<p>Everything can be customized allowing you to create any new kind of cloud IDE or workspace server.</p>
<h1 id="development-lifecycle">Development Lifecycle</h1>
<p>Custom assemblies are git projects that are generated in the same structure of Che itself. Your custom assembly will inherit its libraries from Che and allow you locations to override default behaviors with your own.</p>
<p>The assembly development lifecycle:</p>
<ol>
<li>Generate - We provide an <code class="highlighter-rouge">archetype</code> utility to generate new custom assemblies that already contain basic customizations.</li>
<li>Build - Use the <code class="highlighter-rouge">archetype</code> utility or <code class="highlighter-rouge">mvn clean install</code> to package the custom assembly for execution.</li>
<li>Run - The custom assembly is executed with the standard CLI by mounting it to <code class="highlighter-rouge">:/assembly</code>. The new binaries will be used instead of those that are distributed within the standard <code class="highlighter-rouge">eclipse/che-server</code> Docker image.</li>
<li>Customize - Add different types of custom extensions, agents, stacks, templates, and brand elements.</li>
<li>Debug - Debug your customizations for browser, Che, and workspace extensions running within a custom assembly.</li>
</ol>
<h1 id="archetype">Archetype</h1>
<p>The CLI has an <code class="highlighter-rouge">archetype</code> command that can be used to generate custom assemblies of Eclipse Che and Codenvy.</p>
<p>An archetype is a maven technique for generating code templates. A single archetype has an ID and generates a complete custom assembly. Different archetypes generate assemblies with different types of customizations. We make each archetype customize the minimal number of features to make learning about customizations simpler.</p>
<p>Your host system must have Maven 3.3+ installed to facilitate generation and compiling of custom assemblies. You must pass in your Maven’s M2 repository path on your host. Our archetype generator will download libraries into that repository making repeated compilations faster over time. On most Linux based systems, your M2 repository is located at <code class="highlighter-rouge">/home/user/.m2/repository</code> and it is <code class="highlighter-rouge">%USERPROFILE%/.m2/repository</code> for Windows. We default your M2 repository to <code class="highlighter-rouge">/home/user/.m2/repository</code>. Use the <code class="highlighter-rouge">/m2</code> mount to change this.</p>
<p>The syntax is:</p>
<div class="language-shell highlighter-rouge"><pre class="highlight"><code>USAGE: DOCKER_PARAMS eclipse/che-cli:nightly archetype ACTION <span class="o">[</span>PARAMETERS]
Use an archetype to generate, build or run a custom che assembly
MANDATORY DOCKER PARAMETERS:
-v &lt;path&gt;:/archetype Local path where your custom assembly will be generated
OPTIONAL DOCKER PARAMETERS:
-v &lt;path&gt;:/m2 Local path to your hosts Maven M2 repository
ACTION:
all Generate, build and run a new custom assembly
generate Generate a new custom assembly to folder mounted to <span class="s1">'/archetype'</span>
build Uses <span class="s1">'eclipse/che-dev'</span> image to compile archetype <span class="k">in</span> <span class="s1">'/archetype'</span>
run Starts che from custom assembly <span class="k">in</span> <span class="s1">'/archetype'</span>
PARAMETERS:
--archid<span class="o">=</span>&lt;id&gt; Different archetypes generate different types of customizations
--archversion<span class="o">=</span>&lt;version&gt; Sets archetype version - default <span class="o">=</span> tag of CLI image
--version<span class="o">=</span>&lt;version&gt; Sets custom assembly version - default <span class="o">=</span> archetype version
--group<span class="o">=</span>&lt;group&gt; Sets groupId of generated assembly - default <span class="o">=</span> com.sample
--id<span class="o">=</span>&lt;id&gt; Sets artifactId of generated assembly - default <span class="o">=</span> ID of archetype
--no:interactive Disables interactive mode
</code></pre>
</div>
<h1 id="generate">Generate</h1>
<p>The <code class="highlighter-rouge">generate</code> action will generate a new Maven multi-module project into the folder you mount to <code class="highlighter-rouge">/archetype</code>. Explaining the nature of the command is best served with an example. For example, on a Windows machine run:</p>
<div class="highlighter-rouge"><pre class="highlight"><code>docker run -it --rm
-v /var/run/docker.sock:/var/run/docker.sock
-v /c/archetype:/archetype
-v /c/tmp:/data
-v /c/Users/Tyler/.m2/repository:/m2
eclipse/che-cli:5.14.0
archetype generate
</code></pre>
</div>
<p>This will provide an interactive experience, downloading some utility images and giving you a list of archetypes to choose from. It will generate a new custom assembly from a template. It is essential that you have Maven installed locally on your host and that you mount your Maven’s repository to <code class="highlighter-rouge">/m2</code>. This will allow the archetype Docker command to download various libraries and cache them into your local repository (to be used in the build phase).</p>
<p>You can skip interactive mode along with generate, build and run the new assembly in a single command:</p>
<div class="highlighter-rouge"><pre class="highlight"><code>docker run -it --rm
-v /var/run/docker.sock:/var/run/docker.sock
-v /c/archetype:/archetype
-v /c/tmp:/data
-v /c/Users/Tyler/.m2/repository:/m2
eclipse/che-cli:5.14.0
archetype all --no:interactive
</code></pre>
</div>
<p>This command:</p>
<h4 id="linux">Linux</h4>
<p>On Linux, the Maven utility launched by the CLI may have problems writing files to your host system during the generation phase. To overcome this limitation create the host mount directories before launching docker, and in the <code class="highlighter-rouge">docker run ...</code> syntax before the image name add <code class="highlighter-rouge">--user={uid}</code> where UID is the user identity of your current users. This user identity will be passed into the various CLI utilities to execute under that user identity.</p>
<p>Example</p>
<div class="highlighter-rouge"><pre class="highlight"><code> -v /etc/group:/etc/group:ro \
-v /etc/passwd:/etc/passwd:ro \
--user=1000:100 \
--group-add 999 \
</code></pre>
</div>
<p>Therefore a full set of commands may look like this to do an interactive generate:</p>
<div class="highlighter-rouge"><pre class="highlight"><code>mkdir /tmp/archetype
mkdir /tmp/data
docker run -it --rm \
-v /var/run/docker.sock:/var/run/docker.sock \
-v /tmp/archetype:/archetype \
-v /tmp/data:/data \
-v ~/.m2/repository:/m2 \
-v /etc/group:/etc/group:ro \
-v /etc/passwd:/etc/passwd:ro \
--user=1000:1000 \
--group-add 999 \
eclipse/che-cli:5.14.0 \
archetype generate
</code></pre>
</div>
<p>To determine which user and group to use in the command type <code class="highlighter-rouge">id</code> in a bash shell - you’ll get output similar to the following:</p>
<div class="highlighter-rouge"><pre class="highlight"><code>uid=1000(florent) gid=100(users) groups=100(users),24(cdrom),25(floppy),29(audio),30(dip),44(video),46(plugdev),108(netdev),999(docker)
</code></pre>
</div>
<p>For <code class="highlighter-rouge">--user</code> you need the ID of your user (1000 in the example above) and their group (100). For <code class="highlighter-rouge">--group-add</code> you need the ID of the group associated with <code class="highlighter-rouge">docker</code> (999).</p>
<h4 id="archetypes-list">Archetypes List</h4>
<p>We provide different archetypes that will generate custom assemblies with different types of customizations. You can see the list of available archetypes by running the <code class="highlighter-rouge">archetype</code> command without <code class="highlighter-rouge">--no:interactive</code>. You will be prompted to choose from a list. These archetypes are provided as small sets of customization to simplify the learning experience for new developers with Che. For each of the archetypes that we provide, we also have a short section discussing the relevant elements modified to make the assembly work.</p>
<p>Each archetype has a unique artifactId, which you can specify on the command line with <code class="highlighter-rouge">--archid</code>. We also generate new versions of each archetype during each release of Che. You can choose a specific version of the archetype with the <code class="highlighter-rouge">--archversion</code> parameter.</p>
<p>The generator and templates for each assembly is in an <a href="https://github.com/eclipse/che-archetypes/blob/master/README.md">assembly generator repository</a>.</p>
<table>
<thead>
<tr>
<th>Archetype ID</th>
<th>Assembly Contents</th>
</tr>
</thead>
<tbody>
<tr>
<td><code class="highlighter-rouge">agent-archetype</code></td>
<td>Sample custom agent</td>
</tr>
<tr>
<td><code class="highlighter-rouge">plugin-menu-archetype</code></td>
<td>IDE extension to customize the menu</td>
</tr>
<tr>
<td><code class="highlighter-rouge">plugin-wizard-archetype</code></td>
<td>Custom C project type extension</td>
</tr>
<tr>
<td><code class="highlighter-rouge">plugin-serverservice-archetype</code></td>
<td>Simple IDE extension and a workspace service</td>
</tr>
<tr>
<td><code class="highlighter-rouge">plugin-embedjs-archetype</code></td>
<td>IDE extension with JavaScript in widgets</td>
</tr>
<tr>
<td><code class="highlighter-rouge">plugin-json-archetype</code></td>
<td>JSON project type, codeassistant, and workspace service</td>
</tr>
<tr>
<td><code class="highlighter-rouge">stacks-archetype</code></td>
<td>An assembly with a custom stacks module</td>
</tr>
</tbody>
</table>
<h4 id="overrides">Overrides</h4>
<p>The custom assembly is generated as a Maven multi-module project. Maven scaffolds and expects a particular folder structure that separates source code, resources (like images), and test code into different folders. Maven uses a three-variable combination of artifactId, groupId, and version to uniquely identify a project. When we generate your custom assembly, default values for each of these are provided. You can override them on the command line with <code class="highlighter-rouge">--id</code>, <code class="highlighter-rouge">--group</code>, and <code class="highlighter-rouge">--version</code>.</p>
<h1 id="build">Build</h1>
<p>You can build the assembly into a package using the Che CLI or with native maven utilities. The CLI is generally slower because file operations are performed over file mounts, however using native maven utilities requires your host system to be configured with a variety of additional libraries depending upon the modules you wish to build.</p>
<p>Given the example we started above, you compile it with:</p>
<div class="highlighter-rouge"><pre class="highlight"><code>docker run -it --rm
-v /var/run/docker.sock:/var/run/docker.sock
-v /c/archetype:/archetype
-v /c/tmp:/data
-v /c/Users/Tyler/.m2/repository:/m2
eclipse/che-cli:5.14.0
archetype build
</code></pre>
</div>
<h4 id="cli">CLI</h4>
<p>If you use the CLI to compile the custom assembly, we use a Docker image named <code class="highlighter-rouge">eclipse/che-dev</code> to perform the build. It contains the utilities required to build a Che assembly and every sub-module. Each module, such as agents, dashboard, and IDE, have different dependencies, compilers, and unit test utilities. This image makes getting started really easy, but it’s a monster, weighing in at &gt;1GB!</p>
<p>With the CLI, run <code class="highlighter-rouge">archetype build</code> with the location of your already-generated assembly mounted to <code class="highlighter-rouge">/archetype</code>. If you use the <code class="highlighter-rouge">all</code> command, a build step will be invoked automatically by the CLI. The <code class="highlighter-rouge">archetype</code> action will configure a container from <code class="highlighter-rouge">eclipse/che-dev</code> and give it a <code class="highlighter-rouge">mvn clean install</code> command for the assembly.</p>
<p>You can bypass the CLI and use <code class="highlighter-rouge">eclipse/che-dev</code> directly. We maintain an explanation of the syntax for this image in the repository where this image’s Dockerfile is located. https://github.com/eclipse/che/blob/master/dockerfiles/dev/Dockerfile.</p>
<p>For example, given the sample we started with, the <code class="highlighter-rouge">eclipse/che-dev</code> equivalent would be:</p>
<div class="highlighter-rouge"><pre class="highlight"><code>docker run -it --rm --name build-che \
-v /var/run/docker.sock:/var/run/docker.sock \
-v /c/Users/Tyler/.m2/repository:/home/user/.m2/repository \
-v /c/archetype/assembly:/home/user/che-build \
-w /home/user/che-build \
eclipse/che-dev mvn clean install
</code></pre>
</div>
<p>If this were a Linux system, there would be additional volume mounts required and you must set the user identity with <code class="highlighter-rouge">--user</code>.</p>
<p>Example:</p>
<div class="highlighter-rouge"><pre class="highlight"><code>docker run -it --rm \
-v /var/run/docker.sock:/var/run/docker.sock \
-v /tmp/archetype:/archetype \
-v /tmp/data:/data \
-v ~/:/home/$USER/ \
-v /etc/group:/etc/group:ro \
-v /etc/passwd:/etc/passwd:ro \
--user=1000:1000 \
--group-add 999 \
-w /archetype/assembly \
eclipse/che-dev \
mvn clean install
</code></pre>
</div>
<p>To determine which user and group to use in the command type <code class="highlighter-rouge">id</code> in a bash shell - you’ll get output similar to the following:</p>
<div class="highlighter-rouge"><pre class="highlight"><code>uid=1000(florent) gid=100(users) groups=100(users),24(cdrom),25(floppy),29(audio),30(dip),44(video),46(plugdev),108(netdev),999(docker)
</code></pre>
</div>
<p>For <code class="highlighter-rouge">--user</code> you need the ID of your user (1000 in the example above) and their group (100). For <code class="highlighter-rouge">--group-add</code> you need the ID of the group associated with <code class="highlighter-rouge">docker</code> (999).</p>
<p>The full syntax for this Docker image is <a href="https://github.com/eclipse/che/blob/master/dockerfiles/dev/Dockerfile">within the Che repository</a>.</p>
<h4 id="native">Native</h4>
<p>While the Docker approach to compiling an assembly is simple, it is slower. You can perform a native build with <code class="highlighter-rouge">mvn clean install</code> in the root of the assembly (the folder with the <code class="highlighter-rouge">pom.xml</code>) or any module that is a sub-folder within the assembly. If you have the right utilities installed, Maven will go about downloading necessary dependencies, perform compilation, execute unit tests, and give you a custom assembly. The custom assembly is placed into the <code class="highlighter-rouge">/target</code> sub-folder of the assembly that is built.</p>
<p>Compiling an assembly requires other tools like Java, Angular, Go to be installed on your host system. Each module of the assembly requires different dependencies. You can view the README.md in Che’s source repository for the requirements to build that module. We also discuss many of the requirements and techniques for improving build performance <a href="https://github.com/eclipse/che/wiki/Development-Workflow">in the Che wiki</a> where the internal development workflow is discussed.</p>
<h1 id="run">Run</h1>
<p>A custom assembly is packaged into a set of binaries that can be used with the Che Docker image to launch Che servers. The finalized build is located in <code class="highlighter-rouge">assembly/assembly-main/target</code>.</p>
<p>You can run this custom assembly either by using the <code class="highlighter-rouge">archetype</code> command or with the Che CLI. The <code class="highlighter-rouge">archetype run</code> action will use your assembly details and launch the Che CLI automatically with the proper location of the custom assembly. Given the example we have started, this would look like (note that mounting the M2 repository is not required as we are not building with Maven):</p>
<div class="highlighter-rouge"><pre class="highlight"><code>docker run -it --rm
-v /var/run/docker.sock:/var/run/docker.sock
-v /c/archetype:/archetype
-v /c/tmp:/data
eclipse/che-cli:5.14.0
archetype run
</code></pre>
</div>
<p>On Linux:</p>
<div class="highlighter-rouge"><pre class="highlight"><code>docker run -it --rm \
-v /var/run/docker.sock:/var/run/docker.sock \
-v /tmp/archetype:/archetype \
-v /tmp/data:/data \
-v /etc/group:/etc/group:ro \
-v /etc/passwd:/etc/passwd:ro \
--user=1000:1000 \
--group-add 999 \
eclipse/che-cli:5.14.0 \
archetype run
</code></pre>
</div>
<p>Optionally, you can use the Che CLI to run a custom assembly by mounting <code class="highlighter-rouge">/assembly</code> to the exploded location of the assembly that has already been built. While developing Che and Codenvy itself, our engineers keep a branch open, work on customizations, and then build those customizations into an assembly that they mount with the CLI.</p>
<p>The exploded assembly is usually something like <code class="highlighter-rouge">assembly/assembly-main/target/eclipse-che-&lt;version&gt;/eclipse-che-&lt;version&gt;/</code>. You can use the rest of the CLI’s options and parameters as you normally would. For example, given the sample we started with, the CLI direct launch equivalent would be:</p>
<div class="highlighter-rouge"><pre class="highlight"><code>docker run -it --rm --name run-che \
-v /var/run/docker.sock:/var/run/docker.sock \
-v /c/tmp:/data \
-v /c/archetype/assembly/assembly-main/target/eclipse-che-5.14.0/eclipse-che-5.14.0:/assembly \
eclipse/che:5.14.0 start --skip:nightly
</code></pre>
</div>
<p>On Linux:</p>
<div class="highlighter-rouge"><pre class="highlight"><code>docker run -it --rm --name run-che \
-v /var/run/docker.sock:/var/run/docker.sock \
-v /tmp/data:/data \
-v /tmp/archetype/assembly/assembly-main/target/eclipse-che-5.14.0/eclipse-che-5.14.0:/assembly \
eclipse/che:5.14.0 start --skip:nightly
</code></pre>
</div>
<h1 id="stop">Stop</h1>
<p>You can stop a custom assembly with the CLI’s <code class="highlighter-rouge">stop</code> command or with <code class="highlighter-rouge">archetype stop</code>:</p>
<div class="highlighter-rouge"><pre class="highlight"><code>docker run -it --rm
-v /var/run/docker.sock:/var/run/docker.sock
-v /c/archetype:/archetype
-v /c/tmp:/data
eclipse/che-cli:5.14.0
archetype stop
</code></pre>
</div>
<p>On Linux:</p>
<div class="highlighter-rouge"><pre class="highlight"><code>docker run -it --rm \
-v /var/run/docker.sock:/var/run/docker.sock \
-v /tmp/archetype:/archetype \
-v /tmp/data:/data \
-v /etc/group:/etc/group:ro \
-v /etc/passwd:/etc/passwd:ro \
--user=1000:1000 \
--group-add 999 \
eclipse/che-cli:5.14.0 \
archetype stop
</code></pre>
</div>
<h1 id="che-vs-codenvy">Che vs. Codenvy</h1>
<p>The <code class="highlighter-rouge">archetype generate</code> command will generate two custom assemblies: one for Eclipse Che and one for Codenvy, which is an enterprise adaptation of Che that adds multi-node scalability, a user database, and security controls. Eclipse Che extensions are deployable within a Codenvy custom assembly. There are some elements of configuration that are slightly different between the assemblies, so we provide both to provide comparison between the various packages.</p>
<p>The Eclipse Che and Codenvy CLI have (mostly) identical syntax, so you can build and run either custom assembly. By default, the <code class="highlighter-rouge">archetype build</code> and <code class="highlighter-rouge">archetype run</code> commands default to the Che custom assembly. You can switch to the Codenvy assembly by appending <code class="highlighter-rouge">--codenvy</code> to either command.</p>
<h1 id="customizing">Customizing</h1>
<p>Our archetypes generate a functional custom assembly with some pre-built customizations. You can further customize an assembly by:</p>
<ul>
<li>Excluding plugins or assets from Che / Codenvy</li>
<li>Including new plugins or assets that you have created</li>
<li>Both</li>
</ul>
<p>For example, if you want to replace Che’s git plugin with an improvement that you make, you would both exclude the default one provided by Che and then include a new plugin that you author.</p>
<p>After you exclude / include new plugins, perform another build to package the assembly with the updated plugin list.</p>
<h4 id="standard-assemblies">Standard Assemblies</h4>
<p>There are five different places where you can include or exclude a plugin, which are items we call “standard assemblies”. The “standard assemblies” generate packages that will be run as an asset in a different location. Che and Codenvy are distributed systems, so there are components that run in a browser, on the server, and within a workspace. Each one of these components are independently packaged into a “standard assembly”.</p>
<table>
<thead>
<tr>
<th>Che Assembly Location</th>
<th>What Is Included</th>
</tr>
</thead>
<tbody>
<tr>
<td><code class="highlighter-rouge">/assembly-che/assembly-ide-war</code></td>
<td>GWT plugins that will be compiled into a new browser IDE as JavaScript</td>
</tr>
<tr>
<td><code class="highlighter-rouge">/assembly-che/wsagent-war</code></td>
<td>Java plugins that will run within a workspace’s agent</td>
</tr>
<tr>
<td><code class="highlighter-rouge">/assembly-che/wsagent-server</code></td>
<td>Packages workspace agents into a Tomcat bundle</td>
</tr>
<tr>
<td><code class="highlighter-rouge">/assembly-che/wsmaster-war</code></td>
<td>Java plugins that will run within Che’s core server</td>
</tr>
<tr>
<td><code class="highlighter-rouge">/assembly-che/assembly-main</code></td>
<td>Packages Che’s core server into a Tomcat bundle</td>
</tr>
</tbody>
</table>
<p>And Codenvy’s assemblies are slightly different:</p>
<table>
<thead>
<tr>
<th>Codenvy Assembly Location</th>
<th>What Is Included</th>
</tr>
</thead>
<tbody>
<tr>
<td><code class="highlighter-rouge">/assembly-codenvy/compiling-ide-war</code></td>
<td>GWT plugins that will be compiled into a new browser IDE as JavaScript</td>
</tr>
<tr>
<td><code class="highlighter-rouge">/assembly-codenvy/assembly-ide-war</code></td>
<td>Results of GWT plugins packaged into a new web app</td>
</tr>
<tr>
<td><code class="highlighter-rouge">/assembly-codenvy/assembly-dashboard-war</code></td>
<td>JavaScript plugins that will be packaged into the user dashboard</td>
</tr>
<tr>
<td><code class="highlighter-rouge">/assembly-codenvy/assembly-factory-war</code></td>
<td>Plugins for workspace automation with factories</td>
</tr>
<tr>
<td><code class="highlighter-rouge">/assembly-codenvy/wsagent-war</code></td>
<td>Java plugins that will run within a workspace’s agent</td>
</tr>
<tr>
<td><code class="highlighter-rouge">/assembly-codenvy/wsagent-server</code></td>
<td>Packages workspace agents into a Tomcat bundle</td>
</tr>
<tr>
<td><code class="highlighter-rouge">/assembly-codenvy/wsmaster-war</code></td>
<td>Java plugins that will run within Che’s core server</td>
</tr>
<tr>
<td><code class="highlighter-rouge">/assembly-codenvy/assembly-main</code></td>
<td>Packages Che’s core server into a Tomcat bundle</td>
</tr>
</tbody>
</table>
<h4 id="exclude">Exclude</h4>
<p>You can exclude existing Che or Codenvy plugins from your custom assembly.</p>
<p>In the appropriate assembly where you want to remove a plugin, such as <code class="highlighter-rouge">assembly-che/assembly-ide-war/pom.xml</code>, add an <code class="highlighter-rouge">&lt;exclusions&gt;</code> code block to the maven definition. You can provide an exclusion for each plugin provided by Che individually:</p>
<div class="highlighter-rouge"><pre class="highlight"><code>&lt;dependency&gt;
&lt;groupId&gt;org.eclipse.che&lt;/groupId&gt;
&lt;artifactId&gt;assembly-ide-war&lt;/artifactId&gt;
&lt;classifier&gt;classes&lt;/classifier&gt;
&lt;exclusions&gt;
&lt;exclusion&gt;
&lt;groupId&gt;org.eclipse.che.plugin&lt;/groupId&gt;
&lt;artifactId&gt;PLUGIN-IDENTIFIER&lt;/artifactId&gt;
&lt;/exclusion&gt;
&lt;/exclusions&gt;
&lt;/dependency&gt;
</code></pre>
</div>
<p>You can do a similar activity for the Codenvy custom assembly as well located in <code class="highlighter-rouge">assembly-codenvy/assembly-ide-war/pom.xml</code>:</p>
<div class="highlighter-rouge"><pre class="highlight"><code>&lt;dependency&gt;
&lt;groupId&gt;com.codenvy.onpremises&lt;/groupId&gt;
&lt;artifactId&gt;compiling-ide-war&lt;/artifactId&gt;
&lt;classifier&gt;classes&lt;/classifier&gt;
&lt;exclusions&gt;
&lt;exclusion&gt;
&lt;groupId&gt;com.codenvy.plugin&lt;/groupId&gt;
&lt;artifactId&gt;PLUGIN-IDENTIFIER&lt;/artifactId&gt;
&lt;/exclusion&gt;
&lt;/exclusions&gt;
&lt;/dependency&gt;
</code></pre>
</div>
<p>The <code class="highlighter-rouge">PLUGIN-IDENTIFIER</code> is the <code class="highlighter-rouge">artifactId</code> that is provided by the plugin. You can find this identifier in the <code class="highlighter-rouge">pom.xml</code> that is in the root folder for each plugin in Che and Codenvy’s source repository.</p>
<p>You can have as many <code class="highlighter-rouge">&lt;exclusion&gt;</code> blocks as necessary within a single <code class="highlighter-rouge">&lt;exclusions&gt;</code> tag.</p>
<p>We require the maven POM to be sorted. If you get a sorting error, you can sort your modifications on the command line with <code class="highlighter-rouge">mvn sortpom:sort</code>.</p>
<h4 id="include">Include</h4>
<p>You include your plugin by modifying the same assembly <code class="highlighter-rouge">pom.xml</code> and add a new <code class="highlighter-rouge">&lt;dependency&gt;</code> block:</p>
<div class="highlighter-rouge"><pre class="highlight"><code>&lt;dependency&gt;
&lt;groupId&gt;YOUR-PLUGIN-GROUP-IDENTIFIER&lt;/groupId&gt;
&lt;artifactId&gt;YOUR-PLUGIN-IDENTIFIER&lt;/artifactId&gt;
&lt;/dependency&gt;
</code></pre>
</div>
<p>We require the maven POM to be sorted. If you get a sorting error, you can sort your modifications on the command line with <code class="highlighter-rouge">mvn sortpom:sort</code>.</p>
<h1 id="ide">IDE</h1>
<p>You can use your own IDE for developing plugins that are deployed within Che. We use Eclipse, Che and IntelliJ internally to create Che itself. You can <a href="https://github.com/eclipse/che/wiki/Development-Workflow#ide-setup">create a similar development environment and workflow</a> for customizations that you make.</p>
<h1 id="debugging">Debugging</h1>
<p>It’s a custom assembly, so this means you are either changing our custom plugins or adding your own as new code. Most customizations are either an IDE extension, a server extension, or a workspace extension. You can set up a debugger for tracking your code in each of these different extensions:</p>
<ol>
<li><a href="https://github.com/eclipse/che/wiki/Development-Workflow#debugging-che-ide-extensions">Debug IDE extensions</a></li>
<li><a href="https://github.com/eclipse/che/wiki/Development-Workflow#debugging-che-server">Debug Che extensions</a></li>
<li><a href="https://github.com/eclipse/che/wiki/Development-Workflow#debugging-workspace-agent">Debug workspace and agent extensions</a></li>
</ol>
<h1 id="versioning">Versioning</h1>
<p>Your custom assembly inherits from a base platform from Eclipse Che or Codenvy. When you first generate a custom assembly, you select the version of Che / Codenvy that you have as a base platform. You can have your customer assembly use a new version by modifying two files and then rebuilding the assembly.</p>
<ol>
<li>In your assembly’s primary <code class="highlighter-rouge">pom.xml</code>, change the version in the <code class="highlighter-rouge">&lt;parent&gt;</code> tag to the new version of Che or Codenvy you want to use as a base.</li>
</ol>
<div class="language-xml highlighter-rouge"><pre class="highlight"><code><span class="nt">&lt;parent&gt;</span>
<span class="nt">&lt;artifactId&gt;</span>maven-depmgt-pom<span class="nt">&lt;/artifactId&gt;</span>
<span class="nt">&lt;groupId&gt;</span>org.eclipse.che.depmgt<span class="nt">&lt;/groupId&gt;</span>
<span class="nt">&lt;version&gt;</span>5.5.0-SNAPSHOT<span class="nt">&lt;/version&gt;</span>
<span class="nt">&lt;/parent&gt;</span>
</code></pre>
</div>
<ol>
<li>In the same file, update the properties fields with the new version.</li>
</ol>
<div class="language-xml highlighter-rouge"><pre class="highlight"><code><span class="nt">&lt;properties&gt;</span>
<span class="nt">&lt;che.version&gt;</span>5.5.0-SNAPSHOT<span class="nt">&lt;/che.version&gt;</span>
<span class="nt">&lt;codenvy.version&gt;</span>5.5.0-SNAPSHOT<span class="nt">&lt;/codenvy.version&gt;</span>
<span class="nt">&lt;/properties&gt;</span>
</code></pre>
</div>
<p>You can then rebuild your assembly normally. The parent reference will trigger Maven to download the new dependency libraries that relate to that particular version.</p>
<h1 id="creating-assemblies">Creating Assemblies</h1>
<p>There are two ways to build an assembly</p>
<ol>
<li>As a minimal framework into which you can add plugins.</li>
<li>As a standard assembly with all included default plugins.</li>
</ol>
<p>There are two maven modules that you will need to consider:</p>
<ul>
<li><code class="highlighter-rouge">che-ide-core</code>: The core components of the IDE.</li>
<li><code class="highlighter-rouge">che-wsagent-core</code>: The core components of the server-side workspace agent.</li>
</ul>
<p>These two modules will be used to create either a standard assembly or a sample.</p>
<h2 id="standard-ide-assembly">Standard IDE Assembly</h2>
<p>To make a standard assembly of the IDE, we need to declare it in <code class="highlighter-rouge">assembly/assembly-ide-war/pom.xml</code>.</p>
<p><strong>1) Standard IDE core only</strong></p>
<div class="highlighter-rouge"><pre class="highlight"><code> &lt;dependency&gt;
&lt;groupId&gt;org.eclipse.che.core&lt;/groupId&gt;
&lt;artifactId&gt;che-ide-core&lt;/artifactId&gt;
&lt;/dependency&gt;
</code></pre>
</div>
<p><strong>2) Standard IDE core plus all Che IDE plugins</strong></p>
<div class="highlighter-rouge"><pre class="highlight"><code> &lt;dependency&gt;
&lt;groupId&gt;org.eclipse.che.plugin&lt;/groupId&gt;
&lt;artifactId&gt;*&lt;/artifactId&gt;
&lt;/dependency&gt;
</code></pre>
</div>
<h2 id="minimal-ide-assembly">Minimal IDE Assembly</h2>
<p>To make a minimal assembly of the IDE, we need to declare it in <code class="highlighter-rouge">assembly/assembly-ide-war/pom.xml</code>.</p>
<p><strong>1) Minimal IDE core only</strong></p>
<div class="highlighter-rouge"><pre class="highlight"><code> &lt;dependency&gt;
&lt;groupId&gt;org.eclipse.che.core&lt;/groupId&gt;
&lt;artifactId&gt;che-ide-core&lt;/artifactId&gt;
&lt;/dependency&gt;
</code></pre>
</div>
<p><strong>2) Minimal IDE core plus all Che IDE plugins</strong></p>
<div class="highlighter-rouge"><pre class="highlight"><code> &lt;dependency&gt;
&lt;groupId&gt;my.plugin&lt;/groupId&gt;
&lt;artifactId&gt;plugin-json-ide&lt;/artifactId&gt;
&lt;/dependency&gt;
</code></pre>
</div>
<p><strong>3) Minimal IDE WAR that will be reused to get some resources</strong></p>
<div class="highlighter-rouge"><pre class="highlight"><code> &lt;dependency&gt;
&lt;groupId&gt;org.eclipse.che&lt;/groupId&gt;
&lt;artifactId&gt;assembly-ide-war&lt;/artifactId&gt;
&lt;type&gt;war&lt;/type&gt;
&lt;scope&gt;runtime&lt;/scope&gt;
&lt;/dependency&gt;
</code></pre>
</div>
<h2 id="standard-assembly-of-ws-agent-server-war">Standard Assembly of ws-agent Server WAR</h2>
<p><strong>1) Core ws-agent WAR</strong></p>
<div class="highlighter-rouge"><pre class="highlight"><code> &lt;dependency&gt;
&lt;groupId&gt;org.eclipse.che.core&lt;/groupId&gt;
&lt;artifactId&gt;che-wsagent-core&lt;/artifactId&gt;
&lt;type&gt;war&lt;/type&gt;
&lt;/dependency&gt;
</code></pre>
</div>
<p><strong>2) Swagger support</strong></p>
<div class="highlighter-rouge"><pre class="highlight"><code> &lt;dependency&gt;
&lt;groupId&gt;org.eclipse.che.lib&lt;/groupId&gt;
&lt;artifactId&gt;che-swagger-module&lt;/artifactId&gt;
&lt;/dependency&gt;
</code></pre>
</div>
<p><strong>3) All ws-agent plugins</strong></p>
<div class="highlighter-rouge"><pre class="highlight"><code> &lt;dependency&gt;
&lt;groupId&gt;org.eclipse.che.plugin&lt;/groupId&gt;
&lt;artifactId&gt;che-plugin-*&lt;/artifactId&gt;
&lt;/dependency&gt;
</code></pre>
</div>
<h2 id="custom-assembly-of-minimal-che-ws-agent">Custom Assembly of Minimal Che ws-agent</h2>
<p><strong>1) Core ws-agent war</strong></p>
<div class="highlighter-rouge"><pre class="highlight"><code> &lt;dependency&gt;
&lt;groupId&gt;org.eclipse.che.core&lt;/groupId&gt;
&lt;artifactId&gt;che-wsagent-core&lt;/artifactId&gt;
&lt;type&gt;war&lt;/type&gt;
&lt;/dependency&gt;
</code></pre>
</div>
<p><strong>2) Server side plugins</strong></p>
<div class="highlighter-rouge"><pre class="highlight"><code> &lt;dependency&gt;
&lt;groupId&gt;my.plugin&lt;/groupId&gt;
&lt;artifactId&gt;plugin-json-server&lt;/artifactId&gt;
&lt;/dependency&gt;
</code></pre>
</div>
<h1 id="production-mode">Production Mode</h1>
<p>If you want to deploy your custom Che binaries in a production mode, i.e. make them reusable and independent from a locally mounted repo, you may build your own custom Che CLI. Building a custom CLI also makes it possible to setup CI systems that will generate nightly and tagged images.</p>
<ol>
<li>In the root of your custom Che assembly repo, create a directory <code class="highlighter-rouge">dockerfiles</code></li>
<li>Copy all files and directories as in this <a href="https://github.com/codenvy/plugin-openshift/tree/master/dockerfiles">example</a></li>
<li>In <a href="https://github.com/codenvy/plugin-openshift/blob/master/dockerfiles/build.include">build.include</a> change values of the following properties:
<div class="highlighter-rouge"><pre class="highlight"><code>ORGANIZATION="yourOrg"
PREFIX="yourCustomAssembly"
</code></pre>
</div>
<p>Usually, <code class="highlighter-rouge">ORGANIZATION</code> is your DockerHub/container registry account. <code class="highlighter-rouge">PREFIX</code> is used in image names. With the above properties you will have:</p>
</li>
</ol>
<ul>
<li><code class="highlighter-rouge">yourOrg/yourCustomAssembly-server</code> server image</li>
<li><code class="highlighter-rouge">yourOrg/yourCustomAssembly-cli</code> cli image</li>
<li><code class="highlighter-rouge">yourOrg/yourCustomAssembly-init</code> init image with the default configuration</li>
</ul>
<p>All Dockerfiles inherit base Che images. You should make sure that che-parent version in your root <code class="highlighter-rouge">pom.xml</code> is identical to the tag in <code class="highlighter-rouge">FROM</code> instruction in all 3 Dockerfiles (server, cli and init). If you stay with Che master, then nightly tags are OK. If you depend on a tagged Che version, use the same tag in a Dockerfile:</p>
<p><code class="highlighter-rouge">FROM eclipse/che-server:nightly</code></p>
<p>or</p>
<p><code class="highlighter-rouge">FROM eclipse/che-server:5.10.0</code></p>
<ol>
<li>In <code class="highlighter-rouge">dockerfiles/cli/version/$TAG/images</code> make sure that your custom images are used. There is no need to change <code class="highlighter-rouge">IMAGE_COMPOSE</code>, just server and init images:</li>
</ol>
<div class="highlighter-rouge"><pre class="highlight"><code>IMAGE_INIT=yourOrg/yourCustomAssembly-init:0.1.0
IMAGE_CHE=yourOrg/yourCustomAssembly-server:0.1.0
IMAGE_COMPOSE=docker/compose:1.8.1
</code></pre>
</div>
<p>When building tagged images with <code class="highlighter-rouge">build.sh</code> make sure you use an existing version otherwise CLI won’t be able to find it. It is reasonable to always have <code class="highlighter-rouge">nightly</code>, ‘latest’ tagged tagged with the latest version and all tagged versions as well:</p>
<div class="highlighter-rouge"><pre class="highlight"><code>/0.1.0
/latest
/nightly
latest.ver
</code></pre>
</div>
<p><code class="highlighter-rouge">latest.ver</code> file should also contain the latest version which makes it convenient to tag images in CI systems. This makes it possible to run images without tags, so that Docker automatically pulls the latest tag. <code class="highlighter-rouge">latest.ver</code> is optional though.</p>
<ol>
<li>
<p>Run <code class="highlighter-rouge">build.sh</code> in all 3 subdirs in <code class="highlighter-rouge">dockerfiles</code> directory. By default all images will be tagged as <code class="highlighter-rouge">nightly</code>. You may specify tag with <code class="highlighter-rouge">--tag=$TAG</code> argument passed to a script.</p>
</li>
<li>
<p>Run your custom Che:</p>
</li>
</ol>
<div class="highlighter-rouge"><pre class="highlight"><code>docker run -ti -v /var/run/docker.sock:/var/run/docker.sock -v ~/che-data:/data yourOrg/yourCustomAssembly-cli:nightly start
</code></pre>
</div>
<p>You may run the latest (no tag) or a particular tag too:</p>
<div class="highlighter-rouge"><pre class="highlight"><code>docker run -ti -v /var/run/docker.sock:/var/run/docker.sock -v ~/che-data:/data yourOrg/yourCustomAssembly-cli:0.1.0 start
</code></pre>
</div>
<p>Once <code class="highlighter-rouge">dockerfiles</code> directory is a part of your custom Che assembly repo, you may set up CI jobs to regularly build and push nightly and tagged images.</p>
<ol>
<li>Optional. Custom Che configuration. If your assembly needs custom config (default configuration comes with the <code class="highlighter-rouge">init</code> image), you need to work with addons. See example for <a href="https://github.com/codenvy/plugin-openshift/tree/master/dockerfiles/init/addon">OpenShift plugin</a></li>
</ol>
<p>Just mimic structure and approach, remove unnecessary properties and add your custom ones. If your assembly does not use custom properties, you do not need a custom init image at all, and may use <code class="highlighter-rouge">eclipse/che-init:$TAG</code> in <code class="highlighter-rouge">dockerfiles/build.include</code></p>
<h1 id="example">Example</h1>
<p>Let’s walk through the folder structure for the custom assembly generated by the archetype identified by <code class="highlighter-rouge">plugin-wizard-archetype</code>. This is a custom assembly that has a server-side and IDE plugin that work with one another.</p>
<div class="language-shell highlighter-rouge"><pre class="highlight"><code>pom.xml
<span class="c"># Describes dependencies that are used throughout the custom assembly.</span>
<span class="c"># Disables license and sortpom plugin executions defined in the parent POM.</span>
assembly-che/assembly-ide-war
<span class="c"># Repackages the IDE by declaring dependencies from the source Che assembly along with</span>
<span class="c"># including a new custom plugin and its associated shared model.</span>
<span class="c"># Contains instructions for generating a master IDE GWT XML from dependencies.</span>
<span class="c"># Contains GWT plugin for compiling into different browser types (permutations).</span>
<span class="c"># Contains antrun task for attaching build information.</span>
<span class="c"># Contains the WAR plugin configuration for adding resources (like icons) from the parent.</span>
assembly-che/assembly-main
<span class="c"># Packages Che's server Tomcat which includes the `assembly-ide-war`.</span>
assembly-che/assembly-wsagent-server
<span class="c"># Packages the workspace agent's Tomcat server, which includes `assembly-wsagent-war`.</span>
assembly-che/assembly-wsagent-war
<span class="c"># Packages the server service into a Web app to be deployed within the workspace.</span>
assembly-codenvy
<span class="c"># Same modules as Che, but configured for a Codenvy deployment</span>
plugins/&lt;artifactid&gt;/&lt;artifactid&gt;-ide
<span class="c"># IDE extension written in Java &amp; GWT</span>
plugins/&lt;artifactid&gt;/&lt;artifactid&gt;-server
<span class="c"># REST extension to run within a workspace</span>
plugins/&lt;artifactid&gt;/&lt;artifactid&gt;-shared
<span class="c"># Code that is shared between IDE and server (will be packaged in both)</span>
</code></pre>
</div>
<p>And because it is interesting, here is the file composition of the three plugins.</p>
<p><code class="highlighter-rouge">plugins/&lt;artifactid&gt;/&lt;artifactid&gt;-shared</code>:</p>
<div class="language-shell highlighter-rouge"><pre class="highlight"><code>pom.xml
<span class="c"># Basic module descriptor</span>
src/main/java/com/sample/shared/Constants.java
<span class="c"># Constants that are used across both IDE and server modules</span>
</code></pre>
</div>
<p><code class="highlighter-rouge">plugins/&lt;artifactid&gt;/&lt;artifactid&gt;-server</code>:</p>
<div class="language-shell highlighter-rouge"><pre class="highlight"><code>pom.xml
<span class="c"># Basic module descriptor</span>
src/main/java/com/sample/inject/SampleWizardModule.java
<span class="c"># Dependency injection module, where binding of project type occurs</span>
src/main/java/com/sample/projecttype/SampleProjectType.java
<span class="c"># Project type definition</span>
</code></pre>
</div>
<p><code class="highlighter-rouge">plugins/&lt;artifactid&gt;/&lt;artifactid&gt;-ide</code>:</p>
<div class="language-shell highlighter-rouge"><pre class="highlight"><code>pom.xml
<span class="c"># Basic module descriptor</span>
src/main/java/com/sample/ide/SampleWizardExtension.java
<span class="c"># Extension definiton responsible for registering actions, menus, registrars, etc.</span>
src/main/java/com/sample/ide/SampleWizardLocalizationConstant.java
<span class="c"># Interface for accessing GWT Localization constants written in .properties file</span>
src/main/java/com/sample/ide/SampleWizardResources.java
<span class="c"># Interface for accessing GWT resources, like SVG icons</span>
<span class="c">### The action package contains Actions to be triggered by buttons, menus, etc:</span>
src/main/java/com/sample/ide/action/NewXFileAction.java
<span class="c"># Action which in this example will be triggered by menu selection</span>
<span class="c">### The file package contains classes related to the "New X File" form:</span>
src/main/java/com/sample/ide/file/NewXFilePresenter.java
<span class="c"># Presenter class, responsible for logic of file creation</span>
src/main/java/com/sample/ide/file/NewXFileView.java
<span class="c"># View interface class, which is used in the presenter</span>
src/main/java/com/sample/ide/file/NewXFileViewImpl.java
<span class="c"># View implementation class, containing GWT or JavaScript code to display the form</span>
src/main/java/com/sample/ide/file/NewXFileView.ui.xml
<span class="c"># UIBinder XML file, A GWT concept to provide declarative layout of the "New X File" form</span>
<span class="c">### The inject package contains GIN dependency injection module:</span>
src/main/java/com/sample/ide/inject/SampleWizardGinModule.java
<span class="c"># Dependency injection GIN module, which binds constructors to your classes</span>
<span class="c">### The wizard package contains a custom Project Wizard page:</span>
src/main/java/com/sample/ide/wizard/SamplePagePresenter.java
<span class="c"># Presenter class, responsible for logic of Project Wizard custom project creation page</span>
src/main/java/com/sample/ide/wizard/SamplePageView.java
<span class="c"># View interface class, which is used in the presenter</span>
src/main/java/com/sample/ide/wizard/SamplePageViewImpl.java
<span class="c"># View implementation class, which contains GWT code for the Project Wizard creation page</span>
src/main/java/com/sample/ide/wizard/SamplePageViewImpl.ui.xml
<span class="c"># A UIBinder XML file, which is a GWT declarative layout of the Project Wizard creation page</span>
src/main/java/com/sample/ide/wizard/SampleWizardRegistrar.java
<span class="c"># Class that registers our custom page in the Project Wizard</span>
<span class="c">### Resources define the plugin's GWT module, files like icons, and properties</span>
src/main/resouces/com/sample/SampleWizard.gwt.xml
<span class="c"># GWT XML module snippet - will be included into a global GWT module created during build</span>
src/main/resouces/com/sample/ide/SampleWizardLocalizationConstant.properties
<span class="c"># Properties of string constants, which are used in GWT code for form names and so on</span>
src/main/resouces/com/sample/ide/svg/c_file.svg
<span class="c"># SVG icon for custom project type displayed in the project wizard form</span>
src/main/resouceseclipse/che-cli/ide/svg/category.svg
<span class="c"># SVG icon for custom project type category display in the project wizard form</span>
</code></pre>
</div>
</article>
</div>
<div class="unit one-fifth hide-on-mobiles">
<aside>
<h4>SETUP</h4>
<ul>
<li class=""><a href="../../../docs/index.html">Introduction</a></li>
<li class=""><a href="../../../docs/setup/getting-started/index.html">Getting Started&#58 Local</a></li>
<li class=""><a href="../../../docs/setup/getting-started-saas-cloud/index.html">Getting Started&#58 SaaS Cloud</a></li>
<li class=""><a href="../../../docs/setup/configuration/index.html">Configuration</a></li>
<li class=""><a href="../../../docs/setup/managing/index.html">Managing</a></li>
<li class=""><a href="../../../docs/setup/cli/index.html">CLI Reference</a></li>
<li class=""><a href="../../../docs/setup/glossary/index.html">Glossary</a></li>
<li class=""><a href="../../../docs/setup/docker/index.html">Docker Installation</a></li>
<li class=""><a href="../../../docs/setup/openshift/index.html">OpenShift Installation</a></li>
<li class=""><a href="../../../docs/setup/selenium/index.html">How to run selenium tests</a></li>
</ul>
<h4>WORKSPACE ADMINISTRATION</h4>
<ul>
<li class=""><a href="../../../docs/devops/intro/index.html">Introduction</a></li>
<li class=""><a href="../../../docs/devops/runtime-stacks/index.html">Runtime Stacks</a></li>
<li class=""><a href="../../../docs/devops/runtime-recipes/index.html">Runtime Recipes</a></li>
<li class=""><a href="../../../docs/devops/project-samples/index.html">Project Samples</a></li>
<li class=""><a href="../../../docs/devops/runtime-machines/index.html">Runtime Machines</a></li>
<li class=""><a href="../../../docs/devops/volume-mounts/index.html">Volume Mounts</a></li>
<li class=""><a href="../../../docs/devops/ws-agents/index.html">Workspace Agents</a></li>
<li class=""><a href="../../../docs/devops/workspaces-data-model/index.html">Workspace Data Model</a></li>
<li class=""><a href="../../../docs/devops/runtime-stacks-data-model/index.html">Runtime Stacks Data Model</a></li>
<li class=""><a href="../../../docs/devops/project-samples-data-model/index.html">Project Samples Data Model</a></li>
</ul>
<h4>USER GUIDE</h4>
<ul>
<li class=""><a href="../../../docs/ide/projects/index.html">Projects</a></li>
<li class=""><a href="../../../docs/ide/import-a-project/index.html">Import</a></li>
<li class=""><a href="../../../docs/ide/ssh/index.html">SSH</a></li>
<li class=""><a href="../../../docs/ide/sync/index.html">Local IDE Sync</a></li>
<li class=""><a href="../../../docs/ide/editor-settings/index.html">Editor</a></li>
<li class=""><a href="../../../docs/ide/intellisense/index.html">Intellisense</a></li>
<li class=""><a href="../../../docs/ide/commands/index.html">Commands</a></li>
<li class=""><a href="../../../docs/ide/git-svn/index.html">Git and SVN</a></li>
<li class=""><a href="../../../docs/ide/previews/index.html">Previews</a></li>
<li class=""><a href="../../../docs/ide/build/index.html">Build</a></li>
<li class=""><a href="../../../docs/ide/run/index.html">Run</a></li>
<li class=""><a href="../../../docs/ide/sharing/index.html">Share</a></li>
<li class=""><a href="../../../docs/ide/debug/index.html">Debug</a></li>
<li class=""><a href="../../../docs/ide/docker/index.html">Docker</a></li>
<li class=""><a href="../../../docs/ide/electron/index.html">Install Che Desktop Client</a></li>
</ul>
<h4>PORTABLE WORKSPACES</h4>
<ul>
<li class=""><a href="../../../docs/chedir/getting-started/index.html">Chedir - Getting Started</a></li>
<li class=""><a href="../../../docs/chedir/why/index.html">Chedir - Why Chedir?</a></li>
<li class=""><a href="../../../docs/chedir/installation/index.html">Chedir - Installation</a></li>
<li class=""><a href="../../../docs/chedir/project-setup/index.html">Chedir - Project Setup</a></li>
<li class=""><a href="../../../docs/chedir/up-and-down/index.html">Chedir - Up and Down</a></li>
<li class=""><a href="../../../docs/chedir/chefiles/index.html">Chedir - Chefile</a></li>
<li class=""><a href="../../../docs/chedir/ssh/index.html">Chedir - SSH</a></li>
<li class=""><a href="../../../docs/chedir/factories/index.html">Chedir - Factories</a></li>
<li class=""><a href="../../../docs/factory/getting-started/index.html">Factory - Getting Started</a></li>
<li class=""><a href="../../../docs/factory/creating/index.html">Factory - Creating</a></li>
<li class=""><a href="../../../docs/factory/json-reference/index.html">Factory - JSON Reference</a></li>
</ul>
<h4>DEVELOPER GUIDE - REST API</h4>
<ul>
<li class=""><a href="../../../docs/assemblies/intro/index.html">Introduction</a></li>
<li class=""><a href="../../../docs/assemblies/archetype/index.html">Archetype</a></li>
<li class="current"><a href="../../../docs/assemblies/assembly-lifecycle/index.html">Assembly Dev Lifecycle</a></li>
<li class=""><a href="../../../docs/assemblies/plugin-lifecycle/index.html">Plugin Lifecycle</a></li>
<li class=""><a href="../../../docs/assemblies/sdk-rest-apis/index.html">SDK REST APIs</a></li>
<li class=""><a href="../../../docs/assemblies/sdk-class-reference/index.html">SDK Class Reference</a></li>
<li class=""><a href="../../../docs/assemblies/sdk-dependency-injection/index.html">SDK Dependency Injection</a></li>
<li class=""><a href="../../../docs/assemblies/sdk-dto/index.html">SDK DTOs</a></li>
<li class=""><a href="../../../docs/assemblies/sdk-properties/index.html">SDK Properties</a></li>
<li class=""><a href="../../../docs/assemblies/sdk-code-editors/index.html">SDK Editors</a></li>
<li class=""><a href="../../../docs/assemblies/sdk-embed-htmljs/index.html">SDK Embedded JavaScript</a></li>
<li class=""><a href="../../../docs/assemblies/sdk-project-types/index.html">SDK Project Types</a></li>
<li class=""><a href="../../../docs/assemblies/sdk-actions/index.html">SDK Actions</a></li>
<li class=""><a href="../../../docs/assemblies/sdk-services/index.html">SDK Services</a></li>
<li class=""><a href="../../../docs/assemblies/sdk-parts/index.html">SDK Parts</a></li>
<li class=""><a href="../../../docs/assemblies/sdk-themes/index.html">SDK Themes</a></li>
<li class=""><a href="../../../docs/assemblies/sdk-custom-agents/index.html">SDK Custom Agents</a></li>
<li class=""><a href="../../../docs/assemblies/sdk-language-server-protocol/index.html">SDK Language Server Protocol</a></li>
<li class=""><a href="../../../docs/assemblies/sdk-workspace/index.html">SDK Workspace</a></li>
</ul>
</aside>
</div>
<div class="clear"></div>
</div>
</section>
<script>
var anchorForId = function (id) {
var anchor = document.createElement("a");
anchor.className = "header-link";
anchor.href = "#" + id;
anchor.innerHTML = "<span class=\"sr-only\">Permalink</span><i class=\"fa fa-link\"></i>";
anchor.title = "Permalink";
return anchor;
};
var linkifyAnchors = function (level, containingElement) {
var headers = containingElement.getElementsByTagName("h" + level);
for (var h = 0; h < headers.length; h++) {
var header = headers[h];
if (typeof header.id !== "undefined" && header.id !== "") {
header.appendChild(anchorForId(header.id));
}
}
};
document.onreadystatechange = function () {
if (this.readyState === "complete") {
var contentBlock = document.getElementsByClassName("artik")[0] || document.getElementsByClassName("openshift")[0] || document.getElementsByClassName("tutorials")[0] || document.getElementsByClassName("docs")[0] || document.getElementsByClassName("news")[0];
if (!contentBlock) {
return;
}
for (var level = 1; level <= 6; level++) {
linkifyAnchors(level, contentBlock);
}
}
};
</script>
</body>
</html>