20 KiB

Raw Blame History

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:

che init to get an initial configuration for a particular version.
Edit che.env with your environment-specific configuration.
Save che.env to version control.
Setup a new folder and copy che.env from version control into the folder you will mount to :/data.
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 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_<name>=<value> 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:

# 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:

/instance/logs/che/2016                 # Server logs
/instance/logs/che/che-machine-logs     # Workspace logs

User data is stored in:

/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:

/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://<your_hostname>/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 <local-path>:/data \
                    -v <local-repo>:/repo \
                       eclipse/che-cli:<version> [COMMAND]

Dev mode will use files from your host repository:

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.
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 <other-syntax-here> -e CHE_HOST=<ip-addr-or-dns> eclipse/che-cli:<version> 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 <registry>/<repository> that requires authenticated access will use the provided credentials within che.env to access the registry.

# Syntax
FROM <repository>/<image>:<tag>

# 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=<registry-url>

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:

Create a custom stack, which includes a recipe with your Dockerfile.
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.

# 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. 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.

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:

Activate Docker's prvileged mode, where your user workspaces have access to the host.
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 <port> 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)

# 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 <port> 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":

In the left pane, right-click Inbound Rules, and then click New Rule in the action pane.
In the Rule Type dialog box, select Port, and then click Next.
In the Protocol and Ports dialog box, select TCP.
Select speicfic local ports, enter the port number to be opened and click Next.
In the Action dialog box, select Allow the Connection, and then click Next.
In the Name dialog box, type a name and description for this rule, and then click Finish.

20 KiB Raw Blame History