Google Git
Sign in
eclipse/gerrit/www.eclipse.org/che/refs/heads/CheConf18/./docs/setup/configuration/index.html
blob: 3f5ce04171946e0e6a1e6f09b0d9c455e0d657df [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>Configuration -
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="current"><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=""><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/setup/setup-configuration.md"><i class="fa fa-pencil"></i> &nbsp;Improve this page</a>
<!--<a href="https://github.com/eclipse/che/blob/master/docs/_docs/setup/setup-configuration.md"><i class="fa fa-pencil"></i> &nbsp;Improve this page</a>-->
</div>
<div class="doc-title">
<h1>Configuration</h1>
<div class="doc-title-border">
</div>
</div>
<p>Configuration is handled by modifying <code class="highlighter-rouge">che.env</code> placed in the host folder volume mounted to <code class="highlighter-rouge">:/data</code>. This configuration file is generated during the <code class="highlighter-rouge">che init</code> phase. If you rerun <code class="highlighter-rouge">che init</code> in an already initialized folder, the process will abort unless you pass <code class="highlighter-rouge">--force</code>, <code class="highlighter-rouge">--pull</code>, or <code class="highlighter-rouge">--reinit</code>.</p>
<p>Each variable is documented with an explanation and usually commented out. If you need to set a variable, uncomment it and configure it with your value. You can then run <code class="highlighter-rouge">che config</code> to apply this configuration to your system. <code class="highlighter-rouge">che start</code> also reapplies the latest configuration.</p>
<p>You can run <code class="highlighter-rouge">che init</code> to install a new configuration into an empty directory. This command uses the <code class="highlighter-rouge">che/init:&lt;version&gt;</code> Docker container to deliver a version-specific set of puppet templates into the folder.</p>
<p>If you run <code class="highlighter-rouge">che config</code>, che runs puppet to transform your puppet templates into a che instance configuration, placing the results into <code class="highlighter-rouge">/che/instance</code> if you volume mounted that, or into a <code class="highlighter-rouge">instance</code> subdirectory of the path you mounted to <code class="highlighter-rouge">/che</code>. Each time you start che, <code class="highlighter-rouge">che config</code> is run to ensure instance configuration files are properly generated and consistent with the configuration you have specified in <code class="highlighter-rouge">che.env</code>.</p>
<h1 id="saving-configuration-in-version-control">Saving Configuration in Version Control</h1>
<p>Administration teams that want to version control your che configuration should save <code class="highlighter-rouge">che.env</code>. This is the only file that should be saved with version control. It is not necessary, and even discouraged, to save the other files. If you were to perform a <code class="highlighter-rouge">che upgrade</code> we may replace these files with templates that are specific to the version that is being upgraded. The <code class="highlighter-rouge">che.env</code> file maintains fidelity between versions and we can generate instance configurations from that.</p>
<p>The version control sequence would be:</p>
<ol>
<li><code class="highlighter-rouge">che init</code> to get an initial configuration for a particular version.</li>
<li>Edit <code class="highlighter-rouge">che.env</code> with your environment-specific configuration.</li>
<li>Save <code class="highlighter-rouge">che.env</code> to version control.</li>
<li>Setup a new folder and copy <code class="highlighter-rouge">che.env</code> from version control into the folder you will mount to <code class="highlighter-rouge">:/data</code>.</li>
<li>Run <code class="highlighter-rouge">che config</code> or <code class="highlighter-rouge">che start</code>.</li>
</ol>
<h1 id="internal-configuration">Internal Configuration</h1>
<p>We provide a complete list of user-configurable properties in the <code class="highlighter-rouge">che.env</code> file. However, there are additional internal Che server properties that can also be configured. When we start the <code class="highlighter-rouge">che-server</code> Docker container, it is configured with a <code class="highlighter-rouge">che.properties</code> file to define a variety of internal operational details. You can <a href="https://github.com/eclipse/che/blob/08344fe62ebedfaa199e3258279b29acec7c88f8/assembly/assembly-wsmaster-war/src/main/webapp/WEB-INF/classes/codenvy/che.properties">view the default file</a> in our GitHub repo.</p>
<p>You can override these properties or pass in new Che server properties by defining additional environment variables within <code class="highlighter-rouge">che.env</code>. The CLI will convert any <code class="highlighter-rouge">che.env</code> additional properties into custom <code class="highlighter-rouge">che.properties</code> that are passed into the server.</p>
<p>Any variable with the format <code class="highlighter-rouge">CHE_PROPERTY_&lt;name&gt;=&lt;value&gt;</code> will be configured into property value. A single underscore <code class="highlighter-rouge">_</code> will be converted into a period <code class="highlighter-rouge">.</code>. A double underscore <code class="highlighter-rouge">__</code> will be converted into a single underscore <code class="highlighter-rouge">_</code>. For example:</p>
<div class="language-shell highlighter-rouge"><pre class="highlight"><code><span class="c"># This environment variable:</span>
<span class="nv">CHE_PROPERTY_machine_ws__agent_max__start__time__ms</span><span class="o">=</span>1000
<span class="c"># Is sent to the Che server as:</span>
machine.ws_agent.max_start_time_ms<span class="o">=</span>1000
</code></pre>
</div>
<h1 id="logs-and-user-data">Logs and User Data</h1>
<p>When Che initializes itself, it stores logs, user data, database data, and instance-specific configuration in the folder mounted to <code class="highlighter-rouge">:/data/instance</code> or an <code class="highlighter-rouge">instance</code> subfolder of what you mounted to <code class="highlighter-rouge">:/data</code>.</p>
<p>Che’s containers save their logs in the same location:</p>
<div class="language-shell highlighter-rouge"><pre class="highlight"><code>/instance/logs/che/2016 <span class="c"># Server logs</span>
/instance/logs/che/che-machine-logs <span class="c"># Workspace logs</span>
</code></pre>
</div>
<p>User data is stored in:</p>
<div class="language-shell highlighter-rouge"><pre class="highlight"><code>/instance/data/che <span class="c"># Project backups (we synchronize projs from remote ws here)</span>
</code></pre>
</div>
<p>Instance configuration is generated by Che and is updated by our internal configuration utilities. These ‘generated’ configuration files should not be modified and stored in:</p>
<div class="language-shell highlighter-rouge"><pre class="highlight"><code>/instance/che.ver.do_not_modify <span class="c"># Version of che installed</span>
/instance/docker-compose-container.yml <span class="c"># Docker compose to launch Che from within a container</span>
/instance/docker-compose.yml <span class="c"># Docker compose to launch Che from the host without contianer</span>
/instance/config <span class="c"># Configuration files for Che which are volume mounted into containers</span>
</code></pre>
</div>
<h1 id="oauth">oAuth</h1>
<p>You can configure Google, GitHub, Microsoft, BitBucket, or WSO2 oAuth for use when users perform git operations.</p>
<p>Che is shipped with a preconfigured GitHub oAuth application for the <code class="highlighter-rouge">che.onprem</code> hostname. To enable GitHub oAuth, add <code class="highlighter-rouge">che_HOST=che.onprem</code> to <code class="highlighter-rouge">che.env</code> and restart. If you have a custom DNS, you need to register a GitHub oAuth application with GitHub’s oAuth registration service. You will be asked for the callback URL, which is <code class="highlighter-rouge">http://&lt;your_hostname&gt;/api/oauth/callback</code>. You will receive from GitHub a client ID and secret, which must be added to <code class="highlighter-rouge">che.env</code>:</p>
<div class="highlighter-rouge"><pre class="highlight"><code>CHE_GITHUB_CLIENT_ID=yourID
CHE_GITHUB_SECRET=yourSecret
</code></pre>
</div>
<p>Google oAuth (and others) are configured the same:</p>
<div class="highlighter-rouge"><pre class="highlight"><code>CHE_GOOGLE_CLIENT_ID=yourID
CHE_GOOGLE_SECRET=yourSecret
</code></pre>
</div>
<h3 id="github-oauth">GitHub oAuth</h3>
<p>Refer to <a href="../../../docs/ide/git-svn/index.html#github-oauth">GitHub using OAuth</a> for configuration information.</p>
<h3 id="gitlab-oauth">GitLab oAuth</h3>
<p>Refer to <a href="../../../docs/ide/git-svn/index.html#gitlab-oauth">GitLab using OAuth</a> for configuration information.</p>
<h1 id="stacks">Stacks</h1>
<p><a href="../../../docs/devops/runtime-stacks/index.html">Stacks</a> define the recipes used to create workspace runtimes. They appear in the stack library of the dashboard. You can create your own.</p>
<p><code class="highlighter-rouge">CHE_PREDEFINED_STACKS_RELOAD__ON__START</code> (false by default) defines stack loading policy. When set to false, stacks are loaded from a json file only once - when database is initialized. When set to true, json is sourced every time Che server starts.</p>
<h1 id="sample-projects">Sample Projects</h1>
<p>Code <a href="../../../docs/devops/project-samples/index.html">samples</a> allow you to define sample projects that are cloned into a workspace if the user chooses it when creating a new project. You can add your own.</p>
<h1 id="workspace-limits">Workspace Limits</h1>
<p>You can place limits on how users interact with the system to control overall system resource usage. You can define how many workspaces created, RAM consumed, idle timeout, and a variety of other parameters.</p>
<p>You can also set limits on Docker’s allocation of CPU to workspaces, which may be necessary if you have a very dense workspace population where users are competing for limited physical resources.</p>
<p>Workspace idle timeout can be configured in <code class="highlighter-rouge">che.env</code> , so that inactive workspaces will be shutdown automatically over this length of time in milliseconds. By default, this value is set to 3600000 (1 hour). If set to “0”, then workspaces will not be stopped automatically. Currently, keyboard and mouse interactions in IDE, as well as HTTP requests to ws-agent count as activity</p>
<h1 id="hostname">Hostname</h1>
<p>The IP address or DNS name of where the Che endpoint will service your users. If you are running this on a local system, we auto-detect this value as the IP address of your Docker daemon. On many systems, especially those from cloud hosters like DigitalOcean, you may have to explicitly set this to the external IP address or DNS entry provided by the provider. You can edit this value in <code class="highlighter-rouge">che.env</code> and restart Che, or you can pass it during initialization:</p>
<div class="highlighter-rouge"><pre class="highlight"><code>docker run &lt;OTHER-DOCKER_OPTIONS&gt; -e CHE_HOST=&lt;ip-addr-or-dns&gt; eclipse/che:&lt;version&gt; start
</code></pre>
</div>
<h1 id="networking">Networking</h1>
<p>Eclipse Che makes connections between three entities: the browser, the Che server running in a Docker container, and a workspace running in a Docker container.</p>
<p>If you distribute these components onto different nodes, hosts or IP addresses, then you may need to add additional configuration parameters to bridge different networks.</p>
<p>Also, since the Che server and your Che workspaces are within containers governed by a Docker daemon, you also need to ensure that these components have good bridges to communicate with the daemon.</p>
<p>Generally, if your browser, Che server and Che workspace are all on the same node, then <code class="highlighter-rouge">localhost</code> configuration will always work.</p>
<h2 id="websockets">WebSockets</h2>
<p>Che relies on web sockets to stream content between workspaces and the browser. We have found many networks and firewalls to block portions of Web socket communications. If there are any initial configuration issues that arise, this is a likely cause of the problem.</p>
<h2 id="topology">Topology</h2>
<p>The Che server runs in its own Docker container, “Che Docker Container”, and each workspace gets an embedded runtime which can be a set of additional Docker containers, “Docker Container(n)”. All containers are managed by a common Docker daemon, “docker-ip”, making them siblings of each other. This includes the Che server and its workspaces - each workspace runtime environment has a set of containers that is a sibling to the Che server, not a child.</p>
<p><img src="../../../docs/assets/imgs/Capture.PNG" alt="Capture.PNG" /></p>
<h2 id="connectivity">Connectivity</h2>
<p>The browser client initiates communication with the Che server by connecting to <code class="highlighter-rouge">che-ip</code>. This IP address must be accessible by your browser clients. Internally, Che runs on Tomcat which is bound to port <code class="highlighter-rouge">8080</code>. This port can be altered by setting <code class="highlighter-rouge">CHE_PORT</code> during start or in your <code class="highlighter-rouge">che.env</code>.</p>
<p>When a user creates a workspace, the Che server connects to the Docker daemon at <code class="highlighter-rouge">docker-ip</code> and uses the daemon to launch a new set of containers that will power the workspace. These workspace containers will have a Docker-configured IP address, <code class="highlighter-rouge">workspace-container-ip</code>. The <code class="highlighter-rouge">workspace-container-ip</code> isn’t usually reachable by your browser host, <code class="highlighter-rouge">docker-ip</code> will be used to establish the connections between the browser and workspace containers.</p>
<p>Che goes through a progression algorithm to establish the protocol, IP address and port to establish communications when it is booting or starting a workspace. You can override certain parameters in Che’s configuration to overcome issues with the Docker daemon, workspaces, or browsers being on different networks.</p>
<div class="highlighter-rouge"><pre class="highlight"><code># Browser --&gt; Che Server
# 1. Default is 'http://localhost:${SERVER_PORT}/wsmaster/api'.
# 2. Else use the value of che.api
#
# Che Server --&gt; Docker Daemon Progression:
# 1. Use the value of che.docker.daemon_url
# 2. Else, use the value of DOCKER_HOST system variable
# 3. Else, use Unix socket over unix:///var/run/docker.sock
#
# Che Server --&gt; Workspace Connection (see Workspace Address Resolution Strategy, below):
# - If CHE_DOCKER_SERVER__EVALUATION__STRATEGY is 'default':
# 1. Use the value of che.docker.ip
# 2. Else, use address of docker0 bridge network, if available
# 3. Else, if server connects over Unix socket, then use localhost
# 4. Else, use DOCKER_HOST
# - If CHE_DOCKER_SERVER__EVALUATION__STRATEGY is 'docker-local':
# 1. Use the address of the workspace container within the docker network
# 2. If address cannot be read, use steps 3 and 4 from the default strategy.
#
# Browser --&gt; Workspace Connection:
# 1. Use the value of che.docker.ip
# 2. Else, if server connects over Unix socket, then use localhost
# 3. Else, use DOCKER_HOST
#
# Workspace Agent --&gt; Che Server
# 1. Default is http://che-host:${SERVER_PORT}/wsmaster/api, where che-host is IP of server.
# 2. Else, use value of che.workspace.che_server_endpoint
# 3. Else, if 'docker0' interface is unreachable, then che-host replaced with
# 172.17.42.1 or 192.168.99.1
# 4. Else, print connection exception
</code></pre>
</div>
<p>It is common for configuration with firewalls, routers, networks and hosts to make the default values we detect to establish these connections incorrect. You can run <code class="highlighter-rouge">docker run &lt;DOCKER_OPTIONS&gt; eclipse/che info --network</code> to run a test that makes connections between simulated components to reflect the networking setup of Che as it is configured. You do not need all connections to pass for Che to be properly configured. For example, on a Windows machine, this output may exist, just indicating that <code class="highlighter-rouge">localhost</code> is not an acceptable domain for communications, but the IP address <code class="highlighter-rouge">10.0.75.2</code> is.</p>
<div class="highlighter-rouge"><pre class="highlight"><code>INFO: ---------------------------------------
INFO: -------- CONNECTIVITY TEST --------
INFO: ---------------------------------------
INFO: Browser =&gt; Workspace Agent (localhost): Connection failed
INFO: Browser =&gt; Workspace Agent (10.0.75.2): Connection succeeded
INFO: Server =&gt; Workspace Agent (External IP): Connection failed
INFO: Server =&gt; Workspace Agent (Internal IP): Connection succeeded
</code></pre>
</div>
<p>You can also perform additional tests yourself against an already-running Che server. You will need to use <code class="highlighter-rouge">docker ps</code> and <code class="highlighter-rouge">docker inspect</code> on the command line to get the container name and IP address of your Che server, and then you can run additional tests:</p>
<div class="highlighter-rouge"><pre class="highlight"><code># Browser =&gt; Workspace Ageent (External IP):
$ curl http://&lt;che-ip&gt;:&lt;che-port&gt;/wsagent/ext/
# Server =&gt; Workspace Agent (External IP):
docker exec -ti &lt;che-container-name&gt; curl http://&lt;che-ip&gt;:&lt;che-port&gt;/wsagent/ext/
# Server =&gt; Workspace Agent (Internal IP):
docker exec -ti &lt;che-container-name&gt; curl http://&lt;workspace-container-ip&gt;:4401/wsagent/ext/
</code></pre>
</div>
<h4 id="dns-resolution">DNS Resolution</h4>
<p>The default behavior is for Che and its workspaces to inherit DNS resolver servers from the host. You can override these resolvers by setting <code class="highlighter-rouge">CHE_DNS_RESOLVERS</code> in the <code class="highlighter-rouge">che.env</code> file and restarting Che. DNS resolvers allow programs and services that are deployed within a user workspace to perform DNS lookups with public or internal resolver servers. In some environments, custom resolution of DNS entries (usually to an internal DNS provider) is required to enable the Che server and the workspace runtimes to have lookup ability for internal services.</p>
<div class="language-shell highlighter-rouge"><pre class="highlight"><code><span class="c"># Update your che.env with comma separated list of resolvers:</span>
<span class="nv">CHE_DNS_RESOLVERS</span><span class="o">=</span>10.10.10.10,8.8.8.8
</code></pre>
</div>
<h4 id="workspace-address-resolution-strategy">Workspace Address Resolution Strategy</h4>
<p>By default, the Che server will connect to workspace containers according to the ‘default’ strategy. The order of precedence, Che will use <code class="highlighter-rouge">CHE_DOCKER_IP</code> if it is set, if not, it will use the address <code class="highlighter-rouge">docker-ip</code>. If <code class="highlighter-rouge">docker-ip</code> cannot be determined, it will default to <code class="highlighter-rouge">localhost</code> for Unix socket connections, and <code class="highlighter-rouge">DOCKER_HOST</code>.</p>
<p>Alternatives strategies are available by setting <code class="highlighter-rouge">CHE_DOCKER_SERVER__EVALUATION__STRATEGY</code>.
By setting it to ‘docker-local’, Che will attempt to communicate with workspace containers directly, using <code class="highlighter-rouge">workspace-container-ip</code>, with <code class="highlighter-rouge">localhost</code>/<code class="highlighter-rouge">DOCKER_HOST</code> as a fallback as in the default strategy. This can avoid some issues with ephemeral ports and firewalls (see section ‘Firewalls’, below), but will cause workspace creation to fail if the Che server is configured to not launch workspaces within the same Docker network.</p>
<p>By setting it to ‘custom’, Che will allow to customize the links by using a template by using the property che.docker.server_evaluation_strategy.custom.template that can be defined by using <code class="highlighter-rouge">CHE_DOCKER_SERVER__EVALUATION__STRATEGY_CUSTOM_TEMPLATE</code> environment variable.</p>
<p>Here are macros available for the custom server evaluation strategy:</p>
<ul>
<li>serverName: server reference exposing the port (like tomcat8, ws-agent, etc)</li>
<li>machineName: name of the machine of the workspace. (like devMachine)</li>
<li>workspaceId: id of the workspace</li>
<li>internalIp: IP of the internal address of che (che.docker.ip property)</li>
<li>externalIP: IP of the external address of che</li>
<li>externalAddresss : external address of che (che.docker.ip.external or if null che.docker.ip)</li>
<li>chePort : Che listening port number of workspace master</li>
<li>wildcardNipDomain : get external address transformed into a nip.io DNS sub-domain</li>
<li>wildcardXipDomain : get external address transformed into a xip.io DNS sub-domain</li>
</ul>
<p>Here is an example <code class="highlighter-rouge">che.docker.server_evaluation_strategy.custom.template=&lt;serverName&gt;.&lt;machineName&gt;.&lt;workspaceId&gt;.&lt;wildcardNipDomain&gt;:&lt;chePort&gt;</code></p>
<h4 id="single-port-routing">Single-port routing.</h4>
<p>By enabling single-port, using <code class="highlighter-rouge">CHE_SINGLE_PORT=true</code> in <code class="highlighter-rouge">che.env</code> file , all browser traffic to Che or any workspace will be routed through the value that you have set to <code class="highlighter-rouge">CHE_PORT</code>, or 8080 if not set.
Setting this property will transform the launch sequence of Che to launch a Traefik reverse proxy. The reverse proxy will act as the traffic endpoint for all browser communications.
When a new workspace is started or stopped, Che will update Traefik’s configuration with rules for how browser traffic should be routed to Che or a workspace.
With single-port, each service running in a workspace and exposing ports has its own hostname. Example : workspace agent will have a hostname like : ws-agent.workspace-id….domain.name. By default the domain name will use nip.io which allow to provide wildcard DNS without any
user configuration. The strategy used for the hosts is using the template provided by the <code class="highlighter-rouge">CHE_DOCKER_SERVER__EVALUATION__STRATEGY_CUSTOM_TEMPLATE</code> property with default value <code class="highlighter-rouge">&lt;serverName&gt;.&lt;machineName&gt;.&lt;workspaceId&gt;.&lt;wildcardNipDomain&gt;:&lt;chePort&gt;</code>
If you’ve your own domain and then DNS server, you may want to add wildcard DNS entry matching a pattern. For example updating the property to the value <code class="highlighter-rouge">&lt;serverName&gt;.&lt;machineName&gt;.&lt;workspaceId&gt;.che.foobar.com:&lt;chePort&gt;</code> will require a wildcard <code class="highlighter-rouge">*.che.foobar.com</code> entry in DNS server resolving to the IP of the che server.</p>
<h2 id="docker-connectivity">Docker Connectivity</h2>
<p>There are multiple techniques for connecting to Docker including Unix sockets, localhost, and remote connections over TCP protocol. Depending upon the type of connection you require and the location of the machine node running Docker, we use different parameters.</p>
<h2 id="workspace-port-exposure">Workspace Port Exposure</h2>
<p>Inside your user’s workspace containers, Che launches microservices on port <code class="highlighter-rouge">4401</code> and <code class="highlighter-rouge">4403</code>. We also launch SSH agents on port <code class="highlighter-rouge">22</code>. The terminal accessible in the workspace is also launched as an agent in the workspace on port <code class="highlighter-rouge">4411</code>. Custom stacks (configured in the dashboard) may expose additional services on different ports.</p>
<p>Docker uses ephemeral port mapping. The ports accessible to your clients start at port <code class="highlighter-rouge">32768</code> and go through a wide range. When we start services internal to Docker, they are mapped to one of these ports. It is these ports that the browser (or SSH) clients connect to, and would need to be opened if connecting through a firewall.</p>
<p>Additionally, if services are started within the workspace that expose their own ports, then those ports need to have an <code class="highlighter-rouge">EXPOSE &lt;port&gt;</code> command added to the workspace image Dockerfile, or from within the user dashboard these ports need to be explicitly added to the workspace configuration. As a courtesy, in our default stack images, we expose port <code class="highlighter-rouge">80</code> and <code class="highlighter-rouge">8080</code> within the container for any users that want to launch services on those ports.</p>
<h2 id="firewalls">Firewalls</h2>
<p>On Linux, a firewall may block inbound connections from within Docker containers to your localhost network. As a result, the workspace agent is unable to ping the Che server. You can check for the firewall and then disable it.</p>
<p>Firewalls will typically cause traffic problems to appear when you are starting a new workspace. There are certain network configurations where we direct networking traffic between workspaces and Che through external IP addresses, which can flow through routers or firewalls. If ports or protocols are blocked, then certain functions will be unavailable.</p>
<h3 id="running-behind-a-firewall-linuxmac">Running Behind a Firewall (Linux/Mac)</h3>
<div class="language-shell highlighter-rouge"><pre class="highlight"><code><span class="c"># Check to see if firewall is running:</span>
systemctl status firewalld
<span class="c"># Check for list of open ports</span>
<span class="c"># Verify that ports 8080tcp, 32768-65535tcp are open</span>
firewall-cmd --list-ports
<span class="c"># Optionally open ports on your local firewall:</span>
firewall-cmd --permanent --add-port<span class="o">=</span>8080/tcp
... and so on
<span class="c"># You can also verify that ports are open:</span>
nmap -Pn -p &lt;port&gt; localhost
<span class="c"># If the port is closed, then you need to open it by editing /etc/pf.conf.</span>
<span class="c"># For example, open port 1234 for TCP for all interfaces:</span>
pass <span class="k">in </span>proto tcp from any to any port 1234
<span class="c"># And then restart your firewall</span>
</code></pre>
</div>
<h3 id="running-che-behind-a-firewall-windows">Running Che Behind a Firewall (Windows)</h3>
<p>There are many third party firewall services. Different versions of Windows OS also have different firewall configurations. The built-in Windows firewall can be configured in the control panel under “System and Security”:</p>
<ol>
<li>In the left pane, right-click <code class="highlighter-rouge">Inbound Rules</code>, and then click <code class="highlighter-rouge">New Rule</code> in the action pane.</li>
<li>In the <code class="highlighter-rouge">Rule Type</code> dialog box, select <code class="highlighter-rouge">Port</code>, and then click <code class="highlighter-rouge">Next</code>.</li>
<li>In the <code class="highlighter-rouge">Protocol and Ports</code> dialog box, select <code class="highlighter-rouge">TCP</code>.</li>
<li>Select speicfic local ports, enter the port number to be opened and click <code class="highlighter-rouge">Next</code>.</li>
<li>In the <code class="highlighter-rouge">Action</code> dialog box, select <code class="highlighter-rouge">Allow the Connection</code>, and then click <code class="highlighter-rouge">Next</code>.</li>
<li>In the <code class="highlighter-rouge">Name</code> dialog box, type a name and description for this rule, and then click <code class="highlighter-rouge">Finish</code>.</li>
</ol>
<h1 id="docker">Docker</h1>
<p>Eclipse Che workspace runtimes are powered by one or more Docker containers. When a user creates a workpace, they do so from a <a href="../../../docs/devops/runtime-stacks/index.html">stack</a> which includes a Dockerfile or reference to a Docker image which will be used to create the containers for the workspace runtimes. Che stacks can pull that image from a public registry, like DockerHub, or a private registry. Images in a registry can be publicly visible or private, which require user credentials to access. You can also set up a private registry to act as a mirror to Docker Hub. And, if you are running Eclipse Che behind a proxy, you can configure the Docker daemon registry to operate behind a proxy.</p>
<h2 id="private-images">Private Images</h2>
<p>When users create a workspace in Eclipse Che, they must select a Docker image to power the workspace. We provide ready-to-go stacks which reference images hosted at the public Docker Hub, which do not require any authenticated access to pull. You can provide your own images that are stored in a local private registry or at Docker Hub. The images may be publicly or privately visible, even if they are part of a private registry.</p>
<p>If your stack images that Che wants to pull require authenticated access to any registry, or if you want Che to push snapshot images into a registry (also requiring authenticated access), then you must configure registry authentication.</p>
<p>In <code class="highlighter-rouge">che.env</code>:</p>
<div class="highlighter-rouge"><pre class="highlight"><code>CHE_DOCKER_REGISTRY_AUTH_REGISTRY1_URL=url1
CHE_DOCKER_REGISTRY_AUTH_REGISTRY1_USERNAME=username1
CHE_DOCKER_REGISTRY_AUTH_REGISTRY1_PASSWORD=password1
CHE_DOCKER_REGISTRY_AWS_REGISTRY1_ID=id1
CHE_DOCKER_REGISTRY_AWS_REGISTRY1_REGION=region1
CHE_DOCKER_REGISTRY_AWS_REGISTRY1_ACCESS__KEY__ID=key_id1
CHE_DOCKER_REGISTRY_AWS_REGISTRY1_SECRET__ACCESS__KEY=secret1
</code></pre>
</div>
<p>There are different configurations for AWS EC2 and the Docker regsitry. You can define as many different registries as you’d like, using the numerical indicator in the environment variable. In case of adding several registries just copy set of properties and append <code class="highlighter-rouge">REGISTRY[n]</code> for each variable.</p>
<h3 id="pulling-private-images-in-stacks">Pulling Private Images in Stacks</h3>
<p>Once you have configured private registry access, any Che stack that has a <code class="highlighter-rouge">FROM &lt;registry&gt;/&lt;repository&gt;</code> that requires authenticated access will use the provided credentials within <code class="highlighter-rouge">che.env</code> to access the registry.</p>
<div class="language-text highlighter-rouge"><pre class="highlight"><code># Syntax
FROM &lt;repository&gt;/&lt;image&gt;:&lt;tag&gt;
# Example:
FROM my.registry.url:9000/image:latest
</code></pre>
</div>
<h2 id="workspace-snapshots">Workspace Snapshots</h2>
<p>By default any workspace stop event will automatically snapshot the workspace runtime (and all of its images). Anything in your workspace <code class="highlighter-rouge">/project</code> folder will be saved to the data folder you mounted into the Che container (see <a href="#logs-and-user-data">“Logs and User Data”</a> for more information). We then use Docker to snapshot the remaining contents of the workspace into a Docker image. There is a matching auto-restore configuration item which will automatically restart the workspace from the latest saved Docker image on disk. When the workspace is started, your project files will be re-mounted or re-synced into <code class="highlighter-rouge">/projects</code>.</p>
<p>You can configure auto-snapshot and auto-restore behaviors by modifiyng the <a href="../../../docs/setup/configuration/index.html#internal-configuration"><code class="highlighter-rouge">che.env</code> file</a>:</p>
<div class="language-shell highlighter-rouge"><pre class="highlight"><code><span class="c"># During the stop of the workspace automatically creates a snapshot if the value is {true},</span>
<span class="c"># Otherwise just stops the workspace.</span>
<span class="nv">CHE_WORKSPACE_AUTO__SNAPSHOT</span><span class="o">=</span><span class="nb">false</span>
<span class="c"># During the start of the workspace automatically restore it from a snapshot if the value is {true},</span>
<span class="c"># Otherwise create a new workspace.</span>
<span class="nv">CHE_WORKSPACE_AUTO__RESTORE</span><span class="o">=</span><span class="nb">false</span>
</code></pre>
</div>
<h3 id="save-workspace-snapshots-in-a-private-registry">Save Workspace Snapshots in a Private Registry</h3>
<p>The default configuration for workspace snapshots is to have them written to disk as TAR files. This is faster, but not centralized. You can have workspace snapshots saved in a private registry instead. In <code class="highlighter-rouge">che.env</code>:</p>
<div class="highlighter-rouge"><pre class="highlight"><code>CHE_DOCKER_REGISTRY__FOR__SNAPSHOTS=true
CHE_DOCKER_REGISTRY=&lt;registry-url&gt;
</code></pre>
</div>
<h3 id="managing-snapshots-in-registries">Managing Snapshots in Registries</h3>
<p>Che marks old snapshots for deletion from the registry by deleting the snapshot manifests which reference the image layers. However, the image layers themselves (which consume the disk space) must be removed by the registry itself as part of a garbage collection (it removes layers that have no manifests). Che does not automatically trigger a GC event in the registry because during GC the registry needs to be in read-only mode which could cause new image pushes to fail.</p>
<p>We recommend either triggering the GC manually from time-to-time or when disk space becomes limited and when it’s known that images aren’t being pushed to the registry. Alternatively, registry GCs can be scheduled if there’s a consistent time of day when there’s a low likelihood of pushes to the registry.</p>
<p>To execute the GC in a registry on a host (local or remote):
<code class="highlighter-rouge">bin/registry garbage-collect &lt;/path/to/config.yml&gt;</code></p>
<p>To execute the GC in a registry inside a container:
<code class="highlighter-rouge">docker exec -ti &lt;registry container name/id&gt; bin/registry garbage-collect /etc/docker/registry/config.yml</code></p>
<p>Read more about registries in the <a href="https://docs.docker.com/registry/">Docker documentation</a>.</p>
<h2 id="custom-dockerfiles-and-composefiles-for-workspaces">Custom Dockerfiles and Composefiles for Workspaces</h2>
<p>Within Che, your workspaces are powered by a set of runtime environments. The default runtime is Docker. Typically, admins have pre-built images in a Docker registry which are pulled when the workspace is created. You can optionally provide custom Dockerfiles (or let your users provide their own Dockerfiles), which will dynamically create a workspace image when a user creates a new workspace.</p>
<p>To use your custom Dockerfiles, you can:</p>
<ol>
<li>Create a <a href="../../../docs/devops/runtime-stacks/index.html#custom-stack">custom stack</a>, which includes a <a href="../../../docs/devops/runtime-recipes/index.html">recipe</a> with your Dockerfile.</li>
<li>Or, users can create a custom recipe when creating a workspace that references your registry.</li>
</ol>
<h2 id="privileged-mode">Privileged Mode</h2>
<p>Docker’s privileged mode allows a container to have root-level access to the host from within the container. This enables containers to do more than they normally would, but opens up security risks. You can enable your workspaces to have privileged mode, giving your users root-level access to the host where Che is running (in addition to root access of their workspace). Privileged mode is necessary if you want to enable certain features such as Docker in Docker.</p>
<p>By default, Che workspaces powered by a Docker container are not configured with Docker privileged mode. There are many security risks to activating this feature - please review the various issues with blogs posted online.</p>
<div class="language-shell highlighter-rouge"><pre class="highlight"><code><span class="c"># Update your che.env:</span>
<span class="nv">CHE_DOCKER_PRIVILEGED</span><span class="o">=</span><span class="nb">true</span>
</code></pre>
</div>
<h2 id="mirroring-docker-hub">Mirroring Docker Hub</h2>
<p>If you are running a private registry internally to your company, you can <a href="https://docs.docker.com/registry/recipes/mirror/">optionally mirror Docker Hub</a>. Your private registry will download and cache any images that your users reference from the public Docker Hub. You need to <a href="https://docs.docker.com/registry/recipes/mirror">configure your Docker daemon to make use of mirroring</a>.</p>
<h2 id="using-docker-in-workspaces">Using Docker In Workspaces</h2>
<p>If you’d like your users to work with projects which have their own Docker images and Docker build capabilities inside of their workspace, then you need to configure the workspace to work with Docker. You have three options:</p>
<ol>
<li>Activate Docker’s privileged mode, where your user workspaces have access to the host.
<div class="language-shell highlighter-rouge"><pre class="highlight"><code><span class="c"># Update your codenvy.env to allow all Codenvy workspaces machines/containers privileged rights:</span>
<span class="nv">CHE_DOCKER_PRIVILEGED</span><span class="o">=</span><span class="nb">true</span>;
</code></pre>
</div>
</li>
<li>Configure Che’s workspaces to volume mount the host docker daemon socket file.
<div class="language-shell highlighter-rouge"><pre class="highlight"><code><span class="c"># Update your codenvy.env to allow all Codenvy workspaces to volume mount their host Daemon when starting:</span>
<span class="nv">CHE_WORKSPACE_VOLUME</span><span class="o">=</span>/var/run/docker.sock:/var/run/docker.sock;
</code></pre>
</div>
</li>
<li>Configure Docker daemon to listen to listen to tcp socket and specify <code class="highlighter-rouge">DOCKER_HOST</code> environment variable in workspace machine. Each host environment will have different network topology/configuration so below is only to be used as general example.
Configure your Docker daemon to listen on TCP. First, add the following to your Docker configuration file (on Ubuntu it’s <code class="highlighter-rouge">/etc/default/docker</code> - see the Docker docs for the location for your OS):</li>
</ol>
<p>Second, export <code class="highlighter-rouge">DOCKER_HOST</code> variable in your workspace. You can do this in the terminal or make it permanent by adding <code class="highlighter-rouge">ENV DOCKER_HOST=tcp://$IP:2375</code> to a workspace recipe, where <code class="highlighter-rouge">$IP</code> is your docker daemon machine IP.</p>
<div class="language-shell highlighter-rouge"><pre class="highlight"><code><span class="c"># Listen using the default unix socket, and on specific IP address on host.</span>
<span class="c"># This will vary greatly depending on your host OS.</span>
sudo dockerd -H unix:///var/run/docker.sock -H tcp://0.0.0.0:2375
<span class="c"># Verify that the Docker API is responding at: http://$IP:2375/containers/json</span>
</code></pre>
</div>
<div class="language-shell highlighter-rouge"><pre class="highlight"><code><span class="c"># In workspace machine</span>
docker -H tcp://<span class="nv">$IP</span>:2375 ps
<span class="c"># Shorter form</span>
<span class="nb">export </span><span class="nv">DOCKER_HOST</span><span class="o">=</span><span class="s2">"tcp://</span><span class="nv">$IP</span><span class="s2">:2375"</span>
docker ps
</code></pre>
</div>
<p>These three tactics will allow user workspaces to perform <code class="highlighter-rouge">docker</code> commands from within their workspace to create and work with Docker containers that will be outside the workspace. In other words, this makes your user’s workspace feel like their laptop where they would normally be performing <code class="highlighter-rouge">docker build</code> and <code class="highlighter-rouge">docker run</code> commands.</p>
<p>You will need to make sure that your user’s workspaces are powered from a stack that has Docker installed inside of it. Che’s default Docker recipe images do not have Docker installed, but there is a sample Docker recipe image eclipse/alpine_jdk8 created from our <a href="https://github.com/eclipse/che-dockerfiles/blob/master/recipes/alpine_jdk8/Dockerfile">dockerfile</a> that includes docker which can be used as new stack’s base image. Refer to the [che-in-che tutorial](../../..(../../../docs/tutorials/che-in-che/index.html) for additional information.</p>
<h1 id="development-mode">Development Mode</h1>
<p>You can debug the Che binaries that are running within the Che server. You can debug either the binaries that are included within the <code class="highlighter-rouge">eclipse/che-server</code> image that you download from DockerHub or you can mount a local Che git repository to debug binaries built in a local assembly. By using local binaries, this allows Che developers to perform a rapid edit / build / run cycle without having to rebuild Che’s Docker images.</p>
<p>Dev mode is activated by passing <code class="highlighter-rouge">--debug</code> to any command on the CLI.</p>
<div class="highlighter-rouge"><pre class="highlight"><code># Activate dev mode with embedded binaries
docker run -it --rm -v /var/run/docker.sock:/var/run/docker.sock \
-v &lt;local-path&gt;:/data \
eclipse/che:&lt;version&gt; [COMMAND] --debug
</code></pre>
</div>
<p>You can replace the binaries in your local image with local binaries by volume mounting the Che git repository to <code class="highlighter-rouge">:/repo</code> in your Docker run command.</p>
<div class="highlighter-rouge"><pre class="highlight"><code>docker run -it --rm -v /var/run/docker.sock:/var/run/docker.sock \
-v &lt;local-path&gt;:/data \
-v &lt;local-repo&gt;:/repo \
eclipse/che:&lt;version&gt; [COMMAND] --debug
</code></pre>
</div>
<p>You can also optionally use your local binaries in production mode by volume mounting <code class="highlighter-rouge">:/repo</code> without passing <code class="highlighter-rouge">--debug</code>. There are two locations that files in your Che source repository will be used instead of those in the image:</p>
<ol>
<li>During the <code class="highlighter-rouge">che config</code> phase, the source repository’s <code class="highlighter-rouge">/dockerfiles/init/modules</code> and <code class="highlighter-rouge">/dockerfiles/init/manifests</code> will be used instead of the ones that are included in the <code class="highlighter-rouge">eclipse/che-init</code> container.</li>
<li>During the <code class="highlighter-rouge">che start</code> phase, a local assembly from <code class="highlighter-rouge">assembly/assembly-main/target/</code> is mounted into the <code class="highlighter-rouge">eclipse/che-server</code> runtime container. You must <code class="highlighter-rouge">mvn clean install</code> the <code class="highlighter-rouge">assembly/assembly-main/</code> folder prior to activating development mode.</li>
</ol>
<p>Volume mounting <code class="highlighter-rouge">:/repo</code> will also make use of your repository’s puppet manifests and other files (replacing those that are stored within the CLI’s base image). If you only want to volume mount a new set of assemblies and ignore the other items in a repository, you can do so by volume mounting <code class="highlighter-rouge">:/assembly</code> to a folder that is the base of a binary (we do not yet support volume mounting a <code class="highlighter-rouge">.tgz</code> file).</p>
<div class="highlighter-rouge"><pre class="highlight"><code>docker run -it --rm -v /var/run/docker.sock:/var/run/docker.sock \
-v &lt;local-path&gt;:/data \
-v &lt;local-assembly-folder&gt;:/assembly \
eclipse/che:&lt;version&gt; [COMMAND]
</code></pre>
</div>
<h3 id="debugging-che">Debugging Che</h3>
<p>To activate jpda suspend mode for debugging Che server initialization, in the <code class="highlighter-rouge">che.env</code>:</p>
<div class="highlighter-rouge"><pre class="highlight"><code>CHE_DEBUG_SUSPEND=true
</code></pre>
</div>
<p>To change che debug port, in the <code class="highlighter-rouge">che.env</code>:</p>
<div class="highlighter-rouge"><pre class="highlight"><code>CHE_DEBUG_PORT=8000
</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="current"><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=""><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>