This section walks you through the single-user installation of Che on Docker.

Prerequisites

  • Use Docker version 17 or higher. Older versions are untested but may work (1.13 or higher). To install the latest Docker version, see https://docs.docker.com/install/.

    wget -qO- https://get.docker.com/ | sh

  • Operating Systems: Linux, macOS, Windows.

    macOS users must create an IP alias using the sudo ifconfig lo0 alias $IP command. Here, $IP is the IP that you can obtain from Docker for the Mac application from Preferences → Advanced → Docker subnet or by running the following command:

    docker run --rm --net host eclipse/che-ip:6.19.0

  • Minimum one CPU, 2GB of RAM, 3GB disk space.

The default port required to run Che is 8080. When Che starts, it performs a check to verify that the port is available. Pass the -e CHE_PORT=<port> argument in the Docker portion of the start command to change the port that you want Che to start on.

Ports used by Che must be open and must not be blocked by firewalls or other applications already using the same ports.

In this context, we recognize two types of ports:

  • Internal ports: These are ports within a local network, such as when Che is installed on the user’s local desktop or laptop.

  • External ports: These are ports outside a local network, such as when using a remote Che server on a cloud host provider.

All ports are TCP unless otherwise noted.

Port Service Notes

8080

Tomcat Port

Che server default port.

8000

Server Debug Port

Users developing Che extensions and custom assemblies use this debug port to connect a remote debugger to the Che server.

32768-65535

Docker and Che Agents

Users who launch servers in their workspace bind to ephemeral ports in this range. This range can be limited.

Known issues

To view the known issues, search GitHub issues for Che having the kind/bug label.

Following are the two known issues in which features work on Docker 1.13 and higher but do not work on Docker 1.12:

Fedora and RHEL or CentOS users may encounter issues with SElinux. To fix the issue, disable SElinux using the setenforce 0 command. If using the latest Docker version and disabling SElinux does not fix the issue, file a ticket on the issues page.

Quickstart

To start Che, run the following command where <path> is a local directory:

docker run -it --rm -v /var/run/docker.sock:/var/run/docker.sock -v <path>:/data eclipse/che:6.19.0 start

The following is an example of the output:

$ docker run -ti -v /var/run/docker.sock:/var/run/docker.sock -v ~/Documents/che-data1:/data eclipse/che:6.19.0 start
INFO: (che cli): 6.19.0 - using docker 17.10.0-ce / native
INFO: (che config): Generating che configuration...
INFO: (che config): Customizing docker-compose for running in a container
INFO: (che start): Preflight checks
         mem (1.5 GiB):           [OK]
         disk (100 MB):           [OK]
         port 8080 (http):        [AVAILABLE]
         conn (browser => ws):    [OK]
         conn (server => ws):     [OK]

INFO: (che start): Starting containers...
INFO: (che start): Services booting...
INFO: (che start): Server logs at "docker logs -f che"
INFO: (che start): Booted and reachable
INFO: (che start): Ver: 6.19.0
INFO: (che start): Use: http://172.19.20.180:8080
INFO: (che start): API: http://172.19.20.180:8080/swagger

You can run the docker run -it eclipse/che:6.19.0 start command, which will fail by default. But, it will print options on how to proceed.

eclipse/che is a Docker image that manages the other Docker images and supporting utilities that Che uses during its configuration or operational phases. It is recommended to install Che using the eclipse/che image. To run the che-server image directly, see Run Che-Server directly.

Versions

Each version of Che is available as a Docker image tagged with a label that matches the version, such as eclipse/che:6.0.0. For a list of the available versions, browse Docker Hub.

The following table lists the redirection labels that reference special versions of Che:

Variable Description

nightly

The nightly build.

The software referenced by these labels can change over time. Because Docker will cache images locally, the eclipse/che:<version> image that you are running locally may not be current with the one cached on Docker Hub. Additionally, the eclipse/che:<version> image that you are running references a manifest of Docker images that Che depends upon, which can also change if you are using these special redirection tags.

If you use a CLI version that mismatches with the one that was installed, you will encounter an error.

To avoid issues caused by using the nightly redirections, ensure that you adhere to the following:

  1. Use the docker pull eclipse/che:6.19.0 command to ensure that you have the most recent Docker version.

  2. When using the CLI, commands that use other Docker images have an optional --pull and --force command line option that instructs the CLI to check Docker Hub for a newer version and pull it. Using these flags slows down performance, but it ensures that your local cache is up-to-date.

