Google Git
Sign in
eclipse / gerrit / www.eclipse.org / che / 1425b370a4da0c59ea8e10af63c7459f270f6da6 / . / docs / docker-config.html
blob: 04e71052835fe3a0996c13bec0216353e69d670c [file] [log] [blame]
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="description" content="">
<meta name="keywords" content="installationdocker, docker, configuration">
<title>Configuration&#58 Docker | Eclipse Che Documentation</title>
<link rel="stylesheet" href="css/syntax.css">
<link rel="stylesheet" type="text/css" href="https://maxcdn.bootstrapcdn.com/font-awesome/4.7.0/css/font-awesome.min.css" crossorigin="anonymous">
<!--<link rel="stylesheet" type="text/css" href="css/bootstrap.min.css">-->
<link rel="stylesheet" href="css/modern-business.css">
<!-- Latest compiled and minified CSS -->
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css" integrity="sha384-BVYiiSIFeK1dGmJRAkycuHAHRg32OmUcww7on3RYdg4Va+PmSTsz/K68vbdEjh4u" crossorigin="anonymous">
<link rel="stylesheet" href="css/customstyles.css">
<link rel="stylesheet" href="css/boxshadowproperties.css">
<!-- most color styles are extracted out to here -->
<link rel="stylesheet" href="css/theme-che.css">
<link rel="stylesheet" href="/css/coderay.css" media="screen" type="text/css">
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/2.1.4/jquery.min.js" crossorigin="anonymous"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery-cookie/1.4.1/jquery.cookie.min.js" crossorigin="anonymous"></script>
<script src="js/jquery.navgoco.min.js"></script>
<!-- Latest compiled and minified JavaScript -->
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/js/bootstrap.min.js" integrity="sha384-Tc5IQib027qvyjSMfHjOMaLkfuWVxZxUPnCJA7l2mCWNIpG9mGCD8wGNIcPD7Txa" crossorigin="anonymous"></script>
<!-- Anchor.js -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/anchor-js/2.0.0/anchor.min.js" crossorigin="anonymous"></script>
<script src="js/toc.js"></script>
<script src="js/customscripts.js"></script>
<link rel="shortcut icon" href="che/docs/images/favicon.ico">
<!-- HTML5 Shim and Respond.js IE8 support of HTML5 elements and media queries -->
<!-- WARNING: Respond.js doesn't work if you view the page via file:// -->
<!--[if lt IE 9]>
<script src="https://oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
<script src="https://oss.maxcdn.com/libs/respond.js/1.4.2/respond.min.js"></script>
<![endif]-->
<link rel="alternate" type="application/rss+xml" title="che" href="http://0.0.0.0:4000/feed.xml">
<script>
$(document).ready(function() {
// Initialize navgoco with default options
$("#mysidebar").navgoco({
caretHtml: '',
accordion: true,
openClass: 'active', // open
save: false, // leave false or nav highlighting doesn't work right
cookie: {
name: 'navgoco',
expires: false,
path: '/'
},
slide: {
duration: 400,
easing: 'swing'
}
});
$("#collapseAll").click(function(e) {
e.preventDefault();
$("#mysidebar").navgoco('toggle', false);
});
$("#expandAll").click(function(e) {
e.preventDefault();
$("#mysidebar").navgoco('toggle', true);
});
});
</script>
<script>
$(function () {
$('[data-toggle="tooltip"]').tooltip()
})
</script>
<script>
$(document).ready(function() {
$("#tg-sb-link").click(function() {
$("#tg-sb-sidebar").toggle();
$("#tg-sb-content").toggleClass('col-md-9');
$("#tg-sb-content").toggleClass('col-md-12');
$("#tg-sb-icon").toggleClass('fa-toggle-on');
$("#tg-sb-icon").toggleClass('fa-toggle-off');
});
});
</script>
</head>
<body>
<!-- Navigation -->
<nav class="navbar navbar-inverse navbar-static-top">
<div class="container topnavlinks">
<div class="navbar-header">
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target="#bs-example-navbar-collapse-1">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="fa fa-home fa-lg navbar-brand" href="index.html">&nbsp;<span class="projectTitle"> Eclipse Che Documentation</span></a>
</div>
<div class="collapse navbar-collapse" id="bs-example-navbar-collapse-1">
<ul class="nav navbar-nav navbar-right">
<!-- toggle sidebar button -->
<li><a id="tg-sb-link" href="#"><i id="tg-sb-icon" class="fa fa-toggle-on"></i> Nav</a></li>
<!-- entries without drop-downs appear here -->
<li><a href="https://medium.com/eclipse-che-blog/" target="_blank">Blog</a></li>
<li><a href="https://github.com/eclipse/che" target="_blank">Source Code</a></li>
<!-- entries with drop-downs appear here -->
<!-- conditional logic to control which topnav appears for the audience defined in the configuration file.-->
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Get Support<b class="caret"></b></a>
<ul class="dropdown-menu">
<li><a href="https://github.com/eclipse/che/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Akind%2Fbug" target="_blank">Known Bugs</a></li>
<li><a href="https://github.com/eclipse/che/issues/new" target="_blank">File an Issue</a></li>
<li><a href="https://stackoverflow.com/questions/tagged/eclipse-che" target="_blank">Che on StackOverflow</a></li>
</ul>
</li>
<!--
<li>
<a class="email" title="Submit feedback" href="#" onclick="javascript:window.location='mailto:?subject= feedback&body=I have some feedback about the Configuration&#58 Docker page: ' + window.location.href;"><i class="fa fa-envelope-o"></i> Feedback</a>
</li>
-->
<!--comment out this block if you want to hide search-->
<li>
<!--start search-->
<div id="search-demo-container">
<input type="text" id="search-input" placeholder="search...">
<ul id="results-container"></ul>
</div>
<script src="js/jekyll-search.js" type="text/javascript"></script>
<script type="text/javascript">
SimpleJekyllSearch.init({
searchInput: document.getElementById('search-input'),
resultsContainer: document.getElementById('results-container'),
dataSource: 'search.json',
searchResultTemplate: '<li><a href="{url}" title="Configuration&amp;#58 Docker">{title}</a></li>',
noResultsText: 'No results found.',
limit: 10,
fuzzy: true,
})
</script>
<!--end search-->
</li>
</ul>
</div>
</div>
<!-- /.container -->
</nav>
<!-- Page Content -->
<div class="container">
<div id="main">
<!-- Content Row -->
<div class="row">
<!-- Sidebar Column -->
<div class="col-md-3" id="tg-sb-sidebar">
<ul id="mysidebar" class="nav">
<li class="sidebarTitle"> </li>
<li>
<a href="#">Overview</a>
<ul>
<li><a href="index.html">Introduction</a></li>
<li><a href="quick-start.html">Getting Started</a></li>
<li><a href="single-multi-user.html">Single and Multi-User Flavors</a></li>
<li><a href="infra-support.html">Supported Infrastructures</a></li>
</ul>
</li>
<li>
<a href="#">Che on Docker</a>
<ul>
<li><a href="docker-single-user.html">Docker - Single User</a></li>
<li><a href="docker-multi-user.html">Docker - Multi User</a></li>
<li class="active"><a href="docker-config.html">Docker - Configuration</a></li>
<li><a href="docker-cli.html">Docker - CLI Reference</a></li>
</ul>
</li>
<li>
<a href="#">Che on Kubernetes</a>
<ul>
<li><a href="kubernetes-single-user.html">Kubernetes - Single User</a></li>
<li><a href="kubernetes-multi-user.html">Kubernetes - Multi User</a></li>
<li><a href="kubernetes-config.html">Kubernetes - Configuration</a></li>
<li><a href="kubernetes-admin-guide.html">Kubernetes - Admin Guide</a></li>
</ul>
</li>
<li>
<a href="#">Che on OpenShift</a>
<ul>
<li><a href="openshift-single-user.html">OpenShift - Single User</a></li>
<li><a href="openshift-multi-user.html">OpenShift - Multi User</a></li>
<li><a href="openshift-config.html">OpenShift - Configuration</a></li>
<li><a href="openshift-admin-guide.html">OpenShift - Admin Guide</a></li>
</ul>
</li>
<li>
<a href="#">User Management</a>
<ul>
<li><a href="user-management.html">Authentication and Authorization</a></li>
<li><a href="authentication.html">Security Model</a></li>
<li><a href="permissions.html">Permissions</a></li>
<li><a href="organizations.html">Organizations in UD</a></li>
<li><a href="resource-management.html">Resource Management</a></li>
</ul>
</li>
<li>
<a href="#">User Guides</a>
<ul>
<li><a href="creating-starting-workspaces.html">Creating and starting Workspaces</a></li>
<li><a href="ide-projects.html">Projects</a></li>
<li><a href="editor-code-assistance.html">Editor and Code-Assistance</a></li>
<li><a href="dependency-management.html">Dependency Management</a></li>
<li><a href="commands-ide-macro.html">Commands and IDE Macros</a></li>
<li><a href="version-control.html">Version Control</a></li>
<li><a href="debug.html">Debug</a></li>
</ul>
</li>
<li>
<a href="#">Workspace Administration</a>
<ul>
<li><a href="what-are-workspaces.html">Workspace Overview</a></li>
<li><a href="stacks.html">Workspace - Stacks</a></li>
<li><a href="recipes.html">Workspace - Recipes</a></li>
<li><a href="servers.html">Workspace - Servers</a></li>
<li><a href="installers.html">Workspace - Installers</a></li>
<li><a href="volumes.html">Workspace - Volumes Mount</a></li>
<li><a href="env-variables.html">Workspace - Environment Variables</a></li>
<li><a href="projects.html">Workspace - Projects</a></li>
<li><a href="workspaces-troubleshooting.html">Workspace - Troubleshooting</a></li>
<li><a href="workspace-data-model.html">Workspace Data Model</a></li>
</ul>
</li>
<li>
<a href="#">Portable Workspaces</a>
<ul>
<li><a href="chedir-getting-started.html">Chedir - Getting Started</a></li>
<li><a href="why-chedir.html">Chedir - Why Chedir?</a></li>
<li><a href="chedir-installation.html">Chedir - Installation</a></li>
<li><a href="chedir-project-setup.html">Chedir - Project Setup</a></li>
<li><a href="chedir-up-and-down.html">Chedir - Up and Down</a></li>
<li><a href="chefile.html">Chedir - Chefile</a></li>
<li><a href="chedir-ssh.html">Chedir - SSH</a></li>
<li><a href="factories-getting-started.html">Factory - Getting Started</a></li>
<li><a href="creating-factories.html">Factory - Creating</a></li>
<li><a href="factories_json_reference.html">Factory - JSON Reference</a></li>
</ul>
</li>
<li>
<a href="#">Developer Guides</a>
<ul>
<li><a href="framework-overview.html">Overview</a></li>
<li><a href="rest-api.html">SDK - REST API</a></li>
<li><a href="che-in-che-quickstart.html">SDK - Your First Plugin</a></li>
<li><a href="build-reqs.html">SDK - Building Che</a></li>
<li><a href="assemblies.html">SDK - Assemblies</a></li>
<li><a href="logging.html">SDK - Logging</a></li>
<li><a href="ide-extensions-gwt.html">SDK - GWT IDE Extensions</a></li>
<li><a href="server-side-extensions.html">SDK - Server Side Extensions</a></li>
<li><a href="custom-installers.html">SDK - Installers</a></li>
<li><a href="project-types.html">SDK - Project Types</a></li>
<li><a href="language-servers.html">SDK - Language Support</a></li>
<li><a href="parts.html">IDE UI&#58 Parts</a></li>
<li><a href="actions.html">IDE UI&#58 Actions</a></li>
</ul>
</li>
<li>
<a href="#">Dev Essentials</a>
<ul>
<li><a href="guice.html">Dependency Injection</a></li>
<li><a href="dto.html">Transport&#58 DTO</a></li>
<li><a href="json-rpc.html">Communication&#58 JSON-RPC</a></li>
<li><a href="handling-projects-in-plugins.html">Handling Projects in Plugins</a></li>
<li><a href="dao.html">Persistence, DAO</a></li>
<li><a href="properties.html">Properties</a></li>
</ul>
</li>
<li>
<a href="#">Infrastructure and SPI</a>
<ul>
<li><a href="spi_overview.html">Overview</a></li>
<li><a href="spi-implementation.html">Implementation Notes</a></li>
</ul>
</li>
<!-- if you aren't using the accordion, uncomment this block:
<p class="external">
<a href="#" id="collapseAll">Collapse All</a> | <a href="#" id="expandAll">Expand All</a>
</p>
-->
</ul>
<!-- this highlights the active parent class in the navgoco sidebar. this is critical so that the parent expands when you're viewing a page. This must appear below the sidebar code above. Otherwise, if placed inside customscripts.js, the script runs before the sidebar code runs and the class never gets inserted.-->
<script>$("li.active").parents('li').toggleClass("active");</script>
</div>
<!-- Content Column -->
<div class="col-md-9" id="tg-sb-content">
<div class="post-header">
<h1 class="post-title-main">Configuration&#58 Docker</h1>
</div>
<div class="post-content">
<!-- this handles the automatic toc. use ## for subheads to auto-generate the on-page minitoc. if you use html tags, you must supply an ID for the heading element in order for it to appear in the minitoc. -->
<script>
$( document ).ready(function() {
// Handler for .ready() called.
$('#toc').toc({ minimumHeaders: 0, listType: 'ul', showSpeed: 0, headers: 'h2' });
/* this offset helps account for the space taken up by the floating toolbar. */
$('#toc').on('click', 'a', function() {
var target = $(this.getAttribute('href'))
, scroll_target = target.offset().top
$(window).scrollTop(scroll_target - 10);
return false
})
});
</script>
<div id="toc"></div>
<!--
-->
<div class="paragraph">
<p>Configuration is handled by modifying <a href="https://github.com/eclipse/che/blob/master/dockerfiles/init/manifests/che.env">che.env</a> placed in the root of a host folder volume mounted to <code>:/data</code>. This configuration file is generated during the <code>che init</code> phase. If you rerun <code>che init</code> in an already initialized folder, the process will abort unless you pass <code>--force</code>, <code>--pull</code>, or <code>--reinit</code>.</p>
</div>
<div class="paragraph">
<p>You can also pass an environment variable directly in docker run syntax: <code>-e CHE_ENV_NAME=value</code>.</p>
</div>
<div class="paragraph">
<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>che config</code> to apply this configuration to your system. <code>che start</code> also reapplies the latest configuration.</p>
</div>
<div class="paragraph">
<p>You can run <code>che init</code> to install a new configuration into an empty directory. This command uses the <code>che/init:&lt;version&gt;</code> Docker container to deliver a version-specific set of puppet templates into the folder.</p>
</div>
<div class="paragraph">
<p>If you run <code>che config</code>, che runs puppet to transform your puppet templates into a che instance configuration, placing the results into <code>/che/instance</code> if you volume mounted that, or into a <code>instance</code> subdirectory of the path you mounted to <code>/che</code>. Each time you start che, <code>che config</code> is run to ensure instance configuration files are properly generated and consistent with the configuration you have specified in <code>che.env</code>.</p>
</div>
<div class="paragraph">
<p>Administration teams that want to version control your che configuration should save <code>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 strategy were to perform a <code>che upgrade</code> we may replace these files with templates that are specific to the version that is being upgraded. The <code>che.env</code> file maintains fidelity between versions and we can generate instance configurations from that.</p>
</div>
<div class="paragraph">
<p>The version control sequence would be:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p><code>che init</code> to get an initial configuration for a particular version.</p>
</li>
<li>
<p>Edit <code>che.env</code> with your environment-specific configuration.</p>
</li>
<li>
<p>Save <code>che.env</code> to version control.</p>
</li>
<li>
<p>Setup a new folder and copy <code>che.env</code> from version control into the folder you will mount to <code>:/data</code>.</p>
</li>
<li>
<p>Run <code>che config</code> or <code>che start</code>.</p>
</li>
</ol>
</div>
<div class="sect1">
<h2 id="single-port-policy">Single Port Policy</h2>
<div class="sectionbody">
<div class="paragraph">
<p>By default, Che lets Docker publish exposed ports in a random manner - Docker chooses available ports from the ephemeral port range to expose workspace <a href="servers.html">servers</a>. This, however, brings in certain network requirements, namely opening the ephemeral port range (and Keycloak port 5050 for multi user Che) to the world.</p>
</div>
<div class="paragraph">
<p>To run Che in a single port mode add <code>-e CHE_SINGLE_PORT=true</code> to your run syntax. In this case, a Traefik container will be used to route traffic through a single port.</p>
</div>
<div class="paragraph">
<p><strong>Wildcard DNS</strong></p>
</div>
<div class="paragraph">
<p>In a single port mode, Che builds URLs of workspace services using the following pattern - <code>serviceName-machineName-ws-ID.IP.wildcardDNSProvider</code>. So, if your external IP is <code>193.12.34.56</code>, URL of a workspace agent will look like <code>wsagent-http-dev-machine-workspace0bcgkgkvsqi31b4u.193.12.34.56.nip.io</code></p>
</div>
<div class="ulist">
<ul>
<li>
<p>by default <a href="http://nip.io/">nip.io</a> is used. This is an external wildcard DNS provider, and if it is down for some reason, networking in single port Che is broken.</p>
</li>
<li>
<p>you can use a different wildcard DNS provider with <code>CHE_SINGLEPORT_WILDCARD__DOMAIN_HOST</code> env.</p>
</li>
<li>
<p>if you don’t want the external IP to be part of the url (<code>serviceName-machineName-ws-ID.wildcardDNSProvider</code>, for example to use a wildcard SSL certificate), you can specify <code>CHE_SINGLEPORT_WILDCARD<em>DOMAIN_IPLESS=true</code> with a custom wildcard DNS (e.g. <code>CHE_SINGLEPORT_WILDCARD</em>DOMAIN_HOST=domain.tld</code>. Be aware that you need to have a matching DNS entry for <code>*.domain.tld</code>. If you are using the multi-user mode, Keycloak will be provided at <code>keycloak.domain.tld</code>.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p><strong>Multi-User Mode</strong></p>
</div>
<div class="paragraph">
<p>Make sure <code>webOrigins</code> and <code>redirectUris</code> in Keycloak client settings (<code>che-public</code> client) reference your <code>CHE_DOCKER_IP_EXTERNAL</code> value, i.e IP that external users will use to log in. Keycloak admin console in multi user Che is available at <code><a href="http://keycloak.$IP.$wildcardDNSProvider:$chePort/auth/" class="bare">http://keycloak.$IP.$wildcardDNSProvider:$chePort/auth/</a></code> where <code>$IP</code> is either your <code>docker0</code> IP or <code>CHE_DOCKER_IP_EXTERNAL</code> value.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="logs-and-user-data">Logs and User Data</h2>
<div class="sectionbody">
<div class="paragraph">
<p>When Che initializes itself, it stores logs, user data, database data, and instance-specific configuration in the folder mounted to <code>:/data/instance</code> or an <code>instance</code> subfolder of what you mounted to <code>:/data</code>.</p>
</div>
<div class="paragraph">
<p>Che’s containers save their logs in the same location:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>/instance/logs/che/2016 # Server logs
/instance/logs/che/che-machine-logs # Workspace logs</pre>
</div>
</div>
<div class="paragraph">
<p>Note there might be cases of logs encoding settings when Che master logs are not stored in the location above.</p>
</div>
<div class="paragraph">
<p>User data is stored in:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>/instance/data/che # Project backups (we synchronize projects from remote ws here)</pre>
</div>
</div>
<div class="paragraph">
<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>
<div class="listingblock">
<div class="content">
<pre>/instance/che.ver.do_not_modify # Version of che installed
/instance/docker-compose-container.yml # Docker compose to launch Che from within a container
/instance/docker-compose.yml # Docker compose to launch Che from the host without container
/instance/config # Configuration files for Che which are volume mounted into containers</pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="jdbc-configuration">JDBC Configuration</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Eclipse Che uses <a href="http://www.h2database.com/html/main.html">H2</a> for single-user builds and PostgreSQL database in a multi-user flavor.</p>
</div>
<div class="paragraph">
<p>Depending on the used database, JDBC Connection pool will be initialized with respective default values. These values can be overridden through che.env.</p>
</div>
<div class="listingblock">
<div class="content">
<pre># Example of configuration for using H2 database (default for single-user Che)
CHE_JDBC_USERNAME=
CHE_JDBC_PASSWORD=
CHE_JDBC_DATABASE=jdbc:h2:che
CHE_JDBC_URL=jdbc:postgresql://postgres:5432/dbche
CHE_JDBC_DRIVER__CLASS__NAME=org.h2.Driver
CHE_JDBC_MAX__TOTAL=8
CHE_JDBC_MAX__IDLE=2
CHE_JDBC_MAX__WAIT__MILLIS=-1</pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre># Example of configuration for using PostgreSQL database (default for multi-user Che)
CHE_JDBC_USERNAME=pgche
CHE_JDBC_PASSWORD=pgchepassword
CHE_JDBC_DATABASE=dbche
CHE_JDBC_URL=jdbc:postgresql://postgres:5432/dbche
CHE_JDBC_DRIVER__CLASS__NAME=org.postgresql.Driver
CHE_JDBC_MAX__TOTAL=20
CHE_JDBC_MAX__IDLE=10
CHE_JDBC_MAX__WAIT__MILLIS=-1</pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="oauth">oAuth</h2>
<div class="sectionbody">
<div class="paragraph">
<p>You can configure Google, GitHub, Microsoft or BitBucket oAuth for use when users perform git operations. See: <a href="version-control.html#github-oauth">Version Control</a></p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="stacks-and-samples">Stacks and Samples</h2>
<div class="sectionbody">
<div class="paragraph">
<p><a href="stacks.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>
</div>
<div class="paragraph">
<p><code>CHE_PREDEFINED_STACKS_RELOAD<em>ON</em>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>
</div>
<div class="paragraph">
<p>Code samples 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. In your <code>${LOCAL_DATA_DIR}/instance/data/templates</code> create a json file with your custom samples - it will be sourced each time Che server starts. Here’s how default <a href="https://github.com/eclipse/che/blob/master/ide/che-core-ide-templates/src/main/resources/samples.json">Che samples.json</a> look like.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="workspace-limits">Workspace Limits</h2>
<div class="sectionbody">
<div class="paragraph">
<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>
</div>
<div class="paragraph">
<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>
</div>
<div class="paragraph">
<p>Workspace idle timeout can be configured in <code>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>
</div>
</div>
</div>
<div class="sect1">
<h2 id="java_opts">JAVA_OPTS</h2>
<div class="sectionbody">
<div class="paragraph">
<p>There can be several Java processes running in a workspace machine. Some of the Java agents are special purpose agents started in a machine to provide core and additional IDE functionality. These are workspace agent and a <a href="dependency-management.html">Maven plugin</a> that are both started in own JVM. On top of that, you can run own Java programs and use build tools like Maven. A set of the following environment variables can help optimize RAM consumption:</p>
</div>
<div class="paragraph">
<p><strong>User-Defined Envs</strong></p>
</div>
<div class="paragraph">
<p>A user can provide own <a href="env-variables.html">environment variables</a> per workspace machine:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>JAVA_OPTS # machine-wide java opts
MAVEN_OPTS # machine-wide maven opts
CHE_WORKSPACE_WSAGENT__JAVA__OPTIONS # java opts to adjust java opts of ws-agent
CHE_WORKSPACE_MAVEN__SERVER__JAVA__OPTIONS # java opts to adjust java opts of the maven server</pre>
</div>
</div>
<div class="paragraph">
<p>Che admins (basically whoever has access to <code>che.env</code> or Che server environment directly) can override user-defined envs:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>CHE_WORKSPACE_JAVA__OPTIONS # overrides the default value of JAVA_OPTS of all workspaces
CHE_WORKSPACE_MAVEN__OPTIONS # overrides the default value of MAVEN_OPTS of all workspaces
CHE_WORKSPACE_WSAGENT__JAVA__OPTIONS # overrides the default value of JAVA_OPTS of all ws-agents
CHE_WORKSPACE_MAVEN__SERVER__JAVA__OPTIONS # overrides the default value of JAVA_OPTS of all maven servers</pre>
</div>
</div>
<div class="paragraph">
<p>You can find default values in <a href="https://github.com/eclipse/che/blob/master/dockerfiles/init/manifests/che.env#L127-L141">che.env</a>.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="hostname">Hostname</h2>
<div class="sectionbody">
<div class="paragraph">
<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>che.env</code> and restart Che, or you can pass it during initialization:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>docker run &lt;OTHER-DOCKER_OPTIONS&gt; -e CHE_HOST=&lt;ip-addr-or-dns&gt; eclipse/che:&lt;version&gt; start</pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="networking">Networking</h2>
<div class="sectionbody">
<div class="paragraph">
<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>
</div>
<div class="paragraph">
<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>
</div>
<div class="paragraph">
<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>
</div>
<div class="paragraph">
<p>Generally, if your browser, Che server and Che workspace are all on the same node, then <code>localhost</code> configuration will always work.</p>
</div>
<div class="paragraph">
<p><strong>WebSockets</strong></p>
</div>
<div class="paragraph">
<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>
</div>
<div class="paragraph">
<p><strong>Topology</strong></p>
</div>
<div class="paragraph">
<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 cotainers, "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>
</div>
<div class="paragraph">
<p><strong>Connectivity</strong></p>
</div>
<div class="paragraph">
<p>The browser client initiates communication with the Che server by connecting to <code>che-ip</code>. This IP address must be accessible by your browser clients. Internally, Che runs on Tomcat which is bound to port <code>8080</code>. This port can be altered by setting <code>CHE_PORT</code> during start or in your <code>che.env</code>.</p>
</div>
<div class="paragraph">
<p>When a user creates a workspace, the Che server connects to the Docker daemon at <code>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>workspace-container-ip</code>. The <code>workspace-container-ip</code> isn’t usually reachable by your browser host, <code>docker-ip</code> will be used to establish the connections between the browser and workspace containers.</p>
</div>
<div class="paragraph">
<p>Che server will provide workspace containers with following environment variables:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>CHE_API_INTERNAL</code>, points to the internal API endpoint, that is accessible across other machines within the workspace. Value is taken from Che server <code>CHE_INFRA_DOCKER_MASTER<em>API</em>ENDPOINT</code> variable, which can be initialized either by CLI or default value from <code>che.properties</code>.</p>
</li>
<li>
<p><code>CHE_API_EXTERNAL</code>, points to the external API endpoint, that is used by browser clients. Value is taken from Che server <code>CHE_API</code> variable. It’s default value is defined in <code>che.properties</code>.</p>
</li>
<li>
<p><code>CHE_API</code> will point to the same value as <code>CHE_API_INTERNAL</code> for backward compatibility (will be removed in the future).</p>
</li>
</ul>
</div>
<div class="paragraph">
<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>
<div class="listingblock">
<div class="content">
<pre># Browser --&gt; Che Server
# 1. Default is '${CHE_HOST}:${SERVER_PORT}/wsmaster/api'. In fact, requests are sent to whatever IP/hostname is in your browser address bar
# 2. Else use the value of che.api
#
# Che Server --&gt; Docker Daemon Progression:
# 1. Use the value of che.infra.docker.daemon_url
# 2. Else, use the value of DOCKER_HOST system variable
# 3. Else, use Unix socket over unix:///var/run/docker.sock
# 4. Else default docker0 IP - 172.17.42.1
#
# Che Server --&gt; Workspace Connection:
# 1. Use the value of che.docker.ip
# 2. Else, use address of docker0 bridge network, if available
#
# Browser --&gt; Workspace Connection:
# 1. Use the value of che.docker.ip.external
# 2. Else, use che.docker.ip value
# 3. Else use value provided by ws container inspect
#
# Workspace Agent --&gt; Che Server
# 1. If set, use value of CHE_INFRA_DOCKER_MASTER__API__ENDPOINT
# 2. Default is 'http://che-host:${SERVER_PORT}/api', where 'che-host' is IP of docker0 (linux) VM IP (Mac and Win).</pre>
</div>
</div>
<div class="paragraph">
<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>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>localhost</code> is not an acceptable domain for communications, but the IP address <code>10.0.75.2</code> is.</p>
</div>
<div class="listingblock">
<div class="content">
<pre>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</pre>
</div>
</div>
<div class="paragraph">
<p>You can also perform additional tests yourself against an already-running Che server. You will need to use <code>docker ps</code> and <code>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>
<div class="listingblock">
<div class="content">
<pre># 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/</pre>
</div>
</div>
<div class="paragraph">
<p><strong>DNS Resolution</strong></p>
</div>
<div class="paragraph">
<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>CHE_DNS_RESOLVERS</code> in the <code>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>
<div class="listingblock">
<div class="content">
<pre># Update your che.env with comma separated list of resolvers:
CHE_DNS_RESOLVERS=10.10.10.10,8.8.8.8</pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="single-port-routing">Single-Port Routing</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Currently not supported in Che 6.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="private-images">Private Images</h2>
<div class="sectionbody">
<div class="paragraph">
<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>
</div>
<div class="paragraph">
<p>If your stack images that Che wants to pull require authenticated access to any registry then you must configure registry authentication.</p>
</div>
<div class="paragraph">
<p>In <code>che.env</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>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</pre>
</div>
</div>
<div class="paragraph">
<p>There are different configurations for AWS EC2 and the Docker registry. 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>REGISTRY[n]</code> for each variable.</p>
</div>
<div class="paragraph">
<p><strong>Pulling Private Images in Stacks</strong></p>
</div>
<div class="paragraph">
<p>Once you have configured private registry access, any Che stack that has a <code>FROM &lt;registry&gt;/&lt;repository&gt;</code> that requires authenticated access will use the provided credentials within <code>che.env</code> to access the registry.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="text"># Syntax
FROM &lt;repository&gt;/&lt;image&gt;:&lt;tag&gt;
# Example:
FROM my.registry.url:9000/image:latest</code></pre>
</div>
</div>
<div class="paragraph">
<p>Read more about registries in the <a href="https://docs.docker.com/registry/">Docker documentation</a>.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="privileged-mode">Privileged Mode</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Docker 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>
</div>
<div class="paragraph">
<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>
<div class="listingblock">
<div class="content">
<pre># Update your che.env:
CHE_DOCKER_PRIVILEGED=true</pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="mirroring-docker-hub">Mirroring Docker Hub</h2>
<div class="sectionbody">
<div class="paragraph">
<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>
</div>
</div>
</div>
<div class="sect1">
<h2 id="using-docker-in-workspaces">Using Docker In Workspaces</h2>
<div class="sectionbody">
<div class="paragraph">
<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>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Activate Docker privileged mode, where your user workspaces have access to the host.</p>
</li>
</ol>
</div>
<div class="listingblock">
<div class="content">
<pre># Update your codenvy.env to allow all Che workspaces machines/containers privileged rights:
CHE_DOCKER_PRIVILEGED=true;</pre>
</div>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Configure Che workspaces to volume mount the host docker daemon socket file.</p>
</li>
</ol>
</div>
<div class="listingblock">
<div class="content">
<pre># Update your codenvy.env to allow all Che workspaces to volume mount their host Daemon when starting:
CHE_WORKSPACE_VOLUME=/var/run/docker.sock:/var/run/docker.sock;</pre>
</div>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Configure Docker daemon to listen to listen to tcp socket and specify <code>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>/etc/default/docker</code> - see the Docker docs for the location for your OS):</p>
</li>
</ol>
</div>
<div class="paragraph">
<p>Second, export <code>DOCKER_HOST</code> variable in your workspace. You can do this in the terminal or make it permanent by adding <code>ENV DOCKER_HOST=tcp://$IP:2375</code> to a workspace recipe, where <code>$IP</code> is your docker daemon machine IP.</p>
</div>
<div class="listingblock">
<div class="content">
<pre># Listen using the default unix socket, and on specific IP address on host.
# This will vary greatly depending on your host OS.
sudo dockerd -H unix:///var/run/docker.sock -H tcp://0.0.0.0:2375
# Verify that the Docker API is responding at: http://$IP:2375/containers/json</pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre># In workspace machine
docker -H tcp://$IP:2375 ps
# Shorter form
export DOCKER_HOST="tcp://$IP:2375"
docker ps</pre>
</div>
</div>
<div class="paragraph">
<p>These three tactics will allow user workspaces to perform <code>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>docker build</code> and <code>docker run</code> commands.</p>
</div>
<div class="paragraph">
<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 default Docker recipe images do not have Docker installed, but you can build own image though [TODO: link to custom stack authoring].</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="development-mode">Development Mode</h2>
<div class="sectionbody">
<div class="paragraph">
<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>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>
</div>
<div class="paragraph">
<p>Dev mode is activated by passing <code>--debug</code> to any command on the CLI.</p>
</div>
<div class="listingblock">
<div class="content">
<pre># 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</pre>
</div>
</div>
<div class="paragraph">
<p>You can replace the binaries in your local image with local binaries by volume mounting the Che git repository to <code>:/repo</code> in your Docker run command.</p>
</div>
<div class="listingblock">
<div class="content">
<pre>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</pre>
</div>
</div>
<div class="paragraph">
<p>You can also optionally use your local binaries in production mode by volume mounting <code>:/repo</code> without passing <code>--debug</code>. There are two locations that files in your Che source repository will be used instead of those in the image:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>During the <code>che config</code> phase, the source repository’s <code>/dockerfiles/init/modules</code> and <code>/dockerfiles/init/manifests</code> will be used instead of the ones that are included in the <code>eclipse/che-init</code> container.</p>
</li>
<li>
<p>During the <code>che start</code> phase, a local assembly from <code>assembly/assembly-main/target/</code> is mounted into the <code>eclipse/che-server</code> runtime container. You must <code>mvn clean install</code> the <code>assembly/assembly-main/</code> folder prior to activating development mode.</p>
</li>
</ol>
</div>
<div class="paragraph">
<p>Volume mounting <code>:/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>:/assembly</code> to a folder that is the base of a binary (we do not yet support volume mounting a <code>.tgz</code> file).</p>
</div>
<div class="listingblock">
<div class="content">
<pre>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]</pre>
</div>
</div>
<div class="paragraph">
<p>To activate jpda suspend mode for debugging Che server initialization, in the <code>che.env</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>CHE_DEBUG_SUSPEND=true</pre>
</div>
</div>
<div class="paragraph">
<p>To change che debug port, in the <code>che.env</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>CHE_DEBUG_PORT=8000</pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="production-mode">Production Mode</h2>
<div class="sectionbody">
<div class="paragraph">
<p>You can also build own <code>INIT</code> and <code>SERVER</code> images to have custom configuration and binaries. To do so, clone <a href="https://github.com/eclipse/che">Che repo</a> and copy <code>dockerfiles</code> dir to the root of your custom assembly. If your custom Che server does not need any custom configuration, you may proceed to building Che server image by executing <code>dockerfiles/build.sh</code>. Once done, tag the resulted image the way you need. If your custom Che server requires custom configuration, and you want to let users override them in <code>che.env</code>, you will need to build own init image with a custom <a href="https://github.com/eclipse/che/blob/master/dockerfiles/init/manifests/che.env">che.env</a> file.</p>
</div>
<div class="paragraph">
<p>Once done, you can start your custom binaries this way:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>docker run -ti -v '/var/run/docker.sock:/var/run/docker.sock -v /local/data/path:/data -e "IMAGE_CHE=your/che-server" -e "IMAGE_INIT=your/init-image" eclipse/che:$tag start'</pre>
</div>
</div>
<div class="paragraph">
<p><code>IMAGE_CHE</code> is the image you have built in <code>dockerfiles/che</code>, and <code>IMAGE_INIT</code> is the one from <code>dockerfiles/init</code>.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="docker-unix-socket-mounting-vs-tcp-mode">Docker Unix Socket Mounting vs TCP Mode</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The <code>-v /var/run/docker.sock:/var/run/docker.sock</code> syntax is for mounting a Unix socket so that when a process inside the container speaks to a Docker daemon, the process is redirected to the same socket on the host system.</p>
</div>
<div class="paragraph">
<p>However, peculiarities of file systems and permissions may make it impossible to invoke Docker processes from inside a container. If this happens, the Che startup scripts will print an error about not being able to reach the Docker daemon with guidance on how to resolve the issue.</p>
</div>
<div class="paragraph">
<p>An alternative solution is to run Docker daemon in TCP mode on the host and export <code>DOCKER_HOST</code> environment variable in the container. You can tell the Docker daemon to listen on both Unix sockets and TCP. On the host running the Docker daemon:</p>
</div>
<div class="listingblock">
<div class="content">
<pre># Set this environment variable and restart the Docker daemon
DOCKER_OPTS=" -H tcp://0.0.0.0:2375 -H unix:///var/run/docker.sock"
# Verify that the Docker API is responding at:
http://localhost:2375/info</pre>
</div>
</div>
<div class="paragraph">
<p>Having verified that your Docker daemon is listening, run the Che container with the with <code>DOCKER_HOST</code> environment variable set to the IP address of <code>docker0</code> or <code>eth0</code> network interface. If <code>docker0</code> is running on 1.1.1.1 then:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>docker run -ti -e DOCKER_HOST=tcp://1.1.1.1:2375 -v /var/run/docker.sock:/var/run/docker.sock -v ~/Documents/che-data1:/data eclipse/che start</pre>
</div>
</div>
<div class="paragraph">
<p>Alternatively, you can save this env in <code>che.env</code> and restart Che.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="proxiesfirewallsports">Proxies/Firewalls/Ports</h2>
<div class="sectionbody">
<div class="paragraph">
<p>You can install and operate Che behind a proxy:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Configure each physical node’s Docker daemon with proxy access.</p>
</li>
<li>
<p>Optionally, override workspace proxy settings for users if you want to restrict their Internet access.</p>
</li>
</ol>
</div>
<div class="paragraph">
<p>Before starting Che, configure <a href="https://docs.docker.com/engine/admin/systemd/#/http-proxy">Docker’s daemon for proxy access</a>. If you have Docker for Windows or Docker for Mac installed on your desktop and installing Che, these utilities have a GUI in their settings which let you set the proxy settings directly.</p>
</div>
<div class="paragraph">
<p>Please be mindful that your <code>HTTP_PROXY</code> and/or <code>HTTPS_PROXY</code> that you set in the Docker daemon must have a protocol and port number. Proxy configuration is quite finnicky, so please be mindful of providing a fully qualified proxy location.</p>
</div>
<div class="paragraph">
<p>If you configure <code>HTTP_PROXY</code> or <code>HTTPS_PROXY</code> in your Docker daemon, we will add <code>localhost,127.0.0.1,CHE_HOST</code> to your <code>NO_PROXY</code> value where <code>CHE_HOST</code> is the DNS or IP address. We recommend that you add the short and long form DNS entry to your Docker’s <code>NO_PROXY</code> setting if it is not already set.</p>
</div>
<div class="paragraph">
<p>We will add some values to <code>che.env</code> that contain some proxy overrides. You can optionally modify these with overrides:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>CHE_HTTP_PROXY=&lt;YOUR_PROXY_FROM_DOCKER&gt;
CHE_HTTPS_PROXY=&lt;YOUR_PROXY_FROM_DOCKER&gt;
CHE_NO_PROXY=localhost,127.0.0.1,&lt;YOUR_CHE_HOST&gt;
CHE_HTTP_PROXY_FOR_WORKSPACES=&lt;YOUR_PROXY_FROM_DOCKER&gt;
CHE_HTTPS_PROXY_FOR_WORKSPACES=&lt;YOUR_PROXY_FROM_DOCKER&gt;
CHE_NO_PROXY_FOR_WORKSPACES=localhost,127.0.0.1,&lt;YOUR_CHE_HOST&gt;</pre>
</div>
</div>
<div class="paragraph">
<p>The last three entries are injected into workspaces created by your users. This gives your users access to the Internet from within their workspaces. You can comment out these entries to disable access. However, if that access is turned off, then the default templates with source code will fail to be created in workspaces as those projects are cloned from GitHub.com. Your workspaces are still functional, we just prevent the template cloning.</p>
</div>
<div class="paragraph">
<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>
</div>
<div class="paragraph">
<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>
</div>
<div class="paragraph">
<p><strong>Running Behind a Firewall (Linux/Mac)</strong></p>
</div>
<div class="listingblock">
<div class="content">
<pre># Check to see if firewall is running:
systemctl status firewalld
# Check for list of open ports
# Verify that ports 8080tcp, 32768-65535tcp are open
firewall-cmd --list-ports
# Optionally open ports on your local firewall:
firewall-cmd --permanent --add-port=8080/tcp
... and so on
# You can also verify that ports are open:
nmap -Pn -p &lt;port&gt; localhost
# If the port is closed, then you need to open it by editing /etc/pf.conf.
# For example, open port 1234 for TCP for all interfaces:
pass in proto tcp from any to any port 1234
# And then restart your firewall</pre>
</div>
</div>
<div class="paragraph">
<p><strong>Running Che Behind a Firewall (Windows)</strong></p>
</div>
<div class="paragraph">
<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>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>In the left pane, right-click <code>Inbound Rules</code>, and then click <code>New Rule</code> in the action pane.</p>
</li>
<li>
<p>In the <code>Rule Type</code> dialog box, select <code>Port</code>, and then click <code>Next</code>.</p>
</li>
<li>
<p>In the <code>Protocol and Ports</code> dialog box, select <code>TCP</code>.</p>
</li>
<li>
<p>Select specific local ports, enter the port number to be opened and click <code>Next</code>.</p>
</li>
<li>
<p>In the <code>Action</code> dialog box, select <code>Allow the Connection</code>, and then click <code>Next</code>.</p>
</li>
<li>
<p>In the <code>Name</code> dialog box, type a name and description for this rule, and then click <code>Finish</code>.</p>
</li>
</ol>
</div>
<div class="paragraph">
<p><strong>Limiting Che Ports</strong></p>
</div>
<div class="paragraph">
<p>Eclipse Che uses Docker to power its workspaces. Docker uses the <a href="https://en.wikipedia.org/wiki/Ephemeral_port">ephemeral port range</a> when exposing ports for services running in the container. So when a Tomcat server is started on port 8080 inside a Che workspace Docker automatically selects an available port from the ephemeral range at runtime to map to that Tomcat instance.</p>
</div>
<div class="paragraph">
<p>Docker will select its ports from anywhere in the ephemeral range. If you wish to reduce the size of the ephemeral range in order to improve security you can do so, however, keep in mind that each Che workspace will use at least 2 ports plus whatever ports are required for the services the user adds to their workspace.</p>
</div>
<div class="paragraph">
<p>Limiting the ephemeral range can only be done at the host level - you can read more about it (and some of the risks in doing so) here: <a href="http://www.ncftp.com/ncftpd/doc/misc/ephemeral_ports.html" class="bare">http://www.ncftp.com/ncftpd/doc/misc/ephemeral_ports.html</a></p>
</div>
<div class="paragraph">
<p>To change the ephemeral range:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>On Linux: <a href="http://www.ncftp.com/ncftpd/doc/misc/ephemeral_ports.html#Linux" class="bare">http://www.ncftp.com/ncftpd/doc/misc/ephemeral_ports.html#Linux</a></p>
</li>
<li>
<p>On Windows: <a href="http://www.ncftp.com/ncftpd/doc/misc/ephemeral_ports.html#Windows" class="bare">http://www.ncftp.com/ncftpd/doc/misc/ephemeral_ports.html#Windows</a></p>
</li>
</ul>
</div>
</div>
</div>
<div class="tags">
<b>Tags: </b>
<a href="tag_installation.html" class="btn btn-default navbar-btn cursorNorm" role="button">installation</a>
<a href="tag_docker.html" class="btn btn-default navbar-btn cursorNorm" role="button">docker</a>
</div>
<!--
-->
</div>
<hr class="shaded"/>
<footer>
<div class="row">
<div class="col-lg-12 footer">
Eclipse Che - Documentation <br/>
Site last generated: Sep 13, 2018 <br/>
<hr>
<a href="http://www.eclipse.org" target="_blank">Eclipse Foundation</a><br/>
<a href="http://www.eclipse.org/legal/privacy.php" target="_blank">Privacy Policy</a><br/>
<a href="http://www.eclipse.org/legal/termsofuse.php" target="_blank">Terms of Use</a><br/>
<a href="https://www.eclipse.org/legal/epl-2.0/" target="_blank">Eclipse Public License</a><br/>
<a href="http://www.eclipse.org/legal" target="_blank">Legal Resources</a><br/>
</div>
</div>
</footer>
<!-- /.row -->
</div>
<!-- /.container -->
</div>
<!-- /#main -->
</div>
</body>
</html>