--- tags: [ "eclipse" , "che" ] title: Configuration excerpt: "Configure Eclipse Che to bend to your will..." layout: docs permalink: /:categories/configuration/ --- Configuration is handled by modifying `che.env` placed in the host folder volume mounted to `:/data`. This configuration file is generated during the `che init` phase. If you rerun `che init` in an already initialized folder, the process will abort unless you pass `--force`, `--pull`, or `--reinit`. 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 `che config` to apply this configuration to your system. `che start` also reapplies the latest configuration. You can run `che init` to install a new configuration into an empty directory. This command uses the `che/init:` Docker container to deliver a version-specific set of puppet templates into the folder. If you run `che config`, che runs puppet to transform your puppet templates into a che instance configuration, placing the results into `/che/instance` if you volume mounted that, or into a `instance` subdirectory of the path you mounted to `/che`. Each time you start che, `che config` is run to ensure instance configuration files are properly generated and consistent with the configuration you have specified in `che.env`. # Saving Configuration in Version Control Administration teams that want to version control your che configuration should save `che.env`. 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 `che upgrade` we may replace these files with templates that are specific to the version that is being upgraded. The `che.env` file maintains fidelity between versions and we can generate instance configurations from that. The version control sequence would be: 1. `che init` to get an initial configuration for a particular version. 2. Edit `che.env` with your environment-specific configuration. 3. Save `che.env` to version control. 4. Setup a new folder and copy `che.env` from version control into the folder you will mount to `:/data`. 5. Run `che config` or `che start`. # Internal Configuration We provide a complete list of user-configurable properties in the `che.env` file. However, there are additional internal Che server properties that can also be configured. When we start the `che-server` Docker container, it is configured with a `che.properties` file to define a variety of internal operational details. You can [view the default file](https://github.com/eclipse/che/blob/08344fe62ebedfaa199e3258279b29acec7c88f8/assembly/assembly-wsmaster-war/src/main/webapp/WEB-INF/classes/codenvy/che.properties) in our GitHub repo. You can override these properties or pass in new Che server properties by defining additional environment variables within `che.env`. The CLI will convert any `che.env` additional properties into custom `che.properties` that are passed into the server. Any variable with the format `CHE_PROPERTY_=` will be configured into property value. A single underscore `_` will be converted into a period `.`. A double underscore `__` will be converted into a single underscore `_`. For example: ```shell # This environment variable: CHE_PROPERTY_machine_ws__agent_max__start__time__ms=1000 # Is sent to the Che server as: machine.ws_agent.max_start_time_ms=1000 ``` # Logs and User Data When Che initializes itself, it stores logs, user data, database data, and instance-specific configuration in the folder mounted to `:/data/instance` or an `instance` subfolder of what you mounted to `:/data`. Che's containers save their logs in the same location: ```shell /instance/logs/che/2016 # Server logs /instance/logs/che/che-machine-logs # Workspace logs ``` User data is stored in: ```shell /instance/data/che # Project backups (we synchronize projs from remote ws here) ``` 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: ```shell /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 contianer /instance/config # Configuration files for Che which are volume mounted into containers ``` # oAuth You can configure Google, GitHub, Microsoft, BitBucket, or WSO2 oAuth for use when users perform git operations. Che is shipped with a preconfigured GitHub oAuth application for the `che.onprem` hostname. To enable GitHub oAuth, add `che_HOST=che.onprem` to `che.env` 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 `http:///api/oauth/callback`. You will receive from GitHub a client ID and secret, which must be added to `che.env`: ``` CHE_GITHUB_CLIENT_ID=yourID CHE_GITHUB_SECRET=yourSecret ``` Google oAuth (and others) are configured the same: ``` CHE_GOOGLE_CLIENT_ID=yourID CHE_GOOGLE_SECRET=yourSecret ``` #### GitHub oAuth Refer to [GitHub using OAuth]() for configuration information. #### GitLab oAuth Refer to [GitHub using OAuth]() for configuration information. # Stacks [Stacks]() define the recipes used to create workspace runtimes. They appear in the stack library of the dashboard. You can create your own. TODO: UPDATE THIS ONE: WHERE ARE STACKS DEFINED FOR CONFIGURATION PURPOSES WITH NEW CLI? TWO: LINK TO DOC ON ADDING OR REMOVING # Sample Projects Code [sampes]() 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. TODO: UPDATE THIS FOR THE NEW LOCATION WITH THE CLI ON HOW TO ADD # Development Mode For che developers that are building and customizing che from its source repository, you can run che in development mode where your local assembly is used instead of the one that is provided in the default containers downloaded from DockerHub. This allows for a rapid edit / build / run cycle. Dev mode is activated by volume mounting the che git repository to `:/repo` in your Docker run command. ``` docker run -it --rm -v /var/run/docker.sock:/var/run/docker.sock \ -v :/data \ -v :/repo \ eclipse/che-cli: [COMMAND] ``` Dev mode will use files from your host repository: 1. During the `che config` phase, the source repository's `/dockerfiles/init/modules` and `/dockerfiles/init/manifests` will be used instead of the ones that are included in the `eclipse/che-init` container. 2. During the `che start` phase, a local assembly from `assembly/assembly-main/target/` is mounted into the `eclipse/che-server` runtime container. You must `mvn clean install` the `assembly/assembly-main/` folder prior to activating development mode. To activate jpda suspend mode for debugging Che server initialization, in the `che.env`: ``` CHE_DEBUG_SUSPEND=true ``` To change che debug port, in the `che.env`: ``` CHE_DEBUG_PORT=8000 ``` # Hostname 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 `che.env` and restart Che, or you can pass it during initialization: ``` docker run -e CHE_HOST= eclipse/che-cli: start ``` # Workspace Limits 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. See "Workspace Limits" in `che.env`. 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. # Docker Eclipse Che workspace runtimes are powered by one or more Docker containers. When a user creates a workpace, they do so from a [stack]() 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. ### Private Images 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. 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. In `che.env`: ``` 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 ``` 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 `REGISTRY[n]` for each variable. #### Pulling Private Images in Stacks Once you have configured private registry access, any Che stack that has a `FROM /` that requires authenticated access will use the provided credentials within `che.env` to access the registry. ```text # Syntax FROM /: # Example: FROM my.registry.url:9000/image:latest ``` ### Using Snapshots with Private Registries You can configure Che to save your workspace snapshots to a private registry that you have installed, such as JFrog's Artifactory or Docker's Enterprise Registry. The default configuration of workspace snapshots is to save to local disk. #### Save Workspace Snapshots in a Private Registry 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. In `che.env`: ``` CHE_DOCKER_REGISTRY__FOR__SNAPSHOTS=true CHE_DOCKER_REGISTRY= ``` ### Custom Dockerfiles and Composefiles for Workspaces Within Che, your workspaces are powered by a set of runtime environments. The default runtime is Docker. Typically, admins have pre-built images in DockerHub or another 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. To use your custom Dockerfiles, you can: 1. Create a [custom stack](), which includes a [recipe]() with your Dockerfile. 2. Or, users can create a custom recipe when creating a workspace that references your registry. ### Privileged Mode 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. 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. ```shell # Update your che.env: CHE_DOCKER_PRIVILEGED_MODE=true ``` ### Mirroring Docker Hub If you are running a private registry internally to your company, you can [optionally mirror Docker Hub](https://docs.docker.com/registry/mirror/). Your private registry will download and cache any images that your users reference from the public Docker Hub. You need to [configure your Docker daemon to make use of mirroring](https://docs.docker.com/registry/mirror/). ### Using Docker In Workspaces 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 two options: 1. Activate Docker's prvileged mode, where your user workspaces have access to the host. 2. Configure Che to setup workspaces to volume mount your host Daemon These two tactics will allow user workspaces to perform `docker` 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 `docker build` and `docker run` commands. 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 images do not have Docker installed, but we have sample stacks (see the Che in Che stack). # Networking 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. 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. 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. Generally, if your browser, Che server and Che workspace are all on the same node, then `localhost` configuration will always work. ### WebSockets 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. ### Topology 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. TODO: UPDATE WITH ACCURANTE IMAGE ![Capture_.PNG]({{ base }}/assets/imgs/Capture_.PNG) ### Connectivity The browser client initiates communication with the Che server by connecting to `che-ip`. This IP address must be accessible by your browser clients. Internally, Che runs on Tomcat which is bound to port `8080`. This port can be altered by setting `CHE_PORT` during start or in your `che.env`.\ When a user creates a workspace, the Che server connects to the Docker daemon at `docker-ip` 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, `workspace-ip`. The `workspace-ip` must also be reachable by your browser host. 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. ### Docker Connectivity 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. TODO: LINK TO DOCKER DOCS ON SETTING TCP VS UNIX FOR A DAEMON ### Workspace Port Exposure Inside your user's workspace containers, Che launches microservices on port `4401` and `4403`. We also launch SSH agents on port `22`. The bash terminal accessible in the workspace is also launched as an agent in the workspace on port `4411`. Custom stacks (configured in the dashboard) may expose additional services on different ports. Docker uses ephemeral port mapping. The ports accessible to your clients start at port `32768` 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. Additionally, if services are started within the workspace that expose their own ports, then those ports need to have an `EXPOSE ` 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 `80` and `8080` within the container for any users that want to launch services on those ports. ### Firewalls 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. 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. #### Running Behind a Firewall (Linux/Mac) ```shell # Check to see if firewall is running: systemctl status firewalld # Check for list of open ports # Verify that ports 8080tcp, 7946tcp/udp, 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 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 ``` #### Running Che Behind a Firewall (Windows) 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": 1. In the left pane, right-click `Inbound Rules`, and then click `New Rule` in the action pane. 2. In the `Rule Type` dialog box, select `Port`, and then click `Next`. 3. In the `Protocol and Ports` dialog box, select `TCP`. 4. Select speicfic local ports, enter the port number to be opened and click `Next`. 5. In the `Action` dialog box, select `Allow the Connection`, and then click `Next`. 6. In the `Name` dialog box, type a name and description for this rule, and then click `Finish`.