If you run Che using a tagged version that is not a redirection label, such as 6.0.0, you will not encounter the caching issues because the installed software is tagged and specific to the particular version and does not change over time.

Configuring Che using volume mounts

Use volume mounts to configure certain parts of Che. The presence or absence of certain volume mounts triggers certain behaviors in the system. For example, you can mount a Che source git repository with :/repo to use the Che source code instead of the binaries and the configuration that is shipped with the Docker images.

At a minimum, you must mount a local path to :/data. Che installs its configuration, user data, version, and log information at this location. Che creates a cli.log file in this location to debug unexpected behavior while running the system. You can also create a che.env file in this directory. This file contains all the administrative configurations that you can set or override in a single location.

You can also use volume mounts to override the location of where the user or backup data is stored. By default, these directories are created as sub-directories of the location that you mount to :/data. However, if you do not want the instance/ and backup/ directories to be sub-directories, you can set them individually with separate overrides.

docker run -it --rm -v /var/run/docker.sock:/var/run/docker.sock
                    -v <local-path>:/data
                    -v <a-different-path>:/data/instance
                    -v <another-path>:/data/backup
                       eclipse/che:<version> [COMMAND]
Local Location Container Location Usage

/var/run/docker.sock

/var/run/docker.sock

This is how Che gets access to the Docker daemon. This instructs the container to use your local Docker daemon when Che wants to create its own containers.

/<your-path>/lib

/data/lib

Inside the container, a copy of important libraries that your workspaces will need are made and are placed into the lib/ directory. When Che creates a workspace container, that container uses your local Docker daemon and the Che workspace looks for these libraries in your local lib/ directory. This helps in getting the files from inside the container out on your local host.

/<your-path>/workspaces

/data/workspaces

The location of your workspace and project files.

/<your-path>/storage  

/data/storage  

The location where Che stores the meta information that describes the various workspaces, projects, and user preferences.  

Hosting Che

To host Che on a cloud service like DigitalOcean, AWS, or Scaleways, the CHE_HOST variable must be set to the public IP address of the server or its DNS.

You can automatically set the CHE_HOST variable by running the internal utility docker run --net=host eclipse/che-ip:6.19.0 command. This utility is usually accurate on desktops, but it usually fails on hosted servers. You can explicitly set this value to the IP address of your server:

docker run -it --rm -v /var/run/docker.sock:/var/run/docker.sock
                    -v <local-path>:/data
                    -e CHE_HOST=<your-ip-or-host>
                       eclipse/che:<version> [COMMAND]

Running Che on different ports

Either set the CHE_PORT=$your_port variable in the che.env file or pass it as an environment variable in your docker run syntax: -e CHE_PORT=$your_port.

Running Che as different users

On Linux or macOS, you can run the Eclipse Che container with different user identities. By default, you run the Che container as the root user. You can pass the --user uid:gid or the -e CHE_USER=uid:gid argument as a docker run parameter before the eclipse/che Docker image. The CLI starts the eclipse/che-server image with the same uid:gid combination and mounts the /etc/group and etc/passwd files. When Che is run as a custom user, all files written from within the Che server to the host (such as che.env or cli.log files) are written to the disk with the custom user as the owner of the files. This feature is not available on Windows.

Installing Che when offline

