diff --git a/assembly/assembly-wsmaster-war/src/main/webapp/WEB-INF/classes/che_aliases.properties b/assembly/assembly-wsmaster-war/src/main/webapp/WEB-INF/classes/che_aliases.properties index 5c4f0f6da0..055ea34566 100644 --- a/assembly/assembly-wsmaster-war/src/main/webapp/WEB-INF/classes/che_aliases.properties +++ b/assembly/assembly-wsmaster-war/src/main/webapp/WEB-INF/classes/che_aliases.properties @@ -58,3 +58,5 @@ che.docker.api=docker.api.version che.docker.tcp_connection_timeout_ms=docker.connection.tcp.connection_timeout_ms che.docker.tcp_connection_read_timeout_ms=docker.connection.tcp.read_timeout_ms che.docker.swap=machine.docker.memory_swap_multiplier +che.docker.daemon_url=docker.client.daemon_url + diff --git a/dockerfiles/init/manifests/che.env b/dockerfiles/init/manifests/che.env index dfcc4d7b84..bf497fa6f5 100644 --- a/dockerfiles/init/manifests/che.env +++ b/dockerfiles/init/manifests/che.env @@ -1,9 +1,9 @@ -############################################################ -##### ##### -##### CHE SYSTEM ##### -##### ##### +######################################################################################## +##### ##### +##### CHE SYSTEM ##### +##### ##### # -# Fundamental parameters that affect the initial system operation. +# Parameters that affect the initial system operation. # # IP address, hostname, or DNS @@ -23,18 +23,18 @@ # configure proxies for Che's internal system services. Third, if you want your users # to access the Internet, then you should also add proxy values for their workspaces. # -# Please be mindful of the proxy URL formatting. Proxies are unforgiving if you do not type -# the URL just right, inclduing the protocol and whether they allow a trailing /. +# Please be mindful of the proxy URL formatting. Proxies are unforgiving if you do not +# type the URL properly, including the protocol and whether they allow a trailing /. #CHE_HTTP_PROXY_FOR_CHE=http://myproxy.com:8001/ #CHE_HTTPS_PROXY_FOR_CHE=http://myproxy.com:8001/ #CHE_NO_PROXY_FOR_CHE= # Proxies for Workspaces -# The proxy values that will be set as environment variables within each user's workspace. -# Set these to allow users Internet access if they are behind a proxy. -#CHE_HTTP_PROXY_FOR_CHE_WORKSPACES=http://myproxy.com:8001/ -#CHE_HTTPS_PROXY_FOR_CHE_WORKSPACES=http://myproxy.com:8001/ -#CHE_NO_PROXY_FOR_CHE_WORKSPACES= +# The proxy values that will be set as environment variables within each user's. +# workspace. Set these to allow users Internet access if they are behind a proxy. +#CHE_WORKSPACE_HTTP__PROXY=http://myproxy.com:8001/ +#CHE_WORKSPACE_HTTPS__PROXY=http://myproxy.com:8001/ +#CHE_WORKSPACE_NO__PROXY= # JPDA # If using Che in development mode, activate this property to enable JPDA @@ -49,58 +49,58 @@ # It should be rare that you would need to change this. #CHE_SERVER_XMX=2048 -############################################################ -##### ##### -##### WORKSPACE CONFIGURATION ##### -##### ##### +######################################################################################## +##### ##### +##### WORKSPACES ##### +##### ##### # -# User workspaces have their own runtimes. Those runtimes can be composed 1..n containers. -# We call each container a 'machine' as it is a dedicated runtime. One of the machines for a -# workspace must be designated as the 'development' machine, which installs Che agents to +# User workspaces have their own runtimes. Those runtimes are composed of 1..n containers. +# We call each container a 'machine' as it is a dedicated runtime. One of the machines for +# a workspace must be designated as the 'development' machine, which installs Che agents to # provide additional services to the user. These parameters configure how Che manages user # machines and the agents that are deployed within them. # -# Since workspaces have their own runtimes, they have separate proxies that do not inherit from -# the system proxies that you have configured for your Docker daemon. +# Since workspaces have their own runtimes, they have separate proxies that do not inherit +# from system proxies that you have configured for your Docker daemon. # -# /etc/hosts for Workspaces -# This will add entries into the user's /etc/hosts file that is running within their workspace. -# You may need to configure this file to give the user access to systems within your network -# or access to the Internet. +# /etc/hosts +# This will add entries into the user's /etc/hosts file that is running within their +# workspace. You may need to configure this to give user's access to systems within +# your network or access to the Internet. #CHE_MACHINE_EXTRA_HOSTS=NULL # Idle Timeout -# The length of time that a user is idel with their workspace when the system will suspend the -# workspace by snapshotting it and then stopping it. Idleness is determined by the length of -# time that the user has not interacted with the workspace, meaning that one of our agents -# has not received instructions. Leaving a browser window open counts as idleness time. +# The system will suspend the workspace and snapshot it if the end user is idle for +# this length of time. Idleness is determined by the length of time that a user has +# not interacted with the workspace, meaning that one of our agents has not received +# instructions. Leaving a browser window open counts as idleness time. #CHE_MACHINE_WS_AGENT_INACTIVE_STOP_TIMEOUT_MS=600000 # Memory -# The recommended RAM size that users will see for their workspace when they create new -# workspaces in the user dashboard. +# The recommended RAM size for new workspaces when created from the dashboard. #CHE_MACHINE_DEFAULT_MEM_SIZE_MB=1024 # Memory Swap -# Adjust machine swap memory by multiplication current machnine memory on provided value. -# default is 0 which means disabled swap, if set multiplier value equal to 0.5 +# Adjust machine swap memory by multiplication current machnine memory on provided +# value. Default is 0 which means disabled swap, if set multiplier value equal to 0.5 # machine swap will be configured with size that equal to half of current machine memory. # It should be rare that you would configure this. See Docker memory swap online # for background. #CHE_MACHINE_DOCKER_MEMORY_SWAP_MULTIPLIER=0 # Host Volume Mounts -# Semicolon separated list of volume mounts. If this is provided, Che will volume mount -# those host folders into each workspace generated by your users. This is a way to allow -# you to provide access to network attached storage that is shared across many workspaces. -#CHE_MACHINE_SERVER_EXTRA_VOLUME=/path/on/host:/path/in/workspace:ro,Z;/path/to/host2:/path/in/workspace2:ro,Z; +# Semicolon separated list of volume mounts. Che will volume mount these host folders +# into each workspace. This is a way to allow you to provide access to NAS shared +# across many workspaces. +#CHE_WORKSPACE_VOLUME=/path/on/host:/path/in/workspace:ro,Z;/path/to/host2:/path/in/workspace2:ro,Z; # Privilged Mode -# Set to `true` if you would like user workspaces to be started with Docker's privileged mode. -# Please be careful when setting this property. This allows user workspaces to gain access to -# the underly host with root privileges. However, privileged mode is needed if users want to -# launch their own Docker containers from within their Docker-powered workspace. -#CHE_MACHINE_DOCKER_PRIVILEGE_MODE=false +# Set to `true` if you would like user workspaces to be started with Docker's +# privileged mode. Please be careful when setting this property. This allows +# user workspaces to gain access to the underly host with root privileges. +# However, privileged mode is needed if users want to launch their own Docker +# containers from within their Docker-powered workspace. +#CHE_DOCKER_PRIVILEGE__MODE=false # Agent Start Timeout # The length of time that a workspace will be allowed to boot before the system terminates the @@ -109,45 +109,137 @@ #CHE_MACHINE_WS_AGENT_MAX_START_TIME_MS=300000 -############################################################ -##### ##### -##### OAUTH CONFIGURATION ##### -##### ##### -# -# You can configure a 3rd party provider's oAuth, which will be used for your users when they -# create accounts and login. There are certain services within Che, such as GitHub -# integration, where GitHub keys are required. oAuth must be configured for those services to work. -# -# Google -#CHE_GOOGLE_CLIENT_ID=your_google_client_id -#CHE_GOOGLE_SECRET=your_google_secret +######################################################################################## +##### ##### +##### NETWORKING ##### +##### ##### +# +# Affects how the Che server connects to the Docker Daemon, how the Che server and +# workspaces establish connections to one another, and also how remote browser clients +# should discover and connect to workspaces. +# +# Che goes through a progression algorithm to establish the protocol, IP address and +# port to establish communications with it is booting or starting a workspace. +# +# Browser --> Che Server +# 1. Default is 'http://localhost:${SERVER_PORT}/wsmaster/api'. +# 2. Else use the value of che.api +# +# Che Server --> Docker Daemon Progression: +# 1. Use the value of che.docker.daemon_url +# 2. Else, use the value of DOCKER_HOST system variable +# 3. Else, use Unix socket over unix:///var/run/docker.sock +# +# Che Server --> Workspace Connection: +# Browser --> Workspace Connection: +# 1. Use the value of che.docker.ip +# 2. Else, if server connects over Unix socket, then use localhost +# 3. Else, use DOCKER_HOST +# +# Workspace Agent --> Che Server +# 1. Default is http://che-host:${SERVER_PORT}/wsmaster/api, where che-host is IP of server. +# 2. Else, use value of che.workspace.che_server_endpoint +# 3. Else, if 'docker0' interface is unreachable, then che-host replaced with +# 172.17.42.1 or 192.168.99.1 +# 4. Else, print connection exception + + +######################################################################################## +##### ##### +##### DOCKER ##### +##### ##### +# +# IP Address +# The IP address of the Docker daemon that is running on your host. We do a +# self-discovery to auto-set this. You can combine this with DOCKER_HOST to change +# communications from socket to TCP. This value will be set to DOCKER_MACHINE_HOST +# env variable for the Che Docker container when it boots - it's how we determine +# what containers will boot. +#CHE_DOCKER_IP=172.17.0.1 + +# External Host Name +# The hostname that a browser should use to connect to a workspace container. +# Only set this if your workspace containers are not directly pingable. This is unusual, +# but happens for example in Docker for Mac when containers are in a VM. +#CHE_DOCKER_IP_EXTERNAL=NULL + +# Docker Host +# How Che will connect to the Docker Host. +#DOCKER_HOST=tcp://localhost:2375 + +# Docker Registry +# Docker is the default machine implementation within Che. Workspaces are powered +# by machines that are constructed when the workspace is started. The images used to +# generate containers for the machines can come from DockerHub or a private +# Docker registry. +# +# You can have an internal registry configured for Che to store images: +#CHE_DOCKER_REGISTRY=${CHE_REGISTRY_HOST}:5000 +# +# You can configure 1..n private registries for Che to connect to when searching +# for Docker images to be used for your workspaces. +#CHE_DOCKER_REGISTRY_AUTH__URL=https://index.docker.io/v1/ +#CHE_DOCKER_REGISTRY_AUTH__USERNAME= +#CHE_DOCKER_REGISTRY_AUTH__URL=https://index.docker.io/v1/ + +# Use Registry For Snapshots? +# Use a Docker registry for workspace snapshots. If false, snaps are saved to disk. +# The namespace is how the snapshots will be organized in the registry. +#CHE_DOCKER_REGISTRY__FOR__SNAPSHOTS=false +#CHE_DOCKER_NAMESPACE=NULL + +# Force Image Update +# If true, then Che always pulls an image from a registry even if it is cached +# If false, Docker only pulls the image if it does not exist locally. This can +# create situations where images are not current, but a forced pull is slower. +#CHE_DOCKER_ALWAYS__PULL__IMAGE=true + +# Control User Processes +# Limits the number of processes that can be forked inside a cgroup. Set -1 for +# unlimited. Requires Docker running on a 4.3 Linux kernel. +#CHE_DOCKER_PIDS__LIMIT=-1 + +# SELinux Options +# By default, your source code is mounted into a workspace into /projects folder. +# On SELinux and other OS, you may need to add additional mounting attributes. +#CHE_DOCKER_VOLUMES__PROJECTS__OPTIONS=Z +#CHE_DOCKER_VOLUMES__AGENT__OPTIONS=ro,Z + +# Docker Network +# Provides a Docker network for the Che server and workspaces to use together. +# Workspace containers created by Che will be added to this Docker network. +# Communications between the Che server and container occur over this network. +#CHE_DOCKER_NETWORK=NULL + +# Docker Cleanup +# Unused containers from Che and workspaces need to be cleaned up periodically. +#CHE_DOCKER_UNUSED__CONTAINERS__CLEANUP__MIN=60 + + + + +######################################################################################## +##### ##### +##### OAUTH ##### +##### ##### +# +# You can configure a 3rd party provider's oAuth, which will be used for your users when +# they initiate Git actions from within Che. +# # GitHub -#CHE_GITHUB_CLIENT_ID=your_github_client_ide -#CHE_GITHUB_SECRET=your_google_secret - -# BitBucket -#CHE_BITBUCKET_CLIENT_ID=your_bitbucket_client_ide -#CHE_BITBUCKET_SECRET=your_bitbucket_secret - -# Microsoft -#CHE_MICROSOFT_CLIENT_ID==your_microsoft_client_ide -#CHE_MICROSOFT_SECRET=your_microsoft_secret - -# WSO2 -#CHE_WSO2_CLIENT_ID=your_wso2_client_ide -#CHE_WSO2_SECRET=your_wso2_secret - -# Project Locker -#CHE_PROJECTLOCKER_CLIENT_ID=your_projectlocker_client_ide -#CHE_PROJECTLOCKER_SECRET=your_projectlocker_secret +#CHE_OAUTH_GITHUB_CLIENTID=your_github_client_ide +#CHE_OAUTH_GITHUB_CLIENTSECRET=your_google_secret +#CHE_OAUTH_GITHUB_AUTHURI=https://github.com/login/oauth/authorize +#CHE_OAUTH_GITHUB_TOKENURI=https://github.com/login/oauth/access_token +#CHE_OAUTH_GITHUB_REDIRECTURIS=http://localhost:${SERVER_PORT}/wsmaster/api/oauth/callback -############################################################ -##### ##### -##### JMX ##### -##### ##### +######################################################################################## +##### ##### +##### JMX ##### +##### ##### # # JMX provides a management interface point to within the Che container. JMX is not # use by other containers such as haproxy or nginx. While Che is running, grab the @@ -157,17 +249,24 @@ #CHE_JMX_PASSWORD=Che -############################################################ -##### ##### -##### DOCKER ##### -##### ##### -# IP Address -# The IP address of the Docker daemon that is running on your host. We do a self-discovery -# to set this. You can combine this with values of DOCKER_HOST to change communications -# from socket to TCP. This value will be set to DOCKER_MACHINE_HOST env variable for -# the Che Docker container when it boots - it's how we determine what containers will boot. -#CHE_DOCKER_IP=172.17.0.1 +######################################################################################## +##### ##### +##### CUSTOM ##### +##### ##### +# Custom che.properties Property +# Che's server loads name=value properties in a .properties file. Those values can +# be seen by custom extensions that are packaged within a Che server. There are +# also Che properties that are rarely configured that are shown in documentation +# that can be added with a custom format here. You can add as many as you would like. +# +# Add a new property in the format of CHE_=value. If in your +# you have a single underscore '_', that will be replaced with a +# dot '.'. A double underscore '__' will be replaced with a single underscore '_'. +# +# For example, CHE_WORKSPACE_AUTO__SNAPSHOT=false will be converted into the Che +# property 'che.workspace.auto_snapshot=false'. +#CHE_WORKSPACE_AUTO__SNAPSHOT=false -# Docker Host -# How Che will connect to the Docker Host. -#DOCKER_HOST=tcp://localhost:2375 \ No newline at end of file +# A complete list of internal properties used by Che are available in the default +# properties file that is embedded in the server's runtime. You can view it in our +# GitHub repository: https://github.com/eclipse/che/blob/master/assembly/assembly-wsmaster-war/src/main/webapp/WEB-INF/classes/codenvy/che.properties \ No newline at end of file diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000000..f30166e825 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,525 @@ +# Eclipse Che Installation and Operation +Eclipse Che is an Eclipse next-generation IDE, developer workspace server, and cloud IDE. + +### Quick Start +With Docker 1.11+ on Windows, Mac, or Linux: +``` +$ docker run eclipse/che-cli start +``` +This command will give you additional instructions on how to run the Che CLI while setting your hostname, configuring volume mounts, and testing your Docker setup. + +### TOC +- [Beta](#beta) +- [Getting Help](#getting-help) +- [Getting Started](#getting-started) +- [System Requirements](#system-requirements) + + [Hardware](#hardware) + + [Software](#software) + + [Sizing](#sizing) +- [Installation](#installation) + + [Linux:](#linux) + + [Mac:](#mac) + + [Windows:](#windows) + + [Verification:](#verification) + + [Proxies](#proxies) + + [Offline Installation](#offline-installation) +- [Usage](#usage) + + [Hosting](#hosting) +- [Uninstall](#uninstall) +- [Configuration](#configuration) + + [Saving Configuration in Version Control](#saving-configuration-in-version-control) + + [Logs and User Data](#logs-and-user-data) + [oAuth](#oauth) + + [LDAP](#ldap) + + [Development Mode](#development-mode) + + [Licensing](#licensing) + + [Hostname](#hostname) + + [HTTP/S](#https) + + [SMTP](#smtp) + + [Workspace Limits](#workspace-limits) + + [Private Docker Registries](#private-docker-registries) +- [Managing](#managing) + + [Scaling](#scaling) + + [Upgrading](#upgrading) + + [Backup (Backup)](#backup-backup) + + [Migration](#migration) + + [Disaster Recovery](#disaster-recovery) +- [CLI Reference](#cli-reference) +- [Architecture](#architecture) +- [Team](#team) + +## Getting Help +If you require immediate help, [Che](http://che.com) provides email and phone support options for Eclipse Che. + +If you run into an issue, please [open a GitHub issue](http://github.com/eclipse/che/issues) providing: +- the host distribution and release version +- output of the `docker version` command +- output of the `docker info` command +- the full Docker run syntax you used for the `che-cli ` +- the output of `cli.log` - see [CLI Reference](#cli-reference) + +## System Requirements +Eclipse Che installs on Linux, Mac and Windows. + +#### Hardware +* 1 core +* 2GB RAM +* 200MB disk space + +Eclipse Che requires 200 MB storage and 1 GB RAM for internal services. The RAM, CPU and storage resources required for your users' workspaces are additive. Che's Docker images consume ~900MB of disk and the Docker images for your workspace templates can each range from 5MB up to 1.5GB. Che and its dependent core containers will consume about 500MB of RAM, and your running workspaces will each require at least 250MB RAM, depending upon user requirements and complexity of the workspace code and intellisense. + +Boot2Docker, docker-machine, Docker for Windows, and Docker for Mac are variations that launch VMs with Docker running in the VM with access to Docker from your host. We recommend increasing your default VM size to at least 4GB. Each of these technologies have different ways to allow host folder mounting into the VM. Please enable this for your OS so that Che data is persisted on your host disk. + +#### Software +* Docker 11.1+ + +The Eclipse Che CLI - a Docker image - manages the other Docker images and supporting utilities that Che uses during its configuration or operations phases. The CLI also provides utilities for downloading an offline bundle to run Che while disconnected from the network. + +Given the nature of the development and release cycle it is important that you have the latest version of Docker installed because any issue that you encounter might have already been fixed with a newer docker release. + +Install the most recent version of Docker Engine for your platform using the [official Docker releases](http://docs.docker.com/engine/installation/), including support for Mac and Windows! If you are on Linux, you can also install using: +```bash +wget -qO- https://get.docker.com/ | sh +``` + +#### Sizing +Che's core services and workspaces run on a common, but single node. + +You need to have enough RAM to support the number of concurrent *running* workspaces. A single user may have multiple running workspaces, but generally the common scenario is a user running a single workspace at a time. Workspace sizes are set by users when they create new workspaces, but you can define workspace limits in the configuration file that prevent RAM sprawl. + +For sizing, determine how much RAM you want each user to consume at a time, and then estimate the peak concurrent utilization to determine how much system-wide RAM you will want. For example, internally at Che, we regularly have 75 concurrently running workspaces, each sized at 16 GB RAM, for a total expectation of 1.2TB of RAM. If you are unable to purchase a single server that supports the maximum RAM that you require, you can consider upgrading to Che, which is an Eclipse Che implementation that supports multiple physical nodes with distributed workspaces. + +Compilation is CPU-heavy and most compilation events are queued to a single CPU. You can assume that the number of cores available to the node that is running Che will determine the maximum amount of parallel compilation activities that occur. + +The default configuration of workspaces is to auto-snapshot the workspace runtime to disk whenever it is stopped, whether by the user or through idle timeout. Many stack base images can grow to be >1GB, especially if you are installing complicated software inside of them, and thus their snapshots can be sizable as well. If you allow users to have many workspaces, even if they are stopped, each of those workspaces will have a snapshot on disk. Che's implementation of Eclipse Che provides system admin limits to cap workspaces, workspaces per user, and RAM for running workspaces. + +## Installation +The Che CLI (a Docker image) is downloaded when you first execute `docker run eclipse/che-cli:` command. The CLI downloads other images that run Eclipse Che and its supporting utilities. The CLI also provides utilities for downloading an offline bundle to run Che while disconnected from a network. + +#### Nightly and Latest +Each version of Che is available as a Docker image tagged with a label that matches the version, such as `eclipse/che-cli:5.0.0-M7`. You can see all versions available by running `docker run eclipse/che-cli version` or by [browsing DockerHub](https://hub.docker.com/r/eclipse/che-cli/tags/). + +We maintain "redirection" labels which reference special versions: + +| Variable | Description | +|----------|-------------| +| `latest` | The most recent stable release. | +| `5.0.0-latest` | The most recent stable release on the 5.x branch. | +| `nightly` | The nightly build. | + +The software referenced by these labels can change over time. Since Docker will cache images locally, the `eclipse/che-cli:` image that you are running locally may not be current with the one cached on DockerHub. Additionally, the `eclipse/che-cli:` 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. + +In the case of 'latest' images, when you initialize an installation using the CLI, we encode your `/instance/che.ver` file with the numbered version that latest references. If you begin using a CLI version that mismatches what was installed, you will be presented with an error. + +To avoid issues that can appear from using 'nightly' or 'latest' redirections, you may: +1. Verify that you have the most recent version with `docker pull eclipse/che-cli:`. +2. When running the CLI, commands that use other Docker images have an optional `--pull` and `--force` command line option which will instruct the CLI to check DockerHub for a newer version and pull it down. Using these flags will slow boot up performance, but ensures that your local cache is current. + +If you are running Che using a tagged version that is a not a redirection label, such as `5.0.0-M7`, then these caching issues will not happen, as the software installed is tagged and specific to that particular version, never changing over time. + +#### Linux: +There is nothing additional you need to install other than Docker. + +#### Mac: +There is nothing additional you need to install other than Docker. + +#### Windows: +There is nothing additional you need to install other than Docker. + +#### Verification: +You can verify that the CLI is working: +``` +docker run eclipse/che-cli +``` +The CLI is bound inside of Docker images that are tagged with different versions. If you were to run `eclipse/che-cli:5.0.0-latest` this will run the latest shipping release of Che and the CLI. This list of all versions available can be seen by running `che-cli version` or browsing the list of [tags available in Docker Hub](https://hub.docker.com/r/eclipse/che-cli/tags/). + +#### Proxies +You can install and operate behind a proxy. There are three parts to configure: +1. Configuring Docker proxy access so that Che can download its images from DockerHub. +2. Configuring Che's system containers so that they can proxy to the Internet. +3. Optionally, configuring workspace proxy settings to allow users within a workspace to proxy to the Internet. + +Before starting Che, configure [Docker's daemon for proxy access](https://docs.docker.com/engine/admin/systemd/#/http-proxy). + +Che's system runs on Java, and the JVM requires proxy environment variables in our `JAVA_OPTS`. We use the JVM for the core Che server and the workspace agents that run within each workspace. TODO: HOW DO YOU CONFIGURE THIS? Please be mindful of the proxy URL formatting. Proxies are unforgiving if do not enter the URL perfectly, inclduing the protocol, port and whether they allow a trailing slash/. + +If you would like your users to have proxified access to the Internet from within their workspace, those workspace runtimes need to have proxy settings applied to their environment variables in their .bashrc or equivalent. TODO: HOW DO YOU CONFIGURE THIS? + +A `NO_PROXY` variable is required if you use a fake local DNS. Java and other internal utilities will avoid accessing a proxy for internal communications when this value is set. + +#### Offline Installation +We support the ability to install and run while disconnected from the Internet. This is helpful for certain restricted environments, regulated datacenters, or offshore installations. + +##### Save Docker Images +While connected to the Internet, download Che's Docker images: +``` +docker run eclipse/che-cli offline +``` +The CLI will download images and save them to `/che/backup/*.tar` with each image saved as its own file. The `/backup` folder will be created as a subdirectory of the folder you volume mounted to `:/che`. You can optionally save these files to a differnet location by volume mounting that folder to `:/backup`. The version tag of the CLI Docker image will be used to determine which versions of dependent images to download. There is about 1GB of data that will be saved. + +##### Save Che CLI +``` +docker save eclipse/che-cli: +``` + +##### Save Che Stacks +Out of the box, Che has configured a few dozen stacks for popular programming languages and frameworks. These stacks use "recipes" which contain links to Docker images that are needed to create workspaces from these stacks. These workspace runtime images are not saved as part of `che-cli offline`. There are many of these images and they consume a lot of disk space. Most users do not require all of these stacks and most replace default stacks with custom stacks using their own Docker images. If you'd like to get the images that are associated with Che's stacks: +``` +docker save > backup/.tar +``` +The list of stack images that you can download are sourced from Eclipse Che's [Dockerfiles repository](https://github.com/eclipse/che-dockerfiles/tree/master/recipes). Each folder is named the same way that our images are stored. The `alpine_jdk8` folder represents the `eclipse/alpine_jdk8` Docker image, which you would save with `docker save eclipse/alpine_jdk8 > backup/alpine_jdk8.tar`. + +##### Start Offline +Extract your files to an offline computer with Docker already configured. Install the CLI files to a directory on your path and ensure that they have execution permissions. Execute the CLI in the directory that has the `offline` sub-folder which contains your tar files. Then start Che in `--offline` mode: +``` +docker run eclipse/che-cli: start --offline +``` +When invoked with the `--offline` parameter, the CLI performs a preboot sequence, which loads all saved `backup/*.tar` images including any stack images you saved. The preboot sequence takes place before any CLI configuration, which itself depends upon Docker. The `che-cli start`, `che-cli download`, and `che-cli init` commands support `--offline` mode which triggers this preboot seequence. + +## Usage +#### Syntax +``` +Usage: docker run -it --rm + -v /var/run/docker.sock:/var/run/docker.sock + -v :/che + ${CHE_MINI_PRODUCT_NAME}/che-cli: [COMMAND] + + help This message + version Installed version and upgrade paths + init Initializes a directory with a ${CHE_MINI_PRODUCT_NAME} install + [--no-force Default - uses cached local Docker images + --pull Checks for newer images from DockerHub + --force Removes all images and re-pulls all images from DockerHub + --offline Uses images saved to disk from the offline command + --accept-license Auto accepts the Che license during installation + --reinit] Reinstalls using existing $CHE_MINI_PRODUCT_NAME.env configuration + start [--pull | --force | --offline] Starts ${CHE_MINI_PRODUCT_NAME} services + stop Stops ${CHE_MINI_PRODUCT_NAME} services + restart [--pull | --force] Restart ${CHE_MINI_PRODUCT_NAME} services + destroy Stops services, and deletes ${CHE_MINI_PRODUCT_NAME} instance data + [--quiet Does not ask for confirmation before destroying instance data + --cli] If :/cli is mounted, will destroy the cli.log + rmi [--quiet] Removes the Docker images for , forcing a repull + config Generates a ${CHE_MINI_PRODUCT_NAME} config from vars; run on any start / restart + add-node Adds a physical node to serve workspaces intto the ${CHE_MINI_PRODUCT_NAME} cluster + remove-node Removes the physical node from the ${CHE_MINI_PRODUCT_NAME} cluster + upgrade Upgrades Che from one version to another with migrations and backups + download [--pull|--force|--offline] Pulls Docker images for the current che-cli version + backup [--quiet | --skip-data] Backups ${CHE_MINI_PRODUCT_NAME} configuration and data to /che/backup volume mount + restore [--quiet] Restores ${CHE_MINI_PRODUCT_NAME} configuration and data from /che/backup mount + offline Saves ${CHE_MINI_PRODUCT_NAME} Docker images into TAR files for offline install + info Displays info about ${CHE_MINI_PRODUCT_NAME} and the CLI + [ --all Run all debugging tests + --debug Displays system information + --network] Test connectivity between ${CHE_MINI_PRODUCT_NAME} sub-systems + ssh [machine-name] SSH to a workspace if SSH agent enabled + mount Synchronize workspace with current working directory + action [--help] Start action on ${CHE_MINI_PRODUCT_NAME} instance + compile SDK - Builds Che source code or modules + test [--help] Start test on ${CHE_MINI_PRODUCT_NAME} instance + +Variables: + CHE_HOST IP address or hostname where ${CHE_MINI_PRODUCT_NAME} will serve its users + CLI_DEBUG Default=false.Prints stack trace during execution + CLI_INFO Default=true. Prints out INFO messages to standard out + CLI_WARN Default=true. Prints WARN messages to standard out + CLI_LOG Default=true. Prints messages to cli.log file +``` + +In these docs, when you see `che-cli [COMMAND]`, it is assumed that you run the CLI with the full `docker run ...` syntax. We short hand the docs for readability. + +#### Sample Start +For example, to start the nightly build of Che with its data saved on Windows in `C:\tmp`: +`docker run -it --rm -v /var/run/docker.sock:/var/run/docker.sock -v /c/tmp:/che eclipse/che-cli:5.0.0-latest start` + +This installs a configuration, downloads Che's Docker images, run pre-flight port checks, boot Che's services, and run post-flight checks. You do not need root access to start Che, unless your environment requires it for Docker operations. + +A successful start will display: +``` +INFO: (che cli): Downloading cli-latest +INFO: (che cli): Checking registry for version 'nightly' images +INFO: (che-cli config): Generating che-cli configuration... +INFO: (che-cli config): Customizing docker-compose for Windows +INFO: (che-cli start): Preflight checks + port 8080: [OK] + +INFO: (che-cli start): Starting containers... +INFO: (che-cli start): Server logs at "docker logs -f che_che_1" +INFO: (che-cli start): Server booting... +INFO: (che-cli start): Booted and reachable +INFO: (che-cli start): Ver: 5.0.0-M8-SNAPSHOT +INFO: (che-cli start): Use: http://10.0.75.2 +INFO: (che-cli start): API: http://10.0.75.2/swagger +``` + +#### Versions +While we provide `nightly`, `latest`, and `5.0.0-latest` [redirection versions](#nightly-and-latest) which are tags that simplify helping you retrieve a certain build, you should always run Cche with a specific version label to avoid [redirection caching issues](#nightly-and-latest). So, running `docker run eclipse/che-cli` is great syntax for testing and getting started quickly, you should always run `docker run eclipse/che-cli:` for production usage. + +#### Volume Mounts +If you volume mount a single local folder to `:/che`, then Che creates `/che/che.env` (configuration file), `/che/instance` (user data, projects, runtime logs, and database folder), and `/che/backup` (data backup folder). + +However, if you do not want your `/instance`, and `/backup` folder to all be children of the same parent folder, you can set them individually with separate overrides. + +``` +docker run -it --rm -v /var/run/docker.sock:/var/run/docker.sock + -v :/che + -v :/che/instance + -v :/che/backup + eclipse/che-cli: [COMMAND] + +``` + +#### Hosting +If you are hosting Che at a cloud service like DigitalOcean, set `CHE_HOST` to the server's IP address or its DNS. We use an internal utility, `eclipse/che-ip`, to determine the default value for `CHE_HOST`, which is your server's IP address. This works well on desktops, but usually fails on hosted servers requiring you to explicitly set this value. + +``` +docker run -it --rm -v /var/run/docker.sock:/var/run/docker.sock + -v :/che + -e CHE_HOST= + eclipse/che-cli: [COMMAND] +``` + +## Uninstall +``` +# Remove your che-cli configuration and destroy user projects and database +docker run eclipse/che-cli destroy + +# Deletes Che's images from your Docker registry +docker run eclipse/che-cli rmi +``` + +## Configuration +Configuration is done with environment variables in `che.env` placed into the root of the folder you volume mounted to `:/che`. Environment variables are stored in `che.env`, a file that is generated during the `che-cli init` phase. If you rerun `che-cli 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-cli config` to apply this configuration to your system. `che-cli start` also reapplies the latest configuration. + +You can run `che-cli init` to install a new configuration into an empty directory. This command uses the `che-cli/init:` Docker container to deliver a version-specific set of puppet templates into the folder. + +If you run `che-cli 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-cli 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-cli 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-cli 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-cli 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. When pulling from version control, copy `che.env` into the root of the folder you volume mount to `:/che`. +5. You can then run `che-cli config` or `che-cli start` and the instance configuration will be generated from this file. + +#### Logs and User Data +When Che initializes itself, it stores logs, user data, database data, and instance-specific configuration in the folder mounted to `/che/instance` or an `instance` subfolder of what you mounted to `/che`. + +Che's containers save their logs in the same location: +``` +/logs/che/2016 # Server logs +/logs/che/che-machine-logs # Workspace logs +``` + +User data is stored in: +``` +/data/che # Project backups (we synchronize projs from remote ws here) +/data/registry # Workspace snapshots +``` + +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 # Version of Che installed +/instance/docker-compose-container.yml # Docker compose to launch internal services +/instance/docker-compose.yml # Docker compose to launch Che from the host without contianer +/instance/config # Configuration files which are input mounted into the containers +``` + +#### oAuth +TODO: ADD in CHE OAUTH + +#### 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 :/che \ + -v :/repo \ + eclipse/che-cli: [COMMAND] +``` +Dev mode will use files from your host repository in three ways: + +1. During the `che-cli 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 CLI bootstrap phase, the source repository's `/dockerfiles/cli/cli.sh` file will be used instead of the one within the `eclipse/che-cli` container. This allows CLI developers to iterate without having to rebuild `eclipse/che-cli` container after each change. +3. During the `che-cli start` phase, a local assembly from `assembly/assembly-main/target/eclipse-che-*` 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 the Che debug port, in the `che.env`: +``` +CHE_DEBUG_PORT=8000 +``` + +#### Licensing +Eclipse Che is open sourced under the Eclipse Public License. + +#### 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 pass it during initialization to the docker command: + +``` +docker run -e CHE_HOST= eclipse/che-cli: start +``` + +#### HTTP/S +TODO: GET CONFIRMATION + + +#### Workspace Limits +TODO: REVIEW LIST OF LIMITS + +#### Private Docker Registries +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 /` 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` file: +``` +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 +``` + +## Managing + +#### Scaling +You can resize the physical node that you are running Che without disruptings its services. You can also consider running a Che farm of multiple Che servers with a load balancer or proxy in front, though this does require manual configuration. You can see GitHub issues of users in our GitHub history that have set this up. + +You can also consider using Codenvy, which has an embedded system for adding and removing additional physical nodes to provide additional resources for scaling workspaces. + +#### Upgrading +Upgrading Che is done by downloading a `eclipse/che-cli:` that is newer than the version you currently have installed. For example, if you have 5.0.0-M2 installed and want to upgrade to 5.0.0-M7, then: +``` +# Get the new version of Che +docker pull eclipse/che-cli:5.0.0-M7 + +# You now have two eclipse/che-cli images (one for each version) +# Perform an upgrade - use the new image to upgrade old installation +docker run eclipse/che-cli:5.0.0-M7 upgrade +``` + +The upgrade command has numerous checks to prevent you from upgrading Che if the new image and the old version are not compatible. In order for the upgrade procedure to advance, the CLI image must be newer that the version in `/instance/che.ver`. + +The upgrade process: a) performs a version compatibility check, b) downloads new Docker images that are needed to run the new version of Che, c) stops Che if it is currently running triggering a maintenance window, d) backs up your installation, e) initializes the new version, and f) starts Che. + +You can run `che-cli version` to see the list of available versions that you can upgrade to. + +#### Backup +You can run `che-cli backup` to create a copy of the relevant configuration information, user data, projects, and workspaces. We do not save workspace snapshots as part of a routine backup exercise. You can run `che-cli restore` to recover Che from a particular backup snapshot. The backup is saved as a TAR file that you can keep in your records. + +#### Migration +We currently do not support migrating from the puppet-based configuration of Che to the Dockerized version. We do have a manual process which can be followed to move data between the puppet and Dockerized versions. The versions must be identical. Contact us to let our support team perform this migration for you. + +#### Disaster Recovery +We maintain a disaster recovery [policy and best practices](http://che.readme.io/v5.0/docs/disaster-recovery). + +## CLI Reference +The CLI is configured to hide most error conditions from the output screen. The CLI prints internal stack traces and error output to `cli.log`. To see the output of this log, you will need to volume mount a local path to `:/cli`. For example: + +``` +docker run --rm -it + -v /var/run/docker.sock:/var/run/docker.sock + -v /c/che:/che + -v /c/eclipse/che-cli:/cli eclipse/che-cli:nightly [COMMAND] +``` + +### `che-cli init` +Initializes an empty directory with a Che configuration and instance folder where user data and runtime configuration will be stored. You must provide a `:/che` volume mount, then Che creates an `instance` and `backup` subfolder of ``. You can optionally override the location of `instance` by volume mounting an additional local folder to `:/che/instance`. You can optionally override the location of where backups are stored by volume mounting an additional local folder to `:/che/backup`. After initialization, a `che.env` file is placed into the root of the path that you mounted to `:/che`. + +These variables can be set in your local environment shell before running and they will be respected during initialization: + +| Variable | Description | +|----------|-------------| +| `CHE_HOST` | The IP address or DNS name of the Che service. We use `eclipse/che-ip` to attempt discovery if not set. | + +Che depends upon Docker images. We use Docker images in three ways: +1. As cross-platform utilites within the CLI. For example, in scenarios where we need to perform a `curl` operation, we use a small Docker image to perform this function. We do this as a precaution as many operating systems (like Windows) do not have curl installed. +2. To perform initialization and configuration of Che such as with `eclipse/che-init`. This image contains templates that are delivered as a payload and installed onto your computer. These payload images have different files based upon the image's version. +4. To run the Che server. + +You can control the nature of how che-cli downloads these images with command line options. All image downloads are performed with `docker pull`. + +| Mode>>>> | Description | +|------|-------------| +| `--no-force` | Default behavior. Will download an image if not found locally. A local check of the image will see if an image of a matching name is in your local registry and then skip the pull if it is found. This mode does not check DockerHub for a newer version of the same image. | +| `--pull` | Will always perform a `docker pull` when an image is requested. If there is a newer version of the same tagged image at DockerHub, it will pull it, or use the one in local cache. This keeps your images up to date, but execution is slower. | +| `--force` | Performs a forced removal of the local image using `docker rmi` and then pulls it again (anew) from DockerHub. You can use this as a way to clean your local cache and ensure that all images are new. | +| `--offline` | Loads Docker images from `backup/*.tar` folder during a pre-boot mode of the CLI. Used if you are performing an installation or start while disconnected from the Internet. | + +You can reinstall Che on a folder that is already initialized and preserve your `/che/che.env` values by passing the `--reinit` flag. + +### `che-cli config` +Generates a Che instance configuration thta is placed in `/che/instance`. This command uses puppet to generate configuration files for the Che server and Docker swarm This command is executed on every `start` or `restart`. + +If you are using a `eclipse/che-cli:` image and it does not match the version that is in `/instance/che.ver`, then the configuration will abort to prevent you from running a configuration for a different version than what is currently installed. + +This command respects `--no-force`, `--pull`, `--force`, and `--offline`. + +### `che-cli start` +Starts Che and its services using `docker-compose`. If the system cannot find a valid configuration it will perform a `che-cli init`. Every `start` and `restart` will run a `che-cli config` to generate a new configuration set using the latest configuration. The starting sequence will perform pre-flight testing to see if any ports required by Che are currently used by other services and post-flight checks to verify access to key APIs. + +### `che-cli stop` +Stops all of the Che service containers and removes them. + +### `che-cli restart` +Performs a `che-cli stop` followed by a `che-cli start`, respecting `--pull`, `--force`, and `--offline`. + +### `che-cli destroy` +Deletes `/docs`, `che.env` and `/che/instance`, including destroying all user workspaces, projects, data, and user database. If you pass `--quiet` then the confirmation warning will be skipped. + +If you have mounted the `:/cli` path, then we write the `cli.log` to your host directory. By default, this log is not destroyed in a `che-cli destroy` command so that you can maintain a record of all CLI executions. You can also have this file removed from your host by mounting `:/cli` and passing the `--cli` parameter to this command. + +### `che-cli offline` +Saves all of the Docker images that Che requires into `/backup/*.tar` files. Each image is saved as its own file. If the `backup` folder is available on a machine that is disconnected from the Internet and you start Che with `--offline`, the CLI pre-boot sequence will load all of the Docker images in the `/backup/` folder. + +### `che-cli rmi` +Deletes the Docker images from the local registry that Che has downloaded for this version. + +### `che-cli download` +Used to download Docker images that will be stored in your Docker images repository. This command downloads images that are used by the CLI as utilities, for Che to do initialization and configuration, and for the runtime images that Che needs when it starts. This command respects `--offline`, `--pull`, `--force`, and `--no-force` (default). This command is invoked by `che-cli init`, `che-cli config`, and `che-cli start`. + +This command is invoked by `che-cli init` before initialization to download the images for the version specified by `eclipse/che-cli:`. + +### `che-cli version` +Provides information on the current version and the available versions that are hosted in Che's repositories. `che-cli upgrade` enforces upgrade sequences and will prevent you from upgrading one version to another version where data migrations cannot be guaranteed. + +### `che-cli upgrade` +Manages the sequence of upgrading Che from one version to another. Run `che-cli version` to get a list of available versions that you can upgrade to. + +Upgrading Che is done by using a `eclipse/che-cli:` that is newer than the version you currently have installed. For example, if you have 5.0.0-M2 installed and want to upgrade to 5.0.0-M7, then: +``` +# Get the new version of Che +docker pull eclipse/che-cli:5.0.0-M7 + +# You now have two eclipse/che-cli images (one for each version) +# Perform an upgrade - use the new image to upgrade old installation +docker run eclipse/che-cli:5.0.0-M7 upgrade +``` + +The upgrade command has numerous checks to prevent you from upgrading Che if the new image and the old version are not compatiable. In order for the upgrade procedure to proceed, the CLI image must be newer than the value of '/instance/che.ver'. + +The upgrade process: a) performs a version compatibility check, b) downloads new Docker images that are needed to run the new version of Che, c) stops Che if it is currently running triggering a maintenance window, d) backs up your installation, e) initializes the new version, and f) starts Che. + +You can run `che-cli version` to see the list of available versions that you can upgrade to. + +### `che-cli info` +Displays system state and debugging information. `--network` runs a test to take your `Che_HOST` value to test for networking connectivity simulating browser > Che and Che > workspace connectivity. + +### `che-cli backup` +Tars your `/instance` into files and places them into `/backup`. These files are restoration-ready. + +### `che-cli restore` +Restores `/instance` to its previous state. You do not need to worry about having the right Docker images. The normal start / stop / restart cycle ensures that the proper Docker images are available or downloaded, if not found. + +This command will destroy your existing `/instance` folder, so use with caution, or set these values to different folders when performing a restore.