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

# File name containing default stacks definitions
che.stacks.default=${che.home}/stacks/stacks.json

# Folder name where stack images are stored
che.stacks.images.storage=${che.home}/stacks/images\

Templates

Code templates 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.

# Folder that contains JSON files with code templates and samples
project.template_description.location_dir=${che.home}/templates\

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

Accessing Private Images

You can configure Che to access private images in a public or private registry. In the che.env:

# Docker registry configuration.
# Note that you can configure many registries with different names.
TODO: GET THE REGISTRY CONFIG FROM THE FILE

# You can add as many registries as you need, e.g.:
TODO: GET FROM FILE

Private Docker Registries

When creating a workspace, a user must reference a Docker image. The default location for images is located at Docker Hub. However, you can install your own Docker registry and host custom images within your organization.

Some enterprises use a trusted Docker registry to store their Docker images. If you want your workspace stacks and machines to be powered by these images, then you need to configure each registry and the credentialed access. Once these registries are configured, then you can have users or team leaders create stacks that use recipes with Dockerfiles or images using the FROM <your-registry>/<your-repo> syntax.

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.

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

Accessing Images From Private Registries in Stacks

When users create their workspace, they must reference the custom image in your registry. Whether you provide a custom stack, or you have users reference a custom workspace recipe from the dashboard, to access a private registry, you must provide the domain of the private registry in the FROM syntax of any referenced Dockerfiles.

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

# Where repository is the hostname:port of your registry:
FROM my.registry.url:9000/image:latest

TODO: PRIVATE REGISTRY BEFORE PRIVATE IMAGES? SHOULD PRIVATE REGISTRY BE ADDED TO ACCESS TO A PRIVATE IMAGE?

Custom Images in Private Registries

Most admins create a set of custom workspace stacks as Docker images. They have these pre-built to make the workspace boot sequence faster. These custom Docker images can be placed in a private registry. To push your custom image into a private registry, you will need to build it, tag it with the registry repository name, and push it into the registry. When tagging images into a private registry, they are always tagged with the fully qualified hostname of the registry that will host them. So it is not uncommon to see an image named ops.codenvy.org:9000/myimage.

Start Your Own Private Docker Registry

You can launch a private Docker registry with Docker.

# Launches a docker registry instance on port 5000
docker run -d -p 5000:5000 --restart=always --name registry registry:2\

The --restart=always policy causes this container to be started any time a Docker daemon starts. You can change the location of where this registry will save the snapshots. By default images are stored in a registry container (/var/lib/registry). It is possible to mount this directory when starting 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:

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

TODO: GRAB MISSING STUFF FROM README

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

Workspace Snapshots as Docker Images

In the IDE and dashboard, it is possible to snapshot workspace runtimes. Your projects are saved outside the snapshot and then re-mounted into the runtime after it is reactivated from the snapshot.

Che stores snapshots as Docker images. These images can be saved to disk (default) or into a Docker registry. Workspaces that are restarted will automatically use a snapshot as the base image instead of the originating image used to create the runtime. Snapshots let you store internal state, such as contents of a database, which are not part of your project tree.

TODO: UPDATE FOR CHE.ENV

# If false, snapshots are saved to disk.
# If true, snapshots are saved in a Docker registry
machine.docker.snapshot_use_registry=false

# Automatically creates a snapshot when workspace stopped if the value is {true},
# Otherwise, just stops the workspace.
workspace.runtime.auto_snapshot=true

# Automatically restore workspace from snapshot if {true},
# Otherwise, create a workspace from base image.
workspace.runtime.auto_restore=true\

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.

# Check firewall status
sudo ufw status

# Disable firewall
sudo ufw disable

# Allow 8080 port of Che server
sudo ufw allow 8080/tcp\

TODO: UPDATE WITH RUNBOOK INFORMATION FROM CODENVY ON FIREWALL DETECTION

21 KiB Raw Blame History