Che supports offline (disconnected from the Internet) installation and operation. This is helpful for restricted environments, regulated datacenters, or offshore installations. The offline installation downloads the CLI, core system images, and any stack images while you are within a network DMZ with Docker Hub access. You can then move those files to a secure environment and start Che.

  1. Save Che images.

    While connected to the Internet, download Che Docker images:

    docker run <docker-goodness> eclipse/che:<version> offline

    The CLI downloads images and saves them to the /backup/*.tar file with each image saved as its own file. You can save these files at a different location by mounting a local directory to the :/data/backup directory. The version tag of the CLI Docker image is used to determine the versions of dependent images that must be downloaded. Approximately, 1 GB of data is saved.

    The default execution does not download any optional stack images that are needed to launch workspaces of a particular type. There are many stacks for different programming languages and some of them are over 1 GB in size.

    For a list of available stack images, run the eclipse/che offline --list command.

    To download a specific stack, run the eclipse/che offline --image:<image-name> command. You can use the --image flag repeatedly on a single command line.

  2. Start Che in offline mode.

    Place the TAR files in a directory in the offline computer. If the files are placed in a directory named /tmp/offline/, run Che in offline mode using the following command:

    # Load the CLI
docker load < /tmp/offline/eclipse_che:<version>.tar

# Start Che in offline mode
docker run <other-properties> -v /tmp/offline:/data/backup eclipse/che:<version> start --offline

    The --offline parameter instructs the Che CLI to load all the TAR files located in the directory mounted to the /data/backup/ directory. These images are then used instead of routing to the Internet to check for Docker Hub. The preboot sequence takes place before any CLI functions use the Docker daemon. The eclipse/che start, eclipse/che download, and eclipse/che init commands support the --offline parameter, which triggers this preboot sequence.

Upgrading Che

You can upgrade Che by downloading a eclipse/che-cli:<version> image that is newer than the version that you currently have installed. For a list of available versions that you can upgrade to, run the eclipse/che-cli version command .

Example

To upgrade to 6.0.1 from 6.0.0:

  1. Get the new version of Che: docker pull eclipse/che-cli:6.0.0.

    You now have two eclipse/che-cli images (one for each version).

  2. Use the new image to upgrade the old installation: docker run <volume-mounts> eclipse/che-cli:6.0.1 upgrade.

    The upgrade command has numerous checks to prevent you from upgrading Che if the new image and the old one are not compatible. For the upgrade procedure to advance, the CLI image must be newer than the one in the /instance/che.ver file.

The upgrade command performs the following steps in the background:

  1. Performs a version compatibility check.

  2. Downloads the new Docker images that are needed to run the new version of Che.

  3. If it is running, stops Che .

  4. Triggers a maintenance window.

  5. Backs up your installation.

  6. Initializes the new version.

  7. Starts Che.

To save the stacks packaged into the new binaries in the database, set the CHE_PREDEFINED_STACKS_RELOADONSTART variable to true.

Backing up your Che installation

  • To create a copy of relevant configuration information, user data, projects, and workspaces, run the che backup command. The che backup command does not save workspace snaphots.

  • To recover Che from a particular backup snapshot, run the che restore command. The backup is saved as a TAR file that you can keep in your records. You can then use the che restore command to recover your user data and configuration.

Configuration

Che CLI supports configuring the port, hostname, OAuth, Docker, Git, and resolving networking issues. For details, see Che configuration on Docker.

Running Che without the CLI

You can run the Che server directly by launching a Docker image. This approach bypasses the CLI that has additional utilities to simplify administration and operation. The eclipse/che-server Docker image is appropriate for running Che within clusters, orchestrators, or by third-party tools with automation.

To run Che directly by launching a Docker image, take the following steps:

  1. Run the latest released version of Che 6.x: 6.19.0.

  2. Replace <LOCAL_PATH> with any host directory. Che places the backup files (configurable properties, workspaces, lib, storage) in this directory.

    docker run -p 8080:8080 \
           --name che \
           --rm \
           -v /var/run/docker.sock:/var/run/docker.sock \
           -v <LOCAL_PATH>:/data \
           eclipse/che-server:6.19.0

The following is a selection of commands:

  • To run the nightly version of Che, replace eclipse/che-server:6.19.0 with eclipse/che-server:nightly.

  • To run a specific tagged version of Che, replace eclipse/che-server:6.19.0 with eclipse/che-server:<_version_>.

  • To stop the container running Che, use the docker stop che command.

  • To restart the container running Che and restart the Che server, use the docker restart che command.

  • To upgrade to a newer version, use the following commands in order:

    docker pull eclipse/che-server:6.19.0
docker restart che

The Server startup in # ms message confirms that Che has started. After starting, Che is available at localhost:8080 or at a remote IP if you started Che remotely.

Running Che on SELinux

If SELinux is enabled, run the following command instead of the preceding one:

# Run the latest released version of Che
docker run -p 8080:8080 \
           --name che \
           -v /var/run/docker.sock:/var/run/docker.sock \
           -v <LOCAL_PATH>:/data:Z \
           --security-opt label:disable \
           eclipse/che-server:6.19.0

Running Che on ports

Tomcat inside the container will bind itself to port 8080 by default. You must map this port to be exposed in your container using the -p 8080:8080 parameter. If you want to change the port to which your browsers connect, change the first value, such as -p 9000:8080. This routes requests from port 9000 to the internal Tomcat bound to port 8080. To change the internal port that Tomcat is bound to, you must update the port binding and set the CHE_PORT variable to the new value.

docker run -p 9000:9500 \
           --name che \
           -e CHE_PORT=9500 \
           -v /var/run/docker.sock:/var/run/docker.sock \
           -v <LOCAL_PATH>:/data \
           eclipse/che-server:6.19.0

Configuring properties

The most important configuration properties are defined as environment variables that you can pass to the container. For example, to have Che listen on port 9000:

docker run -p:9000:9000 \
           --name che \
           -e CHE_SERVER_ACTION=stop \
           -v /var/run/docker.sock:/var/run/docker.sock \
           -v <LOCAL_PATH>:/data \
           eclipse/che-server:6.19.0

The following table contains a list of variables that can be set.

Variable Description Default Values

CHE_SERVER_ACTION

The command to send to Tomcat. It can be run, start , stop.

run

CHE_ASSEMBLY

The path to a Che assembly that is on your host to be used instead of the assembly packaged within the che-server image. If you set this variable, you must also volume mount the same directory to /home/user/che

/home/user/che

CHE_IN_VM

Set to true if this container is running inside a VM providing Docker such as boot2docker, Docker for Mac, or Docker for Windows. This is auto-detected in most situations, but it is not always perfect.

auto-detection

CHE_LOG_LEVEL

Logging level of output for Che server. Can be debug or info.

info

CHE_HOST

IP address/hostname that the Che server will bind to. Used by browsers to contact workspaces. You must set this IP address if you want to bind the Che server to an external IP address that is not the same as Docker’s.

The IP address set to the Docker host. This covers 99% of situations, but on rare occassions this IP address is not discovered and you must provide it.

CHE_DEBUG_SERVER

If true, it will launch the Che server with JPDA activated so that a Java debugger can attach to the Che server for debugging plugins, extensions, and core libraries.

false

CHE_DEBUG_SERVER_PORT

The port that the JPDA debugger will listen.

8000

CHE_DEBUG_SERVER_SUSPEND

If true, then activates the JPDA_SUSPEND flag for Tomcat running the Che server. Used for advanced internal debugging of extensions.

false

CHE_PORT

The port that the Che server will bind itself to within the Che container.

8080

For a list of environment variables, see che.env.

You can create a file with the environment variables that you want to pass to the che-server image:

docker run -p:8080:8080 \
           --name che \
           -v /var/run/docker.sock:/var/run/docker.sock \
           -v <LOCAL_PATH>:/data \
           --env-file /home/user/che.env \
           eclipse/che-server:6.19.0

Running Che on a public IP address

To connect the remote browser clients to the Che server (as opposed to the local browser clients) and override the defaults that are detected, set the CHE_IP variable to the Docker host IP address that will have requests forwarded to the che-server container.

Run an auto-detection algorithm within the che-server container to determine this IP.

  • Docker is running on the boot2docker tool, this is usually the eth1 interface.

  • You are running Docker for Windows or Docker for macOS, this is usually the eth0 interface.

  • You are running Docker natively on Linux, this is the docker0 interface.

To allow access of the remote clients to this container when your host that is running Docker has its IP 10.0.75.4:

docker run -p:8080:8080 \
           --name che \
           -e CHE_HOST=10.0.75.4 \
           -v /var/run/docker.sock:/var/run/docker.sock \
           -v <LOCAL_PATH>:/data \
           eclipse/che-server:6.19.0

Running Che as a daemon

Pass the --restart always parameter to the docker command syntax to have the Docker daemon restart the container on any exit event, including when your host is initially booting. You can also run Che in the background with the -d option.

docker run -p:8080:8080 \
           --name che \
           --restart always \
           -e CHE_HOST=10.0.75.4 \
           -v /var/run/docker.sock:/var/run/docker.sock \
           -v <LOCAL_PATH>:/data \
           eclipse/che-server:6.19.0

Running Che with Docker Compose

che:
   image: eclipse/che-server:6.19.0
   port: 8080:8080
   restart: always
   volumes:
     - /var/run/docker.sock:/var/run/docker.sock
     - <LOCAL_PATH>:/data
   container_name: che

  1. Save this in a file named Composefile.

  2. Run this with Docker Compose using the docker-compose -f Composefile -d --env-file=che.env command.

    The Environment file must contain the following required environment variable:

    # $IP is a public IP of your server
CHE_HOST=$IP
Tags: installation docker