diff --git a/.gitignore b/.gitignore index c3fd7ebf13..7795a7dfa3 100644 --- a/.gitignore +++ b/.gitignore @@ -60,10 +60,11 @@ Thumbs.db */overlays *~ -# Che files +# Che files # +############# .che dockerfiles/che/eclipse-che.tar.gz .unison* docs/_site docs/.sass-cache - +docs/.jekyll-metadata diff --git a/docs/_data/docs.yml b/docs/_data/docs.yml index 2268c2d141..5a5edbc86e 100644 --- a/docs/_data/docs.yml +++ b/docs/_data/docs.yml @@ -1,25 +1,14 @@ - title: SETUP docs: - - che-setup-intro + - che-setup-intro - che-setup-getting-started - che-setup-getting-started-saas-cloud - - che-setup-bitnami - - che-setup-cli - - che-setup-ssh - - che-setup-desktop-ide-mounting - - che-setup-config - - che-setup-config-proxies - - che-setup-networking - - che-setup-config-docker - - che-setup-config-security - - che-setup-scaling - - che-setup-glossary -- title: SETUP - ALTERNATIVES - docs: - - che-setupalt-docker - - che-setupalt-native - - che-setupalt-docker-server - - che-setupalt-electron + - che-setup-bitnami + - che-setup-configuration + - che-setup-managing + - che-setup-cli + - che-setup-glossary + - che-setup-docker - title: WORKSPACE ADMINISTRATION docs: - ws-admin-intro @@ -29,20 +18,14 @@ - ws-machines - ws-volume-mounts - ws-agents -- title: CHEDIR - PORTABLE WORKSPACES - docs: - - chedir-getting-started - - chedir-why - - chedir-installation - - chedir-project-setup - - chedir-up-and-down - - chedir-chefiles - - chedir-ssh - - chedir-factories -- title: USE CHE AS AN IDE + - ws-data-model-stacks + - ws-data-model-samples +- title: USER GUIDE docs: - ide-projects - ide-import-a-project + - ide-ssh + - ide-sync - ide-editor-settings - ide-intellisense - ide-commands @@ -53,17 +36,28 @@ - ide-sharing - ide-debug - ide-docker -- title: USE CHE AS A WORKSPACE SERVER + - ide-electron +- title: CHEDIR - PORTABLE WORKSPACES docs: + - chedir-getting-started + - chedir-why + - chedir-installation + - chedir-project-setup + - chedir-up-and-down + - chedir-chefiles + - chedir-ssh + - chedir-factories +- title: DEVELOPER GUIDE - REST API + docs: + - server-rest-api - server-api-projects - server-build-run - server-create-workspaces - server-events - server-project-types - - server-rest-api - server-stack - server-websocket-api -- title: WRITE CHE IDE PLUGINS +- title: DEVELOPER GUIDE - IDE PLUGINS docs: - plugins-introduction - plugins-setup-che-workspace @@ -81,8 +75,4 @@ - plugins-native-access-to-the-workspace - plugins-embed-htmljs - plugins-helloworld-extension - - plugins-themes -- title: CHE DATA MODEL - docs: - - che-data-model-stack - - che-data-model-samples + - plugins-themes \ No newline at end of file diff --git a/docs/_docs/che-data-model/che-data-model-samples.md b/docs/_docs/che-data-model/che-data-model-samples.md deleted file mode 100644 index 2690c01787..0000000000 --- a/docs/_docs/che-data-model/che-data-model-samples.md +++ /dev/null @@ -1,163 +0,0 @@ ---- -tags: [ "eclipse" , "che" ] -title: Samples -excerpt: "Sample object defines code sample and commands that can be used to bootstrap the content of a new project." -layout: docs -permalink: /:categories/samples/ ---- -Samples object defines code sample and commands that can be used to bootstrap the content of a new project. -(Learn more on [Samples](doc:samples) ) - -## Samples Object - -Sample apps are referenced in a JSON file: -```json -samples : { - name : STRING, // Name of the project - displayName : STRING, // Name of the project, which will be displayed for the client without restrictions for the value - path : STRING, // Path to the project in a workspace behaviors - description : STRING, // Description of the project to appear on the dashboard - projectType : STRING, // Project type. Different types have different attributes. Find all the projects types descriptions in the Factory docs - mixins : {}, // Mixins add sets of behavior attributes to a project. - attributes : {}, // List of project type attributes. List varies by type selected - modules : {}, // (Optional) Project components. Set by server - problems : {}, // (Optional) Errors occurred in the project. Set by server - source : {}, // The source code imported attributes to a project - commands : {}, // Set of the commands available for the project. - links : {}, // List of the method links - category : STRING, // Category to be displayed in the IDE Create Project wizard - tags : ARRAY // Values used to filter samples -} -``` -### Source -```json -samples.source : { - type : [git | svn | zip], // Version control system - location : URL, // Location of source code in version control system or location of a remote zip archive - parameters : {} // (Optional) Parameter list to configure access. Parameter variables vary by type - } -``` -When using `source.type` with `git` or `svn`, the `source.location` should be URL of a publicly available repo. Referencing private repos over HTTPS will result in clone failure unless credentials are provided in the URL itself. Using SSH URLs is possible, however, a user will need ssh key to complete this operation, therefore, it is recommended to use HTTPS URLs to public repos. -```json -"source":{ - "type":"git", - "location":"https://github.com/tomitribe/tomee-jaxrs-angular-starter-project.git", - "parameters":{} - }, -``` - -`zip` archives are referenced as URLs to remotely hosted archives that are publicly available i.e. require no login/password to be downloaded. It is not possible to reference local URLs unless you run a local server to host them (in this case a local IP is used e.g. `http://192.168.0.10/projecs/myproject.zip`). - -```json -"source":{ - "type":"zip", - "location":"http://192.168.0.10/projecs/myproject.zip", - "parameters":{} - }, -``` - -#### Parameters -```json -samples.source.parameters : { - branch : STRING, // Clone from this branch - keepVcs : [true | false], // Keep the .git folder after clone. - commitId : STRING, // Clone from a commit point. Branch precedes this property - keepDir : STRING, // Sparse Checkout to clone only sub-directory of repository - fetch : REF-SPEC // Clone from patch set of provided ref-spec -} -``` - -### Commands -When authoring a project sample we recommend to predefine commands to register build and run actions. [Learn more about commands.](https://eclipse-che.readme.io/docs/commands) -```json -samples.commands : [{ - // List of pre-defined commands -}] -``` -See [Command](https://eclipse-che.readme.io/docs/workspace#section-command-object) reference. - - -### Tags -Tags are used for stacks and samples objects. Those values are used to determine if a sample is compatible with a stack. -```json -samples.tags : [{ - "tag1" //list of strings representing tags - "tag2" - "..." -}] -``` -## Samples Reference -```json -[ - { - "name":"web-javaee-jaxrs", - "displayName":"web-javaee-jaxrs", - "path":"/web-javaee-jaxrs", - "description":"A basic example demonstrating JAXRS running on Apache TomEE", - "projectType":"maven", - "mixins":[], - "attributes":{ - "language":[ - "java" - ] - }, - "modules":[], - "problems":[], - "source":{ - "type":"git", - "location":"https://github.com/tomitribe/tomee-jaxrs-angular-starter-project.git", - "parameters":{} - }, - "commands":[ - { - "name":"build", - "type":"mvn", - "commandLine":"mvn -f ${current.project.path} clean install && cp ${current.project.path}/target/*.war $TOMEE_HOME/webapps/ROOT.war", - "attributes":{ - "previewUrl":"" - } - }, - { - "name":"run tomee", - "type":"custom", - "commandLine":"$TOMEE_HOME/bin/catalina.sh run", - "attributes":{ - "previewUrl":"http://${server.port.8080}" - } - }, - { - "name":"stop tomee", - "type":"custom", - "commandLine":"$TOMEE_HOME/bin/catalina.sh stop", - "attributes":{ - "previewUrl":"" - } - }, - { - "name":"build and run", - "type":"mvn", - "commandLine":"mvn -f ${current.project.path} clean install && cp ${current.project.path}/target/*.war $TOMEE_HOME/webapps/ROOT.war && $TOMEE_HOME/bin/catalina.sh run", - "attributes":{ - "previewUrl":"http://${server.port.8080}" - } - }, - { - "name":"debug", - "type":"mvn", - "commandLine":"mvn -f ${current.project.path} clean install && cp ${current.project.path}/target/*.war $TOMEE_HOME/webapps/ROOT.war && $TOMEE_HOME/bin/catalina.sh jpda run", - "attributes":{ - "previewUrl":"http://${server.port.8080}" - } - } - ], - "links":[], - "category":"Samples - "tags":[ - "maven", - "java", - "javaee", - "jaxrs" - ] - } -] -``` diff --git a/docs/_docs/setup-alternatives/che-setupalt-docker.md b/docs/_docs/setup-alternatives/che-setupalt-docker.md deleted file mode 100644 index 05682c3251..0000000000 --- a/docs/_docs/setup-alternatives/che-setupalt-docker.md +++ /dev/null @@ -1,250 +0,0 @@ ---- -tags: [ "eclipse" , "che" ] -title: Usage: Docker Launcher -excerpt: "Run Che inside a Docker container with workspaces saved on your host." -layout: docs -permalink: /:categories/docker/ ---- -This syntax is the preferred way to start and stop Eclipse Che. It follows the principles of 12 factor apps and has a format that works consistently on every operating system. This technique uses a Docker "launcher" - a Docker container that starts the Che server launched in a second container. This creates a simpler syntax reusable on different operating systems. -# Pre-reqs -* Eclipse Che 4.6+: [Docker 1.8+](https://www.docker.com/products/docker). -* Eclipse Che 4.5-: see the pre-reqs in running Che as a [Server](doc:usage-docker-server). -# Usage - -```shell -docker run --rm -t -v /var/run/docker.sock:/var/run/docker.sock eclipse/che:5.0.0-latest [COMMAND] - -# WHERE COMMAND IS: - start # Starts Che server - stop # Stops Che server - restart # Restarts Che server - update # Pulls latest version of Che image (upgrade) - info # Print debugging information\ -``` - -# Start - -```shell -docker run --rm -t -v /var/run/docker.sock:/var/run/docker.sock eclipse/che:5.0.0-latest start - -# YOUR OUTPUT -INFO: ------------------------------------ -INFO: ECLIPSE CHE: CONTAINER STARTING -INFO: ECLIPSE CHE: SERVER BOOTING -INFO: ECLIPSE CHE: See logs at "docker logs -f che" -INFO: ECLIPSE CHE: BOOTED AND REACHABLE -INFO: ECLIPSE CHE: http://:8080 -INFO: ------------------------------------ -``` -The `-v /var/run/docker.sock:/var/run/docker.sock` syntax is needed when starting Eclipse Che so that the Che server (running inside of a container) can communicate to the Docker daemon and ask it to launch workspace containers as peers to the Che server container. - -You can monitor the progress of how the server is booting or check for errors in the Eclipse Che server logs. You access these logs in another terminal with `docker logs -f che`. If the server has booted successfully, you should see something similar to the following at the end of the logs. -```shell -2016-07-15 20:46:24,204[main] [INFO ] [o.a.catalina.startup.Catalina 642] - Server startup in 9052 ms\ -``` - -# Workspace Storage -Che saves your workspaces, projects and Che internal configuration in `/home/user/che`. This location must be changed if you are on Microsoft Windows by setting the `CHE_DATA_FOLDER` environment variable. -```shell -docker run --rm -t -v /var/run/docker.sock:/var/run/docker.sock - -e CHE_DATA= - eclipse/che:5.0.0-latest start\ -``` - -#### Microsoft Windows Nuances -1. Your storage location needs to be provided in a Docker format. So use `/c/Users/tyler` but not `c:\\Users\\tyler` or `c:\\\\Users\\\\Tyler`.\n2. Windows is case sensitive, so `/c/Users`, but not `/c/users`. \n3. You *must* provide a path that has no spaces. Docker does not handle directories with spaces well. \n4. If you are using boot2docker, then you *must* choose a folder that is a subdirectory of `%userprofile%` which is usually `/c/Users`. However, if you are using Docker for Windows on Windows 10+, then you can select any directory. - - -# Diagnose Boot Problems -Generally, if Che fails to boot smoothly, then it is most commonly a configuration issue related to how Docker is setup on your operating system. While we try to address all possible configurations within our system, sometimes networking, firewalls, and other items can interfere. - -There are [configuration items that you can set to alter how Che](doc:networking) communicates with its workspaces, the browser, and the Docker daemon. There are some simple tests that you can run to diagnose if one of the connections is failing you. - -The Che CLI has a number of debugging assistants built into it to provide helpful values during the process of configuring your Che system. -```shell -# Print CLI debugging info -$ che info -DEBUG: --------------------------------------- -DEBUG: --------- CHE CLI DEBUG INFO -------- -DEBUG: --------------------------------------- -DEBUG: -DEBUG: --------- PLATFORM INFO ------------- -DEBUG: DOCKER_INSTALL_TYPE = boot2docker -DEBUG: DOCKER_HOST_IP = 192.168.99.100 -DEBUG: IS_DOCKER_FOR_WINDOWS = NO -DEBUG: IS_DOCKER_FOR_MAC = NO -DEBUG: IS_BOOT2DOCKER = YES -DEBUG: IS_NATIVE = NO -DEBUG: HAS_DOCKER_FOR_WINDOWS_IP = NO -DEBUG: IS_MOBY_VM = NO -DEBUG: -DEBUG: --------------------------------------- -DEBUG: --------------------------------------- -DEBUG: --------------------------------------- - -# Print the Che launcher and server debugging info -DEBUG: --------------------------------------- -DEBUG: --------- CHE DEBUG INFO ------------ -DEBUG: --------------------------------------- -DEBUG: -DEBUG: --------- PLATFORM INFO ------------- -DEBUG: DOCKER_INSTALL_TYPE = boot2docker -DEBUG: DOCKER_HOST_OS = Boot2Docker 1.12.0 (TCL 7.2); HEAD:e030bab - Fri Jul 29 00:29:14 UTC 2016 -DEBUG: DOCKER_HOST_IP = 192.168.99.100 -DEBUG: DOCKER_DAEMON_VERSION = 1.12.0 -DEBUG: -DEBUG: -DEBUG: --------- CHE INSTANCE INFO ---------- -DEBUG: CHE CONTAINER EXISTS = YES -DEBUG: CHE CONTAINER STATUS = running -DEBUG: CHE SERVER STATUS = running -DEBUG: CHE IMAGE = eclipse/che-server:nightly -DEBUG: CHE SERVER CONTAINER ID = 09bde1bdbaec -DEBUG: CHE CONF FOLDER = not set -DEBUG: CHE DATA FOLDER = /home/user/che/workspaces -DEBUG: CHE DASHBOARD URL = http://192.168.99.100:8080 -DEBUG: CHE API URL = http://192.168.99.100:8080/api -DEBUG: CHE LOGS = run `docker logs -f che-server` -DEBUG: -DEBUG: -DEBUG: ---- CURRENT COMMAND LINE OPTIONS --- -DEBUG: CHE_PORT = 8080 -DEBUG: CHE_VERSION = nightly -DEBUG: CHE_RESTART_POLICY = no -DEBUG: CHE_USER = root -DEBUG: CHE_HOST_IP = 192.168.99.100 -DEBUG: CHE_LOG_LEVEL = info -DEBUG: CHE_HOSTNAME = 192.168.99.100 -DEBUG: CHE_DATA_FOLDER = /home/user/che -DEBUG: CHE_CONF_FOLDER = not set -DEBUG: CHE_LOCAL_BINARY = not set -DEBUG: CHE_SERVER_CONTAINER_NAME = che-server -DEBUG: CHE_SERVER_IMAGE_NAME = eclipse/che-server -DEBUG: -DEBUG: --------------------------------------- -DEBUG: --------------------------------------- -DEBUG: --------------------------------------- - -# Run a connectivity test -$ che info --networking -DEBUG: -DEBUG: --------------------------------------- -DEBUG: -------- CHE CONNECTIVITY TEST -------- -DEBUG: --------------------------------------- -DEBUG: Browser => Workspace Agent : Connection succeeded -DEBUG: Browser (websocket) => Workspace Agent : Connection succeeded -DEBUG: Che Server => Workspace Agent (External IP): Connection succeeded -DEBUG: Che Server => Workspace Agent (Internal IP): Connection succeeded\ -``` - -# Environment Variables -We provide a range of environment variables that you can set that alters how Che launches from the local host. You can provide as many of these variables as you need to the launcher using the `-e VAR=` syntax. - -| Variable | Description | Default Values>>>>>>>>>>> -| --- | --- | --- -| `CHE_DATA` | Folder where user workspaces and Che preferences are saved. | `/home/user/che` -| `CHE_PORT` | `CHE_VERSION` | `CHE_RESTART_POLICY` -| `CHE_USER` | `CHE_CONF_FOLDER` | `CHE_LOG_LEVEL` -| `CHE_HOST_IP` | External port of Che server. | `8080` -| Che server version to boot. Set to `nightly` to get the nightly images and builds of Che. | `latest` | Che server restart policy if exited. See [Docker restart policies](https://docs.docker.com/engine/reference/commandline/run/#/restart-policies-restart) for all options. -| `no` | User ID of the Che server within its container. | `root` -| Folder where custom `che.properties` located. | null | Logging level of output for Che server. Can be `debug` or `info`. -| `info` | IP address 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. -| `CHE_ASSEMBLY` | The path to a Che assembly that is on your host to be used instead of the binary contained within the `che-server` image. | `/home/user/che` -| `CHE_HOSTNAME` | External hostname of Che server. Only need to set if admin is managing over hostname. | Varies by OS, but is typically `localhost`. -| `CHE_LAUNCHER_IMAGE_NAME`\n`CHE_SERVER_IMAGE_NAME`\n`CHE_FILE_IMAGE_NAME`\n`CHE_MOUNT_IMAGE_NAME`\n`CHE_TEST_IMAGE_NAME`\n `CHE_SERVER_CONTAINER_NAME` | Che uses various Docker images as utilities. Each image provides a different capability and is when launched as a container, given a container name. You can change the image names if you want to use one that you have built locally, or change the name of containers in case you want to launch multiple instances of the same image using different container names. Also consider using the Che CLI profile capability to manage different sets of environment values to run multiple instances of Che with different containers and images. | `eclipse/che`\n`eclipse/che-server`\n`eclipse/che-file`\n`eclipse/che-mount`\n`eclipse/che-test`\n`che-server` - -Starting in 4.7, you can also define any property typically loaded from `che.properties` using an environment variable. `che.properties` is an internal configuration file that defines advanced ways that Che will configure itself. If an override is not provided by a user, [then Che loads the default file](https://raw.githubusercontent.com/eclipse/che/master/assembly/assembly-wsmaster-war/src/main/webapp/WEB-INF/classes/codenvy/che.properties). There are dozens of additional configuration parameters available. You can change the default value of a property by passing in a variable that matches the name of the property replacing `.` with `_`. For example, you can pass `-e CHE_WORKSPACE_STORAGE=` to override the location where workspaces are stored. -# Versions and Nightly Builds -You can specify the version of Eclipse Che you want launched by providing a tag to the `che-launcher` image name. We parse that tag and will invoke a matching `che-server` image with the same label. If you would like the Che server image to be a different version than the launcher, use the `CHE_VERSION` environment variable. -```text -# Run the nightly version of the launcher and Che server -docker run --rm -t -v /var/run/docker.sock:/var/run/docker.sock \ - eclipse/che-launcher:nightly start - -# Run the latest launcher and the 4.7.2 Che server -docker run --rm -t -v /var/run/docker.sock:/var/run/docker.sock \ - -e CHE_VERSION=4.7.2 \ - eclipse/che start\ -``` - -# Local Eclipse Che Binaries - -You can have the launcher use Eclipse Che binaries that you have on your local host instead of those within the Che image that you select. This is useful for extension developers that are building local assemblies and would like to use the launcher to execute their custom Che build. - -Inform Che of the local directory where your binaries are stored and the Che image will use those. -```text -# If your local assembly is located at /home/assembly: -docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \ - -e CHE_ASSEMBLY=path_to_che_sources/assembly/assembly-main/target/eclipse-che-/eclipse-che- \ - eclipse/che start\ -``` - -# Add Custom Eclipse Che Properties -There are many customizations you can make to the Che server by altering the `che.properties` file. -```shell -# Save your custom che.properties in any local folder -/etc/che/che.properties - -# Start che notifying the launcher of the custom properties -docker run --rm -t -v /var/run/docker.sock:/var/run/docker.sock \ - -e CHE_CONF_FOLDER=/etc/che \ - eclipse/che:5.0.0-latest start\ -``` -You can get a template of the latest version of the `che.properties` [file from here](https://github.com/eclipse/che/blob/master/assembly/assembly-wsmaster-war/src/main/webapp/WEB-INF/classes/codenvy/che.properties). You can get the default `che.properties` file for older versions by changing the tag selector in GitHub. - -In the `che-server` container launched by the `che-launcher`, the Eclipse Che server loads default properties from `/tomcat/webapps/wsmaster/WEB-INF/classes/codenvy/che.properties`. The Che server overrides those values with `.properties` files that you provide. - -System properties and environment variables may be used in `.properties` files in the form `${name}`. For example: -```json -# If java.io.tmpdir is Java property with value "/tmp" then "/tmp/my-index" is result -index.dir=${java.io.tmpdir}/my-index - -# che.home is set as a system property when Che starts -data.dir=${che.home}/conf -``` - -# Under The Hood -The Eclipse Che launcher is a Docker container which launches the Che server container. When you run the launcher container, the container executes a script that gathers information about your environment and then uses that information to launch the Che server container. - -You can bypass the Che launcher and run the Che server container directly. Note that to run this container directly you must replace the environment variables with your own values. For additional information on running Che server container directly refer to [Usage: Docker Server](https://eclipse-che.readme.io/docs/usage-docker-server). -```shell -docker run -d --name "${CHE_SERVER_CONTAINER_NAME}" \ - -v /var/run/docker.sock:/var/run/docker.sock \ - -v /home/user/che/lib:/home/user/che/lib-copy \ - ${CHE_LOCAL_BINARY_ARGS} \ - -p "${CHE_PORT}":8080 \ - --restart="${CHE_RESTART_POLICY}" \ - --user="${CHE_USER}" \ - ${CHE_CONF_ARGS} \ - ${CHE_STORAGE_ARGS} \ - "${CHE_SERVER_IMAGE_NAME}":"${CHE_VERSION}" \ - --remote:"${CHE_HOST_IP}" \ - -s:uid \ - -s:client \ - ${CHE_DEBUG_OPTION} \ - run > /dev/null -``` - -# Docker Unix Socket Mounting vs TCP Mode -The `-v /var/run/docker.sock:/var/run/docker.sock` syntax is for mounting a Unix socket to allow processes within the container to reach the Docker daemon. - -However, peculiarities of file systems and permissions may make it impossible to invoke Docker processes from inside a container. If this happens, the Che startup scripts will print an error about not being able to reach the Docker daemon with guidance on how to resolve the issue. - -An alternative solution is to have Docker listen to both TCP and Unix sockets. On the host running the Docker daemon: -```text -# Set this environment variable and restart the Docker daemon -DOCKER_OPTS=" -H tcp://0.0.0.0:2375 -H unix:///var/run/docker.sock" - -# Verify that the Docker API is responding at: -http://:2375/containers/json -``` -Having verified that your Docker daemon is listening, run the Che container with the with `DOCKER_HOST` environment variable set to the IP address of `docker0` or `eth0` network interface. If `docker0` is running on 1.1.1.1 then: -```shell -docker run --rm -t -v /var/run/docker.sock:/var/run/docker.sock \ - -e DOCKER_HOST=tcp://1.1.1.1:2375 \ - eclipse/che:5.0.0-latest start\ -``` - -# Websockets -Eclipse Che heavily relies on WebSocket communications. When a browser client connects to a workspace, it connects to it through WebSockets. Inside the workspace, the workspace agent also uses WebSockets to connect back to the Che server. diff --git a/docs/_docs/setup-alternatives/che-setupalt-native.md b/docs/_docs/setup-alternatives/che-setupalt-native.md deleted file mode 100644 index ac3d779d4d..0000000000 --- a/docs/_docs/setup-alternatives/che-setupalt-native.md +++ /dev/null @@ -1,156 +0,0 @@ ---- -tags: [ "eclipse" , "che" ] -title: Usage: Native Server -excerpt: "Running Che server natively provides the best performance" -layout: docs -permalink: /:categories/native/ ---- -This is advanced syntax intended for developers that are building extensions for Che. The environmental setup requires Java and Docker - please see the pre-reqs for different operating systems at the end of this page. - -If you are behind a proxy see our [Configuration: Proxies](doc:configuration-proxies) docs. -# Start - -#### UID=1000 -On Linux systems Che must run under a user with UID=1000 to properly run the workspace containers. Run `id` command to get your UID settings.\n\nIf you user is not UID=1000 you can skip the check by using -`-skip:uid` on the command line or create a new user with the proper uid and add it to docker group.\n\nIn Ubuntu this can be achieved by running `adduser mynewuser` followed by adding the user to the `docker` group with `usermod -aG docker mynewuser` and then changing to the new user with `su - newuser`. - - -```shell -# In a terminal in the Che home directory. -# Windows: -bin/che run - -# Mac / Linux: -bin/che.sh run\ -``` -After starting, Che is available at: -```http -http://localhost:8080\ -``` - -```http -/ # Loads dashboard or last opened workspace, based upon user config -/dashboard # Loads dashboard for managing projects and workspaces -/che/ # Loads specific workspace\ -``` - -# Command Line - -```text -Usage: - che [OPTIONS] [COMMAND] - -m:name, --machine:name For Win & Mac, sets the docker-machine VM name; default=default - -p:port, --port:port Port that Che server will use for HTTP requests; default=8080 - -r:ip, --remote:ip If Che clients are not localhost, set to IP address of Che server - -h, --help Show this help - -d, --debug Use debug mode (prints command line options + app server debug) - - Options when running Che natively: - -b, --blocking-entropy Security: https://wiki.apache.org/tomcat/HowTo/FasterStartUp - -g, --registry Launch Docker registry as a container (used for ws snapshots) - -s:client, --skip:client Do not print browser client connection information - -s:java, --skip:java Do not enforce Java version checks - -s:uid, --skip:uid Do not enforce UID=1000 for Docker - - Commands: - run (Default) Starts Che server with logging in current console - start Starts Che server in new console - stop Stops Che server\ -``` -`che.bat` checks for the installation of `bash` and executes `che.sh`. The default parameters for `che.sh` include: running Che as a native server (not as a Docker image), launching on port 8080, and executing the `run` server action. - -Using `-i` will cause the Che server to launch itself in a Docker container. Otherwise, Che will start itself on the native operating system. Either way, once the Che server has been started, that server also needs access to create its own Docker containers. The native Che server will create containers using the avialable Docker daemon. The Che docker image will create its dependent Docker containers using the same daemon. - -If you launch Che as a Docker image, you can choose specific version of Che by passing in the version using the `tag` attribute. We support `latest`, `nightly`, and `version`. -# Stop - -```shell -bin/che stop\ -``` - -# Troubleshoot -Errors will appear as exceptions in `stdout` of Tomcat when you run it. Che saves standard and error output to `/logs/catalina.out`. - -### Too Many Files Opened -This means that Docker is not properly configured. For MacOS or Windows, [start a Docker machine](doc:install-pre-reqs#docker) instance and apply its environment variables to your shell before starting Che. - -### Port Already In Use -Che runs on a server that expects port 8080 to be configured. If you get this error, the port that Che is connecting to is already being used. Use the `-p:port` option when starting Che to change the port being used. - -### Cannot Create Projects -On Linux, Che must be launched with user ID=1000. The workspaces created by Che are launched in Docker containers that create an internal container user with ID=1000. If the Che server is launched with a user that does not have ID=1000 then your Che users will not have write permissions to the projects running within the workspace. This issue appears if you run Che as a sudo user or if you have set up special user accounts. You can launch Che with `--skip:uid` to ignore this check. However, you will need to create custom stacks that have their internal container users match the UID of your Linux installation. - -### Che Server Takes Long Time to Load -If you are running on Digital Ocean or other providers, there are additional security configurations which [may be necessary.](https://www.digitalocean.com/community/questions/fresh-tomcat-takes-loong-time-to-start-up) - -# Pre-reqs: Windows -###Java -Java is used to run Che's server and the SDK tools which are used to create and package plug-ins. Install [Java 1.8](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html). Java JRE is enough to run Che. You need the Java JDK if you want to build Che from source. - -The `JAVA_HOME` environment variable should be exported in the system and point to a valid Java installation. - -Windows users can either set these variables for a current terminal session or export them system wide. See: [Setting JAVA_HOME on Windows](https://confluence.atlassian.com/doc/setting-the-java_home-variable-in-windows-8895.html). - -###Docker -[Docker](https://get.docker.com/) will install `docker`, `docker-machine`, Git bash, and other utilities required to operating Docker. - -#### BIOS Virtualization Enabled -} - -Che depends upon Docker and will not start if it cannot verify Docker running. If you have Docker Toolbox installed, Che will create a VM using VirtualBox that is running Docker (this is unusualy now that Docker has released Docker for Windows). The script is performing the equivalent of the following. You can verify that VirtualBox is working properly if the following commands complete execution without an error. -```shell -# Start the Docker Machine -docker-machine start default - -# If you get an error, you may need to create a machine named 'default' -docker-machine create --driver virtualbox default - -# After the machine is created, add ENV variables to your shell -# This command will give you instructions of what to do -# MacOS -docker-machine env default - -# Windows -docker-machine env --shell cmd default\ -``` -###Git Bash -On Windows, `bash` is required to launch the Che server. This is typically installed with Git Windows, which is installed by Docker Toolbox for Windows, a requirement for using Che. -# Pre-reqs: Mac / Linux -###Java -Set `$JAVA_HOME` variable in the `~/.bash_profile` or `~/.profile` files. -```text -export JAVA_HOME=/path/to/Java -export PATH=$JAVA_HOME/bin:$PATH\ -``` - -# Networking -This page provides a how-to and important configuration properties that you must review to successfully set up Eclipse Che as a hosted server for remote clients. - -This page is a companion to the [Configuration: Networking](doc:configuration-networking) page which specifies all of the properties and workflow that Che provides related to networking. -![che_networking.png]({{ base }}/assets/imgs/che_networking.png) -This graphic provides a logical framework of the various components that have to be configured to be reachable to one another in a server scenarios. This document reviews the connection points between each component. - -## DNS -If your Che server has a configured DNS, you need to ensure that this DNS is reachable from the browser client and from within the workspace container. If the workspace container is running within a VM, then the DNS entry must also be reachable from within the VM. - -## Che Server => Workspace Agent -Che has an algorithm for retrieving the workspace agent URL that includes properties, environment variables and default values. - -If Che is launched in a VM and `DOCKER_HOST` or `CHE_DOCKER_MACHINE_HOST` variables have not been exported, the Che server will try to reach workspace agent at `localhost:32768-65535`. In this case, make sure `iptables` allows local connections for this port range. - -If `DOCKER_HOST` or `CHE_DOCKER_MACHINE_HOST` are exported and point to an external IP, make sure `32768-65535` port range is open for inbound connections since Che server will use this IP (or DNS) to reach the workspace agent. - -## Local Clients (Browser) => Workspace Agent -After the Che server has successfully pinged a workspace agent, the client will use the same endpoint to establish its connection with a workspace agent as well over `http` and `ws`. - -If you have customized `docker.client.daemon_url` or `machine.docker.local_node_host`, or you have exported `DOCKER_HOST` or `CHE_DOCKER_MACHINE_HOST`, the browser will use those provided values to connect to a workspace agent. - -## Workspace Agent => Che Server -When a workspace is coming online, it must verify that it can connect back to the Che server. The `che.properties` file has the property `machine.docker.che_api.endpoint` that identifies the location of the Che server APIs. The default value for this property uses a `che-host` alias. When a workspace container starts, Che writes an entry into the container's `/etc/hosts` file to map `che-host` to the IP address of the Che server. For example: -```text -172.17.0.1 che-host\ -``` -In most cases, `che-host` maps to the IP address of the `docker0` network interface. If Che fails to retrieve the IP address for this interface, then IP defaults that vary by operating system type are used. - -Make sure to check that the Che server's port is opened on the server's `iptables`. It is common that these ports would be closed and this would prevent the workspace agent from connecting back to the Che server, even though your browser clients can connect to the Che server. - -###Docker diff --git a/docs/_docs/setup/che-setup-cli.md b/docs/_docs/setup/che-setup-cli.md index dcc6486f81..7e227b53fc 100644 --- a/docs/_docs/setup/che-setup-cli.md +++ b/docs/_docs/setup/che-setup-cli.md @@ -1,230 +1,183 @@ --- -tags: [ "eclipse" , "che" ] -title: Usage: CLI -excerpt: "Installing and using the Eclipse Che CLI" +title: CLI Reference +excerpt: "Manage your Che installation on the command line." layout: docs permalink: /:categories/cli/ --- -#### Experimental -The CLI is currently for experimentation. Please provide feedback by [logging issues](https://github.com/eclipse/che/issues) in our GitHub repo. +The Docker image which runs Che is the Che CLI. It has various commands for running Che and also for allowing your end users to interact with their workspaces on the command line. -The CLI simplifies operation of Che and is available on all the OS that Che supports. Additionally, the CLI simplifies updating and executing the different tools that we have packaged as Docker containers. -# Install -You can install the CLI scripts from the [Che GitHub repo](https://github.com/eclipse/che). Windows users will need to first install [git for Windows](https://git-scm.com/download/win). -```shell -$ curl -sL https://raw.githubusercontent.com/eclipse/che/master/che.sh > che -$ chmod 755 che && mv che /usr/local/bin/\ ``` -```shell -\ +USAGE: + docker run -it --rm eclipse/che-cli: [COMMAND] + +MANDATORY DOCKER PARAMETERS: + -v :/data Where user, instance, and log data saved + +OPTIONAL DOCKER PARAMETERS: + -e CHE_HOST= IP address or hostname where che will serve its users + -e CHE_PORT= Port where che will bind itself to + -v :/data/instance Where instance, user, log data will be saved + -v :/data/backup Where backup files will be saved + -v :/repo che git repo to activate dev mode + -v :/sync Where remote ws files will be copied with sync command + -v :/unison Where unison profile for optimzing sync command resides + +COMMANDS: + action Start action on che instance + backup Backups che configuration and data to /data/backup volume mount + config Generates a che config from vars; run on any start / restart + destroy Stops services, and deletes che instance data + download Pulls Docker images for the current che version + help This message + info Displays info about che and the CLI + init Initializes a directory with a che install + offline Saves che Docker images into TAR files for offline install + restart Restart che services + restore Restores che configuration and data from /data/backup mount + rmi Removes the Docker images for , forcing a repull + ssh [machine-name] SSH to a workspace if SSH agent enabled + start Starts che services + stop Stops che services + sync Synchronize workspace with current working directory + test Start test on che instance + upgrade Upgrades che from one version to another with migrations and backups + version Installed version and upgrade paths ``` -```shell -# You need both che.bat and che.sh -curl -sL https://raw.githubusercontent.com/eclipse/che/master/che.sh > che.sh -curl -sL https://raw.githubusercontent.com/eclipse/che/master/che.bat > che.bat +The CLI will hide most error conditions from standard out. Internal stack traces and error output is redirected to `cli.log`, which is saved in the host folder where `:/data` is mounted. -# Add the files to your PATH -set PATH=;%PATH%\ -``` -```shell -\ -``` -### Upgrade the CLI -The URLs provided are for the latest version of the CLI that is saved within our source repositories. We tag and version the CLI for each version of Che. You can grab right right files with `che-.sh` and `che-.bat` from `https://install.codenvycorp.com/che/`. -```shell -# The latest released version - save on top of your existing CLI files -https://install.codenvycorp.com/che/che.bat -https://install.codenvycorp.com/che/che.sh +## 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 `:/data` volume mount, then Che creates a `instance` and `backup` subfolder of ``. You can optionally override the location of `instance` by volume mounting an additional local folder to `/data/instance`. You can optionally override the location of where backups are stored by volume mounting an additional local folder to `/data/backup`. After initialization, a `che.env` file is placed into the root of the path that you mounted to `/data`. -# Specific version of the CLI -https://install.codenvycorp.com/che/che-4.6.2.bat -https://install.codenvycorp.com/che/che-4.6.2.sh\ +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 to: +1. Provide 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. Look up the master version and upgrade manifest, which is saved within the CLI docker image in the /version subfolder. +3. Perform initialization and configuration of Che such as with `eclipse/che-init`. This image contains templates to be installed onto your computer used by the CLI to configure Che for your specific OS. + +You can control how Che 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.env` values by passing the `--reinit` flag. + +## config +Generates a Che instance configuration thta is placed in `/instance`. This command uses puppet to generate Docker Compose configuration files to run Che and its associated server. Che's server configuration is generated as a che.properties file that is volume mounted into the Che server when it boots. 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`. + +## start +Starts Che and its services using `docker-compose`. If the system cannot find a valid configuration it will perform an `init`. Every `start` and `restart` will run a `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. + +## stop +Stops all of the Che service containers and removes them. + +## restart +Performs a `stop` followed by a `start`, respecting `--pull`, `--force`, and `--offline`. + +## destroy +Deletes `/docs`, `che.env` and `/instance`, including destroying all user workspaces, projects, data, and user database. If you pass `--quiet` then the confirmation warning will be skipped. Passing `--cli` will also destroy the `cli.log`. By default this is left behind for traceability. + +## 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. + +`--list` option will list all of the core images and optional stack images that can be downloaded. The core system images and the CLI will always be saved, if an existing TAR file is not found. `--image:` will download a single stack image and can be used multiple times on the command line. You can use `--all-stacks` or `--no-stacks` to download all or none of the optional stack images. + +## rmi +Deletes the Docker images from the local registry that Che has downloaded for this version. + +## 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 init`, `che config`, and `che start`. + +`download` is invoked by `che init` before initialization to download images for the version specified by `eclipse/che-cli:`. + +## version +Provides information on the current version and the available versions that are hosted in Che's repositories. `che upgrade` enforces upgrade sequences and will prevent you from upgrading one version to another version where data migrations cannot be guaranteed. + +## upgrade +Manages the sequence of upgrading Che from one version to another. Run `che 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 ``` -# Use +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'. -```text -Usage: che [COMMAND] - start Starts che server - stop Stops che server - restart Restart che server - update Pulls specific version, respecting CHE_VERSION - profile add Add a profile to ~/.che/ - profile set Set this profile as the default for che CLI - profile unset Removes the default profile - leaves it unset - profile rm Remove this profile from ~/.che/ - profile update Update profile in ~/.che/ - profile info Print the profile configuration - profile list List available profiles - mount Synchronize workspace to a local directory - dir init Initialize directory with che configuration - dir up Create workspace from source in current directory - dir down Stop workspace running in current directory - dir status Display status of che in current directory - action [--help] Start action on che instance - test [--help] Start test on che instance - info [ --all Run all debugging tests - --server Run che launcher and server debugging tests - --networking Test connectivity between che sub-systems - --cli Print CLI (this program) debugging info - --create [] Test creating a workspace and project in che - [] - [] ]\ +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 version` to see the list of available versions that you can upgrade to. + +## 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. + +## backup +TARS your `/instance` into files and places them into `/backup`. These files are restoration-ready. + +## 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. + +TODO: NEED SYNTAX FOR SSH, TEST, SYNC, DIR COMMANDS + +# CLI Development +You can customize the CLI using a variety of techniques. This section discusses how engineers develop and test the CLI on their local machines. + +## Structure +The Che CLI is constructed of multiple Docker images within the Che source repository. +``` +/dockerfiles/base # Common functions and commands +/dockerfiles/cli # CLI entrypoint, overrides, and version information +/dockerfiles/init # Manifests used to configure Che on a host installation ``` -# Profiles -Most Che configuration parameters are done through system environment variables. If you have these set, the CLI will detect these values and pass them along to the `che-launcher`, `che-server`, `che-mount`, `che-dev`, and `che-dir` utilities. You can save sets of environment configurations as a profile. +The Che CLI is authored in `bash`. The `cli` image depends upon both the `base` image and the `init` image. In the source repository, we have `build.sh` commands which will build these Docker images for you either one at a time or collectively as a group. -When creating a profile, the CLI will take the values of currently set Che environment variables and place them into a profile. If you "set" a profile, then those environment variables will be loaded before any of the Che utilities are called. +It can become tedious rebuilding images every time you want to test a small change to a bash script. You can avoid having to rebuild images each time for every change to a bash script by volume mounting the contents during the image execution. You cannot volume mount the `entrypoint.sh` file which is where each container has a launch point, but you can volume mount others: +``` +# Volume mount the contents of the base image +-v /dockerfiles/scripts/base/scripts:/base/scripts -You can use profiles to set up different configurations of Che servers so that you can switch between different servers, launch them, and avoid having conflicts with container names, ports, and output. -```shell -# Configure some non-standard environment variables -export CHE_PORT=9000 -export CHE_SERVER_CONTAINER_NAME=my-home-che-server - -# Add a profile named food-network -che profile add food-network -INFO: -INFO: Added new che CLI profile ~/.che/profiles/food-network. -INFO: - -# Display its contents -che profile info food-network -DEBUG: --------------------------------------- -DEBUG: --------- CLI PROFILE INFO -------- -DEBUG: --------------------------------------- -DEBUG: -DEBUG: Profile ~/.che/profiles/food-network contains: -DEBUG: CHE_DIR_IMAGE_NAME=eclipse/che-dir -DEBUG: CHE_LAUNCHER_IMAGE_NAME=eclipse/che-launcher -DEBUG: CHE_MOUNT_IMAGE_NAME=eclipse/che-mount -DEBUG: CHE_PORT=9000 -DEBUG: CHE_SERVER_CONTAINER_NAME=my-home-che-server -DEBUG: CHE_SERVER_IMAGE_NAME=eclipse/che-server -DEBUG: CHE_TEST_IMAGE_NAME=eclipse/che-test - -# Set the food-network profile to be used by other utilities -che profile set food-network -INFO: -INFO: Set active che CLI profile to ~/.che/profiles/food-network. -INFO: - -# Start Che with the currently set configuration -che start - -# Unset the default configuration (CLI uses your current environment values) -che profile unset - -# Update an existing profile with the current values of environment variables -export CHE_PORT=10000 -che profile update food-network - -# List all available profiles -che profile list\ +# Volume mount the contents of the init image +-v :/repo ``` -# Chefiles +If you run the Che CLI in this configuration, then any changes made to the bash files or templates in those repositories will be used without having to first rebuild the CLI image. -#### Experimental -Chefiles are experimental starting with 4.6. The Chefile syntax is not locked and may change frequently. - -Chefiles let you create and configure lightweight, portable developer workspaces using a git repo as the basis for a project in a workspace. If you do not have a Che server running, one will be started in the background. - -The source code that is in the current directory will be used to populate the project(s) within the workspace. Git, version control, editing, and commands used within Che will be executed against the files in the directory, which are mounted within the workspace. - -Create a single file for your project to describe the type of workspace you want, the software that needs to be installed, and the way you want to access the machine. Store this file with your project code. Run a single command - `che up` — and watch Che put together a complete workspace in a Che server. -```shell -# Initilize a directory with a Chefile configuration - optional -che init - -# Convert the current directory into a Che workspace, starting Che if necessary -che up - -# Stop the workspace associated with the current directory -che down\ +## Custom CLI Assemblies +The Che CLI was designed to easily be overridden to allow different CLIs to be created from the same base structure. This is how Codenvy and ARTIK has an identical CLIs to Che. The CLI is created with a few minimal assets: ``` -## Example -```shell -$ git clone http://github.com/benoitf/spring-petclinic -$ cd spring-petclinic -$ che up - -INFO: ECLIPSE CHE: FOUND IMAGE eclipse/che-dir:nightly -INFO: ECLIPSE CHE FILE: LAUNCHING CONTAINER -INFO: ECLIPSE CHE FILE: ADDED CHE CONFIGURATION -INFO: ECLIPSE CHE FILE: STARTING CHE -INFO: ECLIPSE CHE: ALREADY HAVE IMAGE eclipse/che-server:nightly -INFO: ECLIPSE CHE: CONTAINER STARTING -INFO: ECLIPSE CHE: SERVER LOGS AT "docker logs -f che-server" -INFO: ECLIPSE CHE: SERVER BOOTING... -INFO: ECLIPSE CHE: BOOTED AND REACHABLE - -Open browser to http://10.0.75.2:8080/che/local -``` -This example creates a new workspace named local in a Che server running in the background. When the command started, Che was not started, and the Che launcher was silently called to start Che with its default configuration. - -## File Structure -```text -Chefile # Optional configuration file -/.che/conf/che.properties # Used to define the behavior of the Che server -/.che/workspaces # Workspace meta data\ -``` -## Chefile -Add an optional Chefile to your directory to provide instructions on how Che should launch itself and rules for how the workspace should be created. -```json -che.server.type = [local | codenvy] -che.server.ip = localhost -che.server.port = 8080 -che.server.user = admin -che.server.pass = password -che.server.startup = [insert startup params to pass to docker run] - -# Default is latest, but can be "nightly" or a tagged version -che.server.version = latest - -# new = always create new workspace for every che up command -# reuse = create new if not exist, otherwise reopen existing workspace -workspace.create = [new | reuse] -workspace.recipe = [default | file | inline | url] -workspace.recipe.location = {} -workspace.name = “happy” -workspace.ram = 2048 - -# Something similar to a vagrant provisioner syntax -workspace.command.add = - -# Default = local directory -# Where to load the code for the workspace from -# A workspace can have multiple projects imported -project.importer = [directory | zip | git | svn] -project.location = http://github.com/eclipse/che -project.type = maven -project[2].importer = [directory | zip | git | svn] -``` -## Docker Syntax -Like most everything we do with Che, Chefiles are packaged and executed as Docker containers. You can run the Docker container directly. `${CURRENT_DIRECTORY}` must be an absolute directory and if you are using Docker for Windows, the format of the drive must be `/c/my/path`. -```text - docker run -it --rm --name chefile \ - -v /var/run/docker.sock:/var/run/docker.sock \ - -v "$CURRENT_DIRECTORY":"$CURRENT_DIRECTORY" \ - eclipse/che-dir \ - "${CURRENT_DIRECTORY}" < up | init | down > +/dockerfiles/cli/build.sh # Local file to build the image +/dockerfiles/cli/Dockerfile # Image definition, must FROM eclipse/che-base:nightly +/dockerfiles/cli/scripts # Contains additional commands in form of cmd_.sh +/dockerfiles/cli/scripts/entrypoint.sh # The entrypoint of the CLI container, with usage() method +/dockerfiles/cli/scripts/cli.sh # Defines CLI-specific product names & variables +/dockerfiles/cli/version # Contains version-specific data the CLI requires ``` -# Under the Covers -The Che CLI is a simplification provided for launching our various Docker containers. We provide Docker images for performing certain, repetitive tasks. You can use these containers directly. +You can add additional commands to the Che CLI beyond the base set of commands that are provided by adding a file of the name `cmd_.sh` into the `scripts` folder. Codenvy is an [example that adds additional commands](https://github.com/codenvy/codenvy/tree/master/dockerfiles/cli/scripts). -The full syntax for how to build and run each Docker image is provided in the Dockerfile for each one, which is maintained in our GitHub repository. Each of these images have `:latest`, `:nightly`, and `:` tags for the images on DockerHub. +The `version` folder has information that details the latest version and a sub-folder for each version that is available for installation. Each version subfolder has version-specific data that the CLI depends upon to create a manifest of Docker images that must be downloaded to support the product that is going to be run. When we generate a release of the Che CLI, we have our CI systems automatically update the `/version` folder with the version-specific information contained in a release. +## Puppet Templates +The Che CLI uses Puppet to generate OS-specific configuration files based upon environment variables set by the user either with `-e ` options on the command line, or by modifying their `che.env` file. We pass all of these values into Puppet and then run a puppet configuration utility across the files contained in the `/dockerfiles/init/modules` and `/dockerfiles/init/manifests` folder to take the templates contained within the `/init` module, marry them with user-specific variables, and then generate an instance-specific configuration in `/instance`. Puppet has logic constructs that allow us to generate different kinds of constructs with logic based upon the values provided by end users. -| Image>>>>>>>>>>>>>> | Description | `eclipse/che-dev` -| --- | --- | --- -| `eclipse/che-dir` | `eclipse/che-ip` | `eclipse/che-launcher`\n`eclipse/che` -| `eclipse/che-mount` | `eclipse/che-server` | `eclipse/che-test` -| An image that contains all of the libraries and utilties necessary to compile Che extensions and custom assemblies. | An image that enables the conversion of local directories into Che workspaces. Think of it as Vagrant, but for Che servers and workspaces. | An image that returns the IP address of your Docker daemon. Used by our various containers to discover their environment. -| An image that is responsible for launching `eclipse/che-server` with a proper configuration. Configuration of how to launch `eclipse/che-server` varies by the operating system, user defined environment variables, and Docker installation type.\n\nThe syntax for using this container is the same as documented at [Usage: Local](doc:usage-docker). | An image that synchornizes a remote Che workspace to a local path. | The Che server itself. Contains the application server and libraries to launch a single instance of Che. -| An image that performs smoke tests against Che servers by creating workspaces and projects to verify that the system's networking and other properties have been properly established. | Dockerfile | [Dockerfile](https://github.com/eclipse/che-dockerfiles/blob/master/che-dev/Dockerfile) -| [Dockerfile](https://github.com/eclipse/che-dockerfiles/blob/master/che-dir/Dockerfile) | [Dockerfile](https://github.com/eclipse/che-dockerfiles/blob/master/che-ip/Dockerfile) | [Dockerfile](https://github.com/eclipse/che-dockerfiles/blob/master/che-launcher/Dockerfile) -| [Dockerfile](https://github.com/eclipse/che-dockerfiles/blob/master/che-mount/Dockerfile) | [Dockerfile](https://github.com/eclipse/che/blob/master/dockerfiles/che-server/Dockerfile) | [Dockerfile](https://github.com/eclipse/che-dockerfiles/blob/master/che-test/Dockerfile) +This puppet-based approach allow us to simplify the outputs for end users and limit the locations where end users need to configure various parts of the system. One powerful example of this is that we generate two `docker-compose.yml` files from a single Puppet template. In the user's `/instance` folder is `docker-compose.yml` and `docker-compose-container.yml`. The first one is a configuration file that allows a user to run Docker compose for Che on their host. They can just `docker-compose up` in that folder. The second file is for running Docker compose from within a container, which is what the CLI does. The syntax of Docker compose changes in each of these scenarios as the files being referenced from within the compose syntax are different. In the `init` image, we have a single template for Docker Compose and then apply it in two configurations using Puppet. diff --git a/docs/_docs/setup/che-setup-config-docker.md b/docs/_docs/setup/che-setup-config-docker.md deleted file mode 100644 index 3d56e0f2d5..0000000000 --- a/docs/_docs/setup/che-setup-config-docker.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -tags: [ "eclipse" , "che" ] -title: Config: Docker -excerpt: "" -layout: docs -permalink: /:categories/config-docker/ ---- -Eclipse Che workspaces are based upon a Docker image. You can either pull that image from a public registry, like Docker Hub, or a private registry which is managed by yourself. 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. -# Proxy for Docker -If you are installing Eclipse Che behind a proxy and you want your users to create workspaces powered by images hosted at Docker Hub, then you will need to configure the Docker daemon used by Eclipse Che to [operate over a proxy](https://docs.docker.com/engine/admin/systemd/#http-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. Modify the `che.properties` to configure your private registry: -```text -# Docker registry configuration. -# Note that you can configure many registries with different names. -#docker.registry.auth.your_registry_name.url=https://index.docker.io/v1/ -#docker.registry.auth.your_registry_name.username=user-name -#docker.registry.auth.your_registry_name.password=user-password - -# You can add as many registries as you need, e.g.: -docker.registry.auth.registry1.url -docker.registry.auth.registry2.url -\ -``` -Registries added in User Dashboard override registries added to `che.properties`. -# 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. - -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. -```text -# Syntax -FROM /: - -# Where repository is the hostname:port of your registry: -FROM my.registry.url:9000/image:latest\ -``` -To add a private registry, perform steps documented above (either adding a registry to global configuration or in User Dashboard). -#### Custom Images -To get 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`. - - -# Custom Dockerfiles -Within Che, your workspaces are powered by a set of runtime environments. The default runtime is Docker. You can provide custom Dockerfiles or images that you author, which are used to power the workspaces used by your users. - -You can: -1. Create a custom ready-to-go stack, which has a reference to your custom image and registry. Or: -2. Users can create a custom recipe when creating a workspace that references your registry. - -## Provide Users Your Own Stack With Custom Dockerfile Recipe -See [Stacks](doc:stacks). -See [Templates](doc:templates). - -## Users Create Custom Stack -When creating a workspace within Che, the user can select custom stack in the user dashboard. Your users can paste Dockerfile syntax which will be used to create a Docker image that is then used to create a runtime container for your workspace. The Dockerfile can reference base images at DockerHub or at a private registry. - -## Privileged Mode -By default, Che workspaces powered by a Docker container are not configured with Docker privileged mode. Privileged mode is necessary if you want to enable certain features such as Docker in Docker. There are many security risks to activating this feature - please review the various issues with blogs posted online. - -```text -# Activate your Che installation with priviliged mode -machine.docker.privilege_mode=true\ -``` - -# Mirroring Docker Hub diff --git a/docs/_docs/setup/che-setup-config-proxies.md b/docs/_docs/setup/che-setup-config-proxies.md deleted file mode 100644 index 2f0ea4a02c..0000000000 --- a/docs/_docs/setup/che-setup-config-proxies.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -tags: [ "eclipse" , "che" ] -title: Config: Proxies -excerpt: "Configure Che workspaces to operate over a proxy." -layout: docs -permalink: /:categories/config-proxies/ ---- -Your users may need their workspaces to operate over a proxy to the Internet. Che has three dependencies to the Internet: -1. Docker, in order to download Docker images from DockerHub. -2. Importers, in order to clone sample projects or source code at an external repository to mount into a workspace. -2. Workspaces created by users, which have their own internal operating system. Users that want to reach the Internet from within their workspace, such as for maven or npm, also need a proxy configuration. -# Installation Proxies -The Vagrant installer downloads software from the Internet. The steps to configure Vagrant to work over a proxy are provided in the [Usage: Vagrant](doc:usage) docs. If you plan to run Che as a Docker container, then your local system must have Docker configured to work over a proxy. The steps to configure that are on this page. - -The Vagrant installer allows you to configure proxies from within the `Vagrantfile` and we automated the internal configuration of the VM and Che server. It's fast and painless. The remaining instructions on this page will help you configure Che server to work over a proxy if you are setting up a server of your own. -# Docker Over Proxy -When a user creates a workspace, we will perform `docker pull`. This command will communicate with Docker Hub. You need to configure the [Docker daemon to communicate over a proxy](https://docs.docker.com/engine/admin/systemd/#http-proxy). -# Importers Over Proxy -When a user creates a project from a template or sample, we clone that source code from a Git or Subversion repository. You need to configure the operating system that the Che server is running on to run over a proxy. - -[Linux](http://www.cyberciti.biz/faq/linux-unix-set-proxy-environment-variable/) -[Mac](http://kb.netgear.com/app/answers/detail/a_id/25191/~/configuring-tcp%2Fip-and-proxy-settings-on-mac-osx) -[Windows](http://windows.microsoft.com/en-us/windows/change-internet-explorer-proxy-server-settings#1TC=windows-7) -# Proxies for Che Workspaces -After a workspace is created, the user will be within a Docker container that has its own operating system. This operating system must also be configured to work over a proxy. Set the proxy for your workspaces within the `che.properties` file. -```ruby -# Available starting in Che 4.2 -# Set these values in che.properties and restart the server -http.proxy=://:@: -https.proxy=://:@:\ -``` diff --git a/docs/_docs/setup/che-setup-config-security.md b/docs/_docs/setup/che-setup-config-security.md deleted file mode 100644 index b58ac41ae9..0000000000 --- a/docs/_docs/setup/che-setup-config-security.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -tags: [ "eclipse" , "che" ] -title: Config: Security -excerpt: "" -layout: docs -permalink: /:categories/config-security/ ---- -Eclipse Che is designed as a single identity system to be used by an individual or small team working in a trusted environment. The following outlines some of the security capabilities and known gaps in Che. - -# Securing Che Ports -Firewall rules can be added to prevent access to ports that shouldn't be externally accessible. Refer to [network topology docs](https://eclipse-che.readme.io/docs/networking#topology) for additional information on ports. - -When a user requires access to Che server remotely, outside of the local network/localhost, firewall rules can be setup to allow only certain ip-addresses access to Che server ports mention earlier. -# Limiting Che Ports -Eclipse Che uses Docker to power its workspaces. Docker uses the [ephemeral port range](https://en.wikipedia.org/wiki/Ephemeral_port) when exposing ports for services running in the container. So when a Tomcat server is started on port 8080 inside a Che workspace Docker automatically selects an available port from the ephemeral range at runtime to map to that Tomcat instance. - -Docker will select its ports from anywhere in the ephemeral range. If you wish to reduce the size of the ephemeral range in order to improve security you can do so, however, keep in mind that each Che workspace will use at least 2 ports plus whatever ports are required for the services the user adds to their workspace. - -Limiting the ephemeral range can only be done at the host level - you can read more about it (and some of the risks in doing so) here: http://www.ncftp.com/ncftpd/doc/misc/ephemeral_ports.html - -To change the ephemeral range: - * On Linux: http://www.ncftp.com/ncftpd/doc/misc/ephemeral_ports.html#Linux - * On Windows: http://www.ncftp.com/ncftpd/doc/misc/ephemeral_ports.html#Windows -# Securing a Workspace from the Che Host -Exposing host file system files/folders through volume mounts such as environment variable `CHE_WORKSPACE_VOLUME` and giving workspace/docker container privileged rights using Che configuration property `machine.docker.privilege_mode=true` could allow workspaces/docker containers to effect the host operating system. - -These options are useful for certain development situations but should be minimized to increase security to the host system whenever possible. -# Workspace Permissions -Eclipse Che is a single identity system. All users accessing a Che server share an identity and user preferences. There are no identity-based permissions since all users share the same identity. Users have access and control over all workspace environments. - -For a simple separation of workspaces for small development teams, without requiring workspace permissions, administrators can create separate Che server for each user. Each server, if ran on same host, would need to be setup on different ports using the `CHE_PORT` environment variable, different names using the `CHE_SERVER_CONTAINER_NAME` environment variable and different data/configuration folders using environment variable `CHE_CONF_FOLDER` and `CHE_DATA_FOLDER`. With this configuration there is no synchronization of workspaces or configuration between these instances - workspaces would need to be exported/imported from Che server to Che server manually. -```shell -docker run --rm -t --env CHE_PORT=8080 \ - --env CHE_SERVER_CONTAINER_NAME=che-server-user1 \ - --env CHE_CONF_FOLDER=/home/user1/che/conf \ - --env=CHE_DATA_FOLDER=/home/user1/che/ \ - -v /var/run/docker.sock:/var/run/docker.sock eclipse/che start - -docker run --rm -t --env CHE_PORT=8081 \ - --env CHE_SERVER_CONTAINER_NAME=che-server-user2 \ - --env CHE_CONF_FOLDER=/home/user2/che/conf \ - --env=CHE_DATA_FOLDER=/home/user2/che/ \ - -v /var/run/docker.sock:/var/run/docker.sock eclipse/che start - -#Setup firewall rules for ports 8080 and 8081 to only allow certain ipaddress access.\ -``` -Codenvy provides an implementation of Eclipse Che that is multi-tenant, multi-user with distributed access and permissions controls for teams. Each user has a different login which enables access controls, workspace collaboration, and other forms of sharing. Learn more at [https://codenvy.com/getting-started/](https://codenvy.com/getting-started/). -# Authenticated Access -The Che server itself is unauthenticated. Che is extensible allowing different dashboard front ends or proxies to implement authenticated access to the Che server. Bitnami's deployment of Eclipse Che includes an authenticated front-end implemented as a proxy. Many users deploy nginx in front of Che to provide an authentication layer within the system. - -Bitnami requires an existing account with cloud providers such as Google, Amazon AWS, or Microsoft Azure which may require monthly service charges from cloud providers. Refer to [Usage: Private Cloud](doc:usage-bitnami) for additional information. - -Codenvy also provides an implementation of Eclipse Che that has multi-user and multi-tenant capabilities. -# HTTPS -HTTPS is not provided by Eclipse Che. It would require a more complex architecture with multi-service deployments, making Che more challenging for developers and small teams to use. diff --git a/docs/_docs/setup/che-setup-config.md b/docs/_docs/setup/che-setup-config.md deleted file mode 100644 index 122d2fb255..0000000000 --- a/docs/_docs/setup/che-setup-config.md +++ /dev/null @@ -1,209 +0,0 @@ ---- -tags: [ "eclipse" , "che" ] -title: Configuration -excerpt: "Configure Che to bend to your will." -layout: docs -permalink: /:categories/config/ ---- -There is a lot you can do with Eclipse Che by changing its configuration. You can do this in three ways depending on how you interact with Che: -1. [Che CLI](https://eclipse-che.readme.io/docs/configuration-bdm-alternative#configure-che-using-the-che-cli): The CLI makes it easy to change any property. -2. [Che Launcher Environment Variables](https://eclipse-che.readme.io/docs/usage-docker-server#section-pass-che-command-line-options): You can change properties in Che by passing environment variables into the commands in the che launcher. -3. [Che Server Properties File](https://eclipse-che.readme.io/docs/configuration-bdm-alternative#configure-che-using-the-che-server): Che uses a properties file that can be altered directly if you're not using the CLI or launcher. This method is not recommended as it's the most error prone and complicated. -#### Eclipse Che Properties File -Throughout this document we reference the embedded `che.properties` file. You can [view this file and its defaults](https://github.com/eclipse/che/blob/08344fe62ebedfaa199e3258279b29acec7c88f8/assembly/assembly-wsmaster-war/src/main/webapp/WEB-INF/classes/codenvy/che.properties) in our repo. - - -# Configure Che Using the CLI -If you are using the [Che CLI](https://eclipse-che.readme.io/docs/che-cli) to start / stop Che, you can configure the `che-launcher` and `che-server` through environment variables. This is the preferred and simplest way to configure Che. - -Some values configure the CLI, some the `che-launcher`, and others the Che server. The CLI will also generate a one-time use `che.properties` from any parameters provided as environment variables. - -## Environment Variables -You can set environment variables that will affect the behavior of the CLI. These values are also used to configure how the `che-launcher` will be called and passed along as an input into the `che-launcher`. You can also [set a Che CLI profile](https://eclipse-che.readme.io/docs/che-cli#profiles) which will store a set of environment variables for use during other calls so that you can have multiple sets of configurations. - - -| Variable | Description | Defaults>>>>>>>>>>> -| --- | --- | --- -| `CHE_PORT` | External port of Che server. | `8080` -| `CHE_HOSTNAME` | `CHE_CONF_FOLDER` | `CHE_RESTART_POLICY` -| `CHE_USER` | External hostname of Che server. Only need to set if admin is managing over hostname. Changing this should be rare. | Varies by OS, but is typically `localhost`. -| Folder where custom `che.properties` located. | `null` | Che server restart policy if exited. See [Docker restart policies](https://docs.docker.com/engine/reference/commandline/run/#/restart-policies-restart) for all options. -| `no` | User ID of the Che server within its container. | `root` -| `CHE_LOCAL_BINARY` | The path to a Che assembly that is on your host to be used instead of the binary contained within the `che-server` image. | `/home/user/che` -| `CHE_VERSION` | Che server version to boot. Can be any valid [Che tag](https://github.com/eclipse/che/tags). Set to `nightly` to get the nightly images and builds of Che. | `latest` -| `CHE_SERVER_CONTAINER_NAME` | Changes the pretty-name of the container used to start the Che server. Change the name if you want to have multiple Che servers running as containers at the same time. | `che-server` -| `CHE_DATA_FOLDER` | Folder where user workspaces and Che preferences are saved. | `/home/user/che` -| `CHE_LOG_LEVEL` | Logging level of output for Che server. Can be `debug` or `info`. | `info` -| `CHE_LAUNCHER_IMAGE_NAME`\n`CHE_SERVER_IMAGE_NAME`\n`CHE_FILE_IMAGE_NAME`\n`CHE_MOUNT_IMAGE_NAME`\n`CHE_TEST_IMAGE_NAME` | Che uses various Docker images as utilities. Each image provides a different capability and is when launched as a container, given a container name. You can change the image names if you want to use one that you have built locally | `eclipse/che`\n`eclipse/che-server`\n`eclipse/che-file`\n`eclipse/che-mount`\n`eclipse/che-test` -| `CHE_IS_INTERACTIVE` | Set to `false` if you want the CLI to work in environments where there is no interactivivity available, such as part of a provisioner within Vagrant. | `true` -| `CHE_PRODUCT_NAME`\n`CHE_MINI_PRODUCT_NAME` | Sets the miniature and full product names used by the utilities in their output to the console. | `ECLIPSE CHE`\n`che` -| `CHE_HOST_IP` | IP address 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. -| `CHE_IS_PSEUDO_TTY` | Set to 'false' if you want the CLI to work without a PSEUDO_TTY, necessary for products like Jenkins. | `true` -| `CHE_DEBUG_SERVER` | If `true`, then will launch the Che server with JPDA activated so that you 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 `JPDA_SUSPEND` flag for Tomcat running the Che server. Used for advanced internal debugging of extensions. | `false` -| `CHE_DOCKER_MACHINE_HOST_EXTERNAL` | The hostname a browser should use to ping a workspace, if that workspace is not directly pingable by the browser. The default configuration will have the browser use the same hostname and IP address to reach the Che server and each workspace. In some cases, like Docker for Mac which is in a VM, the Che server can use an internal IP to reach the workspace, while the browser needs to use a separate, external hostname. It would be rare to change this. | `localhost` if on Docker for Windows or Mac. Otherwise, `\\`. -| `CHE_EXTRA_VOLUME_MOUNT` | Folder(s) to mount from your host into the workspace. Each mount is seperated by a semicolon `;`. \nExample:\n`~/.ssh:/home/user/.ssh;~/.m2:/home/user/.m2` | `null` -| `CHE_UTILITY_VERSION` | `null` | The version of the che utility to use. - -## One Time Use Properties -There are a number of internal properties that define how the Che server will operate. These are typically provided in a `che.properties` file. If you are using the CLI, you can provide a one-time use `che.properties` file by defining additional environment variables. The CLI will create this file and pass it along to the launcher and server. - -Any variable with the format `CHE_PROPERTY_=` will be configured into property value. A single underscore `_` will be converted into a period `.`. A double underscore `__` will be converted into a single underscore `_`. For example: -``` -# This environment variable: -export CHE_PROPERTY_machine_ws__agent_max__start__time__ms=1000 - -# Is placed into the temporary che.properties as: -machine.ws_agent.max_start_time_ms=1000 -``` - -## Custom Properties File -Eclipse Che has an embedded `che.properties` file [which provides a set of defaults](https://github.com/eclipse/che/blob/08344fe62ebedfaa199e3258279b29acec7c88f8/assembly/assembly-wsmaster-war/src/main/webapp/WEB-INF/classes/codenvy/che.properties). - -If you set the `CHE_LOCAL_CONF` environment variable, it will point to a directory name that can have any number of `*.properties` files. The values in these files will be passed along to the server instead of any values passed as environment variables. - -## Other Customizations -Additionally, there are a number of other areas you can customize inside Che through [System properties](https://eclipse-che.readme.io/docs/configuration#configure-che-using-the-che-server) -# Configure Che Using the Che Launcher -If you are using our `docker run eclipse/che start` or `docker run eclipse/che-launcher start` syntax, there is a smaller set of environment variables that are available and all `che.properties` must be provided in a custom file. See [Usage: Docker Launcher](https://eclipse-che.readme.io/docs/usage-docker) for specifics. - -Additionally, there are a number of other areas you can customize inside Che through [System properties](https://eclipse-che.readme.io/docs/configuration#configure-che-using-the-che-server) -# Configure Che Using the Che Server -This method is not recommended as it is the most error prone and complex. - -If you are using our `docker run eclipse/che-server` syntax, you can customize the Che server by passing in a `che.properties` file and with some limited command line options. See [Usage: Docker Server](https://eclipse-che.readme.io/docs/usage-docker-server#section-pass-che-command-line-options) for specifics. - -Additionally, there are a number of other areas you can customize inside Che through [System properties](https://eclipse-che.readme.io/docs/configuration#configure-che-using-the-che-server) -# Custom Workspace Properties -Each workspace is a separate runtime, and has at least one development agent that runs as a miniaturized Che server within the workspace. That agent has its own properties that can be configured as well. If you are authoring custom workspace extensions that are deployed within Che's agent in the workspace, you can customize. - -Properties saved in `CHE_CONF_FOLDER\plugin-conf\` folder will be mounted into the runtime for each workspace created by Che. The Che development agent that runs within the workspace will load these properties when it boots. -# System Properties -Whether you are using the CLI, Che launcher, or Che server, most internal Che configuration is done with a property, usually loaded by the server as a `che.properties` file. Che has an embedded `che.properties` file [which provides a set of defaults](https://github.com/eclipse/che/blob/08344fe62ebedfaa199e3258279b29acec7c88f8/assembly/assembly-wsmaster-war/src/main/webapp/WEB-INF/classes/codenvy/che.properties). - -You can customize the properties by: -1: If using the Che CLI, by providing a custom `che.properties` by setting the `CHE_CONF_FOLDER` variable or by providing individual environment variables in the form of `CHE_PROPERTY_=`. [See more](https://eclipse-che.readme.io/docs/configuration#section-one-use-properties). -2: If using the Che launcher, [set an environment variable](https://eclipse-che.readme.io/docs/usage-docker#environment-variables) or by providing a [`che.properties` file with custom properties](https://eclipse-che.readme.io/docs/usage-docker#add-custom-eclipse-che-properties). -3: If using the Che server from our ZIP, edit `/conf/che.properties` before starting Tomcat or passing a `-D` option to Che's JVM when starting Che. - -## Server Configuration - -Che stores internal configuration and metadata in storage. You can change the default location where this information is saved. Note that if you are using our Docker launcher, the Che server is running in a container, and this storage is within that container. -```json -# Folder where Che will store internal data objects -che.conf.storage=${che.home}/storage\ -``` -If you are using the Che CLI or Che launcher, setting `CHE_DATA_FOLDER` or `CHE_PROPERTY_che_conf_storage` will also update this property. - -## Workspace Configuration - -### Storage -Che stores each workspace as a separate directory on a file system. -```json -# Path to workspace and project storage. -che.user.workspaces.storage=${che.home}/workspaces \ -``` -If you are using the Che CLI or Che launcher, setting `CHE_DATA_FOLDER` or `CHE_PROPERTY_che_user_workspaces_storage` will also update this property. - -### Other Workspace Options -```json -# Your projects are synchronized from the Che server into the machine running each -# workspace. This is the directory in the ws runtime where your projects are mounted. -che.machine.projects.internal.storage=/projects - -# Configures proxies used by runtimes powering workspaces -http.proxy= -https.proxy= -no_proxy= - -# Java command line options when starting our Che agent in workspace runtime -che.machine.java_opts=-Xms256m -Xmx2048m -Djava.security.egd=file:/dev/./urandom - -# Folder to mount from your host into the workspace. -machine.server.extra.volume - -# Workspace SSH connection timeouts. -machine.ssh.connection_timeout_ms=3000 - -# Pather for workspace logs form Che agents and other runtimes -machine.logs.location=${che.logs.dir}/machine/logs - -# RAM default for new workspace runtimes. -machine.default_mem_size_mb=1024\ -``` -## Stacks -[Stacks](https://eclipse-che.readme.io/docs/stacks) define the recipes used to create workspace runtimes. They appear in the stack library of the dashboard. You can create your own. -```json -# 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](doc: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. -```json -# Folder that contains JSON files with code templates and samples -project.template_description.location_dir=${che.home}/templates\ -``` -## GitHub oAuth -Refer to [GitHub using OAuth](https://eclipse-che.readme.io/docs/git#section-github-oauth) for configuration information. - -## GitLab oAuth -Refer to [GitHub using OAuth](https://eclipse-che.readme.io/docs/git#section-gitlab-oauth) for configuration information. - -## Docker in Docker -By default, Che has Docker privileged mode disabled. This prevents your workspace (which is a Docker container) from launching their own Docker containers. Activating privileged mode will allow you to do Docker-in-Docker. -```json -# If true, then all docker machines will start in privilege mode. -machine.docker.privilege_mode=false\ -``` -## Workspace Snapshots -In the IDE, 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. - -```json -# 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\ -``` - -### Start A Docker Registry -You can launch a private Docker registry with Docker. -```shell -# 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](https://docs.docker.com/registry/deploying/). - -### Add Your Registry To Che -```json -# Docker registry example. Uncomment to add a registry configuration. -# You can configure multiple registries with different names. -docker.registry.auth..url=https://index.docker.io/v1/ -docker.registry.auth..username= -docker.registry.auth..password= - -# Example -docker.registry.auth.url=http://localhost:5000 -docker.registry.auth.username=user1 -docker.registry.auth.password=pass -docker.registry.auth.email=user1@email.com - -# Or, save your snapshots to Docker Hub: -machine.docker.registry={namespace/repository} -docker.registry.auth.url=https://index.docker.io/v1 -docker.registry.auth.username={username} -docker.registry.auth.password={password} -docker.registry.auth.email=user1@email.com\ -``` diff --git a/docs/_docs/setup/che-setup-configuration.md b/docs/_docs/setup/che-setup-configuration.md new file mode 100644 index 0000000000..62c9f5c5e4 --- /dev/null +++ b/docs/_docs/setup/che-setup-configuration.md @@ -0,0 +1,295 @@ +--- +tags: [ "eclipse" , "che" ] +title: Configuration +excerpt: "Configure Eclipse Che to bend to your will..." +layout: docs +permalink: /:categories/configuration/ +--- +Configuration is handled by modifying `che.env` placed in the host folder volume mounted to `:/data`. This configuration file is generated during the `che init` phase. If you rerun `che init` in an already initialized folder, the process will abort unless you pass `--force`, `--pull`, or `--reinit`. + +Each variable is documented with an explanation and usually commented out. If you need to set a variable, uncomment it and configure it with your value. You can then run `che config` to apply this configuration to your system. `che start` also reapplies the latest configuration. + +You can run `che init` to install a new configuration into an empty directory. This command uses the `che/init:` Docker container to deliver a version-specific set of puppet templates into the folder. + +If you run `che config`, che runs puppet to transform your puppet templates into a che instance configuration, placing the results into `/che/instance` if you volume mounted that, or into a `instance` subdirectory of the path you mounted to `/che`. Each time you start che, `che config` is run to ensure instance configuration files are properly generated and consistent with the configuration you have specified in `che.env`. + +# Saving Configuration in Version Control +Administration teams that want to version control your che configuration should save `che.env`. This is the only file that should be saved with version control. It is not necessary, and even discouraged, to save the other files. If you were to perform a `che upgrade` we may replace these files with templates that are specific to the version that is being upgraded. The `che.env` file maintains fidelity between versions and we can generate instance configurations from that. + +The version control sequence would be: +1. `che init` to get an initial configuration for a particular version. +2. Edit `che.env` with your environment-specific configuration. +3. Save `che.env` to version control. +4. Setup a new folder and copy `che.env` from version control into the folder you will mount to `:/data`. +5. Run `che config` or `che start`. + +# Internal Configuration +We provide a complete list of user-configurable properties in the `che.env` file. However, there are additional internal Che server properties that can also be configured. When we start the `che-server` Docker container, it is configured with a `che.properties` file to define a variety of internal operational details. You can [view the default file](https://github.com/eclipse/che/blob/08344fe62ebedfaa199e3258279b29acec7c88f8/assembly/assembly-wsmaster-war/src/main/webapp/WEB-INF/classes/codenvy/che.properties) in our GitHub repo. + +You can override these properties or pass in new Che server properties by defining additional environment variables within `che.env`. The CLI will convert any `che.env` additional properties into custom `che.properties` that are passed into the server. + +Any variable with the format `CHE_PROPERTY_=` will be configured into property value. A single underscore `_` will be converted into a period `.`. A double underscore `__` will be converted into a single underscore `_`. For example: +```shell +# This environment variable: +CHE_PROPERTY_machine_ws__agent_max__start__time__ms=1000 + +# Is sent to the Che server as: +machine.ws_agent.max_start_time_ms=1000 +``` + +# Logs and User Data +When Che initializes itself, it stores logs, user data, database data, and instance-specific configuration in the folder mounted to `:/data/instance` or an `instance` subfolder of what you mounted to `:/data`. + +Che's containers save their logs in the same location: +```shell +/instance/logs/che/2016 # Server logs +/instance/logs/che/che-machine-logs # Workspace logs +``` + +User data is stored in: +```shell +/instance/data/che # Project backups (we synchronize projs from remote ws here) +``` + +Instance configuration is generated by Che and is updated by our internal configuration utilities. These 'generated' configuration files should not be modified and stored in: +```shell +/instance/che.ver.do_not_modify # Version of che installed +/instance/docker-compose-container.yml # Docker compose to launch Che from within a container +/instance/docker-compose.yml # Docker compose to launch Che from the host without contianer +/instance/config # Configuration files for Che which are volume mounted into containers +``` + +# oAuth +You can configure Google, GitHub, Microsoft, BitBucket, or WSO2 oAuth for use when users perform git operations. + +Che is shipped with a preconfigured GitHub oAuth application for the `che.onprem` hostname. To enable GitHub oAuth, add `che_HOST=che.onprem` to `che.env` and restart. If you have a custom DNS, you need to register a GitHub oAuth application with GitHub's oAuth registration service. You will be asked for the callback URL, which is `http:///api/oauth/callback`. You will receive from GitHub a client ID and secret, which must be added to `che.env`: +``` +che_GITHUB_CLIENT_ID=yourID +che_GITHUB_SECRET=yourSecret +``` + +Google oAuth (and others) are configured the same: +``` +che_GOOGLE_CLIENT_ID=yourID +che_GOOGLE_SECRET=yourSecret +``` + +#### GitHub oAuth +Refer to [GitHub using OAuth](https://eclipse-che.readme.io/docs/git#section-github-oauth) for configuration information. + +#### GitLab oAuth +Refer to [GitHub using OAuth](https://eclipse-che.readme.io/docs/git#section-gitlab-oauth) for configuration information. + + +# Stacks +[Stacks](https://eclipse-che.readme.io/docs/stacks) define the recipes used to create workspace runtimes. They appear in the stack library of the dashboard. You can create your own. +```shell +# 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](doc: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. +```json +# 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 :/data \ + -v :/repo \ + eclipse/che-cli: [COMMAND] +``` +Dev mode will use files from your host repository: + +1. During the `che config` phase, the source repository's `/dockerfiles/init/modules` and `/dockerfiles/init/manifests` will be used instead of the ones that are included in the `eclipse/che-init` container. +2. During the `che start` phase, a local assembly from `assembly/assembly-main/target/` is mounted into the `eclipse/che-server` runtime container. You must `mvn clean install` the `assembly/assembly-main/` folder prior to activating development mode. + +To activate jpda suspend mode for debugging Che server initialization, in the `che.env`: +``` +CHE_DEBUG_SUSPEND=true +``` +To change che debug port, in the `che.env`: +``` +CHE_DEBUG_PORT=8000 +``` + +# Hostname +The IP address or DNS name of where the Che endpoint will service your users. If you are running this on a local system, we auto-detect this value as the IP address of your Docker daemon. On many systems, especially those from cloud hosters like DigitalOcean, you may have to explicitly set this to the external IP address or DNS entry provided by the provider. You can edit this value in `che.env` and restart Che, or you can pass it during initialization: + +``` +docker run -e CHE_HOST= eclipse/che-cli: start +``` + +# Workspace Limits +You can place limits on how users interact with the system to control overall system resource usage. You can define how many workspaces created, RAM consumed, idle timeout, and a variety of other parameters. See "Workspace Limits" in `che.env`. + +You can also set limits on Docker's allocation of CPU to workspaces, which may be necessary if you have a very dense workspace population where users are competing for limited physical resources. + +# Docker +Eclipse Che workspace runtimes are powered by one or more Docker containers. When a user creates a workpace, they do so from a [stack]() which includes a Dockerfile or reference to a Docker image which will be used to create the containers for the workspace runtimes. Che stacks can pull that image from a public registry, like DockerHub, or a private registry. Images in a registry can be publicly visible or private, which require user credentials to access. You can also set up a private registry to act as a mirror to Docker Hub. And, if you are running Eclipse Che behind a proxy, you can configure the Docker daemon registry to operate behind a proxy. + +### Private 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`: +```shell +# 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 /` 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. +```text +# Syntax +FROM /: + +# 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. +```shell +# 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](https://docs.docker.com/registry/deploying/). + +### Custom Dockerfiles and Composefiles for Workspaces +Within Che, your workspaces are powered by a set of runtime environments. The default runtime is Docker. Typically, admins have pre-built images in DockerHub or another registry which are pulled when the workspace is created. You can optionally provide custom Dockerfiles (or let your users provide their own Dockerfiles), which will dynamically create a workspace image when a user creates a new workspace. + +To use your custom Dockerfiles, you can: +1. Create a [custom stack], which includes a [recipe] with your Dockerfile. +2. Or, users can create a custom recipe when creating a workspace that references your registry. + +### Privileged Mode +Docker's privileged mode allows a container to have root-level access to the host from within the container. This enables containers to do more than they normally would, but opens up security risks. You can enable your workspaces to have privileged mode, giving your users root-level access to the host where Che is running (in addition to root access of their workspace). Privileged mode is necessary if you want to enable certain features such as Docker in Docker. + +By default, Che workspaces powered by a Docker container are not configured with Docker privileged mode. There are many security risks to activating this feature - please review the various issues with blogs posted online. + +```shell +# Update your che.env: +CHE_DOCKER_PRIVILEGED_MODE=true +``` + +### Mirroring Docker Hub +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: +1. Activate Docker's prvileged mode, where your user workspaces have access to the host. +2. Configure Che to setup workspaces to volume mount your host Daemon + +These two tactics will allow user workspaces to perform `docker` commands from within their workspace to create and work with Docker containers that will be outside the workspace. In other words, this makes your user's workspace feel like their laptop where they would normally be performing `docker build` and `docker run` commands. + +You will need to make sure that your user's workspaces are powered from a stack that has Docker installed inside of it. Che's default images do not have Docker installed, but we have sample stacks (see the Che in Che stack). + +### 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 +```shell +# 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 ` 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. +```shell +# 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 \ No newline at end of file diff --git a/docs/_docs/setup-alternatives/che-setupalt-docker-server.md b/docs/_docs/setup/che-setup-docker.md similarity index 89% rename from docs/_docs/setup-alternatives/che-setupalt-docker-server.md rename to docs/_docs/setup/che-setup-docker.md index 5e386636b9..f379360335 100644 --- a/docs/_docs/setup-alternatives/che-setupalt-docker-server.md +++ b/docs/_docs/setup/che-setup-docker.md @@ -1,22 +1,13 @@ --- tags: [ "eclipse" , "che" ] -title: Usage: Docker Server -excerpt: "Run the Che server inside a Docker image with workspaces mounted on your host." +title: Docker Installation +excerpt: "Run the Che server with Docker bypassing the CLI with workspaces mounted on your host." layout: docs -permalink: /:categories/docker-server/ +permalink: /:categories/docker/ --- -#### Requires Eclipse Che 5.0.0-M6+ -Starting in Eclipse Che M6 release, we altered the structure of the Che container. The launching syntax is simplified to consolidate data into a single folder and to use environment variables more. This syntax will not work with the eclipse/che-server:latest and you may have to use eclipse/che-server:nightly or eclipse/che-server:5.0.0-M6 or eclipse/che-server:5.0.0-latest to get the right version. +You can run the Che server directly by launching a Docker image. This approach bypasses the CLI, which 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. -Eclipse Che has an [image available within Docker Hub](https://hub.docker.com/r/eclipse/che-server/). This image only runs the Che server and requires your Docker clients to have additional configuration that varies by operating system. - -!!!NOTE: This is a new syntax that is not available on Docker Hub yet. To get this new approach, you need to build a eclipse/che-server:nightly directly. Please see this [pull request](https://github.com/eclipse/che/pull/2786) for details on how to run it. - -The preferred technique for running Eclipse Che is with our [Usage: Docker](doc:usage-docker) launcher which simplifies the syntax and provides a consistent client that works on any operating system. There are quirks to running the Che server container on Windows and Mac, so the `che-launcher` is encouraged. - -As of 5.0.0-M7, this syntax has changed. The che-server container provides an error message if you try to use it with the old syntax. # Run the Image - ```shell # Run the latest released version of Che # Replace with any host folder diff --git a/docs/_docs/setup/che-setup-getting-started.md b/docs/_docs/setup/che-setup-getting-started.md index b2c3b032a3..d58a49dbff 100644 --- a/docs/_docs/setup/che-setup-getting-started.md +++ b/docs/_docs/setup/che-setup-getting-started.md @@ -5,121 +5,267 @@ excerpt: "" layout: docs permalink: /:categories/getting-started/ --- -# How to Get Help -**Support:** If the unthinkable happens, or you have a question, you can post [issues on our GitHub page](https://github.com/eclipse/che/issues). Please follow the [guidelines on issue reporting](https://github.com/eclipse/che/blob/master/CONTRIBUTING.md). +Eclipse Che is a developer workspace server and cloud IDE. You install, run, and manage Eclipse Che with Docker. -**Documentation:** We put a lot of effort into our docs. Please add suggestions on areas for improvement. -# 0. Pre-Reqs -To run Eclipse Che, you need: -1. Docker 1.8+ for [Linux](https://docs.docker.com/engine/installation/), [Windows](https://docs.docker.com/engine/installation/windows/) or [Mac](https://docs.docker.com/engine/installation/mac/). -2. Bash. +### Download +This is the administration guide for the on-premises installation of Eclipse Che. This document discusses the installation, configuration, and operation of Che that you host on your own hardware or IaaS provider. -If you are using boot2docker for Windows or Mac, environment variables must be set in each terminal session. +You can get a hosted version of Eclipse Che with Codenvy at [codenvy.io](http://codenvy.io). -Once Docker and bash are installed: +# How to Get Help +### Support: +If the unthinkable happens, or you have a question, you can post [issues on our GitHub page](https://github.com/eclipse/che/issues). Please follow the [guidelines on issue reporting](https://github.com/eclipse/che/blob/master/CONTRIBUTING.md) and provide: +* your OS distribution and version +- output of `docker version` command +- output of `docker info` command +- the full `docker run ...` syntax you used on the command line +- the output of `cli.log` + +### Documentation: +We put a lot of effort into our docs. Please add [suggestions on areas for improvement]() with a pull request. + +# Quick Start +On any computer with Docker 1.11+ installed: +```shell +# Interactive help +docker run -it eclipse/che-cli start + +# Or, full start syntax where is a local directory +docker run -it --rm -v /var/run/docker.sock:/var/run/docker.sock -v :/data eclipse/che-cli start +``` + +# Operate Che +```shell +# Start Eclipse Che with user data saved on Windows in c:\tmp +docker run -it --rm -v /var/run/docker.sock:/var/run/docker.sock -v /c/tmp:/data eclipse/che-cli start +INFO: (che cli): Loading cli... +INFO: (che cli): Checking registry for version 'nightly' images +INFO: (che config): Generating che configuration... +INFO: (che config): Customizing docker-compose for running in a container +INFO: (che start): Preflight checks + port 8080 (http): [AVAILABLE] + +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: nightly +INFO: (che start): Use: http://:8080 +INFO: (che start): API: http://:8080/swagger + +# Stop Che +docker run eclipse/che-cli stop + +# Restart Che +docker run eclipse/che-cli restart + +# Run a specific version of Che +docker run eclipse/che-cli: start + +# Get help +docker run eclipse/che-cli + +# If boot2docker on Windows (rare), mount a subdir of `%userprofile%` to `:/data`. For example: +docker run -v /c/Users/tyler/che:/data eclipse/che-cli start + +# If Che will be accessed from other machines add your server's external IP +docker run -e CHE_HOST= eclipse/che-cli start +``` + +# Develop with Che +Now that Che is running there are a lot of fun things to try: +- Become familiar with Che through [one of our tutorials](). +- [Import a project](https://eclipse-che.readme.io/docs/import-a-project) and setup [git authentication](). +- Use [commands]() to build and run a project. +- Create a [preview URL]() to share your app. +- Setup a [debugger](). +- Create reproducible workspaces with [chedir](). +- Create a [custom runtime stack](https://eclipse-che.readme.io/docs/stacks). + +# Syntax +``` +USAGE: + docker run -it --rm eclipse/che-cli: [COMMAND] + +MANDATORY DOCKER PARAMETERS: + -v :/data Where user, instance, and log data saved + +OPTIONAL DOCKER PARAMETERS: + -e CHE_HOST= IP address or hostname where che will serve its users + -e CHE_PORT= Port where che will bind itself to + -v :/data/instance Where instance, user, log data will be saved + -v :/data/backup Where backup files will be saved + -v :/repo che git repo to activate dev mode + -v :/sync Where remote ws files will be copied with sync command + -v :/unison Where unison profile for optimzing sync command resides + +COMMANDS: + action Start action on che instance + backup Backups che configuration and data to /data/backup volume mount + config Generates a che config from vars; run on any start / restart + destroy Stops services, and deletes che instance data + download Pulls Docker images for the current che version + help This message + info Displays info about che and the CLI + init Initializes a directory with a che install + offline Saves che Docker images into TAR files for offline install + restart Restart che services + restore Restores che configuration and data from /data/backup mount + rmi Removes the Docker images for , forcing a repull + ssh [machine-name] SSH to a workspace if SSH agent enabled + start Starts che services + stop Stops che services + sync Synchronize workspace with current working directory + test Start test on che instance + upgrade Upgrades che from one version to another with migrations and backups + version Installed version and upgrade paths +``` + +# Pre-Reqs +### Hardware: +* 1 cores +* 256MB RAM +* 300MB disk space + +Che requires 300 MB storage and 256MB RAM for internal services. The RAM, CPU and storage resources required for your users' workspaces are additive. Che Docker images consume ~300MB 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 all Docker 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 1.11+ + +The 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 the 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 +``` + +Verify that Docker is installed with: ```shell # Should print "Hello from Docker!" docker run hello-world - -# Should open a bash shell (Windows too! - Docker installs Git Bash for Windows) -bash - -# Windows users may have to add Git Bash to their path in system environment variables -# set PATH=;%PATH% -set PATH=C:\Program Files\Git\bin\;%PATH% ``` -# 1. Get the Eclipse Che CLI +Sometimes Fedora and RHEL/CentOS users will encounter issues with SElinux. Try disabling selinux with `setenforce 0` and check if resolves the issue. If using the latest docker version and/or disabling selinux does not fix the issue then please file a issue request on the [issues](https://github.com/eclipse/che/issues) page. + +#### Ports +The default port required to run Che is `8080`. Che performs a preflight check when it boots to verify that the port is available. You can pass `-e CHE_PORT=` in Docker portion of the start command to change the port that Che starts on. + +#### Internet Connection +You can install Che while connected to a network or offline, disconnected from the Internet. If you perform an offline intallation, you need to first download a Che assembly while in a DMZ with a network connection to DockerHub. + +# Versions +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 of Che: + +| 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 a `/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 down 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. + +# Volume Mounts +We use volume mounts to configure certain parts of Che. The presence or absence of certain volume mounts will trigger certain behaviors in the system. For example, you can volume mount a Che source git repository with `:/repo` to activate development mode where we start Che's containers using source code from the repository instead of the software inside of the default containers. + +At a minimum, you must volume mount a local path to `:/data`, which will be the location that Che installs its configuration, user data, version and log information. Che also leaves behind a `cli.log` file in this location to debug any odd behaviors while running the system. In this folder we also create a `che.env` file which contains all of the admin configuration that you can set or override in a single location. + +You can also use volume mounts to override the location of where your user or backup data is stored. By default, these folders will be created as sub-folders of the location that you mount to `:/data`. However, if you do not want your `/instance`, and `/backup` folder to be children, you can set them individually with separate overrides. + +``` +docker run -it --rm -v /var/run/docker.sock:/var/run/docker.sock + -v :/data + -v :/data/instance + -v :/data/backup + eclipse/che-cli: [COMMAND] -```shell -sudo curl -sL https://raw.githubusercontent.com/eclipse/che/master/che.sh > /usr/local/bin/che -sudo chmod +x /usr/local/bin/che\ ``` -```shell -# You need both che.bat and che.sh -> curl -sL https://raw.githubusercontent.com/eclipse/che/master/che.sh > che.sh -> curl -sL https://raw.githubusercontent.com/eclipse/che/master/che.bat > che.bat +# Hosting +If you are hosting Che at a cloud service like DigitalOcean, `CHE_HOST` must be set to the server's IP address or its DNS. -# Add the files to your PATH -set PATH=;%PATH%\ +We will attempt to auto-set `CHE_HOST` by running an internal utility `docker run --net=host eclipse/che-ip:nightly`. This approach is not fool-proof. This utility is usually accurate on desktops, but 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 :/data + -e CHE_HOST= + eclipse/che-cli: [COMMAND] ``` -# 2. Start Che +# Proxy Installation +You can install and operate Che behind a proxy: +1. Configure each physical node's Docker daemon with proxy access. +2. Optionally, override workspace proxy settings for users if you want to restrict their Internet access. -```shell -# Change where workspaces are saved. Default = /home/user/che -# export CHE_DATA=/home/user/reginald +Before starting Che, configure [Docker's daemon for proxy access](https://docs.docker.com/engine/admin/systemd/#/http-proxy). If you have Docker for Windows or Docker for Mac installed on your desktop and installing Che, these utilities have a GUI in their settings which let you set the proxy settings directly. -# If Che will be accessed from other machines define your host IP -# export CHE_HOST_IP= +Please be mindful that your `HTTP_PROXY` and/or `HTTPS_PROXY` that you set in the Docker daemon must have a protocol and port number. Proxy configuration is quite finnicky, so please be mindful of providing a fully qualified proxy location. -# Start Eclipse Che -che start -INFO: ECLIPSE CHE: Starting launcher -INFO: ECLIPSE CHE: Already have image eclipse/che-server:nightly -INFO: ECLIPSE CHE: Starting container... -INFO: ECLIPSE CHE: Server logs at "docker logs -f che-server" -INFO: ECLIPSE CHE: Server booting... -INFO: ECLIPSE CHE: Booted and reachable -INFO: ECLIPSE CHE: http://192.168.99.100:8080 +If you configure `HTTP_PROXY` or `HTTPS_PROXY` in your Docker daemon, we will add `localhost,127.0.0.1,CHE_HOST` to your `NO_PROXY` value where `CHE_HOST` is the DNS or IP address. We recommend that you add the short and long form DNS entry to your Docker's `NO_PROXY` setting if it is not already set. -# Stop Eclipse Che -che stop - -# Update Eclipse Che to the nightly build -export CHE_VERSION=nightly -che update - -# List all Che CLI commands -che help +We will add some values to `che.env` that contain some proxy overrides. You can optionally modify these with overrides: +``` +CHE_HTTP_PROXY= +CHE_HTTPS_PROXY= +CHE_NO_PROXY=localhost,127.0.0.1, +CHE_HTTP_PROXY_FOR_WORKSPACES= +CHE_HTTPS_PROXY_FOR_WORKSPACES= +CHE_NO_PROXY_FOR_WORKSPACES=localhost,127.0.0.1, ``` -```shell -# If boot2docker, set workspace storage to a subdirectory of `%userprofile%`. -# If Docker for Windows on Windows 10, set to any directory. -# Docker is case sensitive and requires forward slashes without colons. -mkdir /c/Users/%userprofile%/ -set CHE_DATA=/c/Users/%userprofile%/ +The last three entries are injected into workspaces created by your users. This gives your users access to the Internet from within their workspaces. You can comment out these entries to disable access. However, if that access is turned off, then the default templates with source code will fail to be created in workspaces as those projects are cloned from GitHub.com. Your workspaces are still functional, we just prevent the template cloning. -# If Che will be accessed from other machines define your host IP -# set CHE_HOST_IP= +# Offline Installation +We support 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 DockerHub access. You can then move those files to a secure environment and start Che. -# Start Eclipse Che -che start -INFO: ECLIPSE CHE: Starting launcher -INFO: ECLIPSE CHE: Already have image eclipse/che-server:nightly -INFO: ECLIPSE CHE: Starting container... -INFO: ECLIPSE CHE: Server logs at "docker logs -f che-server" -INFO: ECLIPSE CHE: Server booting... -INFO: ECLIPSE CHE: Booted and reachable -INFO: ECLIPSE CHE: http://192.168.99.100:8080 +### 1. Save Che Images +While connected to the Internet, download Che's Docker images: +```shell +docker run eclipse/che-cli: offline +``` +The CLI will download images and save them to `/backup/*.tar` with each image saved as its own file. You can save these files to a differnet location by volume mounting a local folder to `:/data/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. -# Stop Eclipse Che -che stop +The default execution will download none of the optional stack images, which are needed to launch workspaces of a particular type. There are a few dozen stacks for different programming languages and some of them are over 1GB in size. It is unlikely that your users will need all of the stacks, so you do not need to download all of them. You can get a list of available stack images by running `eclipse/che-cli offline --list`. You can download a specific stack by running `eclipse/che-cli offline --image:` and the `--image` flag can be repeatedly used on a single command line. -# Update Eclipse Che to the nightly build -set CHE_VERSION=nightly -che update +### 2. Start Che In Offline Mode +Place the TAR files into a folder in the offline computer. If the files are in placed in a folder named `/tmp/offline`, you can run Che in offline mode with: -# List all Che CLI commands -che help +```shell +# Load the CLI +docker load < /tmp/offline/eclipse_che-cli:.tar + +# Start Che in offline mode +docker run -v /tmp/offline:/data/backup eclipse/che-cli: start --offline +``` +The `--offline` parameter instructs the Che CLI to load all of the TAR files located in the folder mounted to `/data/backup`. These images will then be used instead of routing out to the Internet to check for DockerHub. The preboot sequence takes place before any CLI functions make use of Docker. The `eclipse/che-cli start`, `eclipse/che-cli download`, and `eclipse/che-cli init` commands support `--offline` mode which triggers this preboot seequence. + +# Uninstall +```shell +# Remove your Che configuration and destroy user projects and database +docker run eclipse/che-cli: destroy [--quiet|--cli] + +# Deletes Che's images from your Docker registry +docker run eclipse/che-cli: rmi + +# Delete the Che CLI +docker rmi -f eclipse/che-cli ``` -#### Installing Behind a Proxy -If you are behind a proxy, you need to [configure your proxy settings](https://eclipse-che.readme.io/docs/configuration-proxies) for Docker and Eclipse Che. +# Licensing +Che is licensed with the Eclipse Public License. - -#### Configuration -Change Che's port, hostname, oAuth, Docker, git, and networking by setting [Eclipse Che properties](https://eclipse-che.readme.io/docs/usage-docker#environment-variables). - - -# 3. Develop with Che -Now that Che is running there are a lot of fun things to try: -- Become familiar with Che through [one of our tutorials](https://eclipse-che.readme.io/docs/get-started-with-java-and-che). -- [Import a project](https://eclipse-che.readme.io/docs/import-a-project) and setup [git authentication](https://eclipse-che.readme.io/docs/git). -- Use [commands](https://eclipse-che.readme.io/docs/commands) to build and run a project. -- Create a [preview URL](https://eclipse-che.readme.io/docs/previews) to share your app. -- Setup a [debugger](https://eclipse-che.readme.io/docs/debug). -- Experiment with [chedir](https://dash.readme.io/project/eclipse-che/docs/getting-started-chedir). -- Create a [custom stack](https://eclipse-che.readme.io/docs/stacks). +# Configuration +Change Che's port, hostname, oAuth, Docker, git, and networking by setting [Eclipse Che properties](). \ No newline at end of file diff --git a/docs/_docs/setup/che-setup-intro.md b/docs/_docs/setup/che-setup-intro.md index 6b3f87527c..202cb24c13 100644 --- a/docs/_docs/setup/che-setup-intro.md +++ b/docs/_docs/setup/che-setup-intro.md @@ -77,7 +77,8 @@ Workspace master extensions are deployed as services within the Che server. Once Workspace agent extensions are compiled with Che core libraries and also deployed within an embedded Che server that runs inside of each workspace machine. The Che server is injected into machines created and controlled by the central workspace master Che server. This embedded server hosts your workspace agent extensions and provides a communication bridge between the services hosted within Che and the machines that are hosting the project. -**About Machines**. When you develop with a desktop IDE, the workspace uses localhost as the execution environment for processes like build, run and debug. In a cloud IDE, localhost is not available, so the workspace server must generate the environments that it needs. These environments must be isolated from one another and scalable. We use Docker to generate containers that contain the software needed for each environment. Each workspace is given at least one environment, but users may create additional environments for each workspace if they want. Each container can have different software installed. Che installs different software into the machine based upon the project type. For example, a Java project will have the JDK, Git, and Maven installed. When a user is working within their Workspace, this container is booted by Che and the source code of the project is mounted within it. Developer actions like auto-complete and `mvn clean install` are processes that are executed within the container. Users can provide their own Dockerfiles that Che will build into images and extension developers can register Dockerfile templates associated with a project type. This allows Che to manage a potentially infinite number of environments while still giving users customization flexibility. +## Machines +When you develop with a desktop IDE, the workspace uses localhost as the execution environment for processes like build, run and debug. In a cloud IDE, localhost is not available, so the workspace server must generate the environments that it needs. These environments must be isolated from one another and scalable. We use Docker to generate containers that contain the software needed for each environment. Each workspace is given at least one environment, but users may create additional environments for each workspace if they want. Each container can have different software installed. Che installs different software into the machine based upon the project type. For example, a Java project will have the JDK, Git, and Maven installed. When a user is working within their Workspace, this container is booted by Che and the source code of the project is mounted within it. Developer actions like auto-complete and `mvn clean install` are processes that are executed within the container. Users can provide their own Dockerfiles that Che will build into images and extension developers can register Dockerfile templates associated with a project type. This allows Che to manage a potentially infinite number of environments while still giving users customization flexibility. + # What's Included Che ships with a large number of plug-ins for many programming languages, build systems, source code tools, and infrastructure including Java, Maven, Ant, Git, Subversion, JavaScript, and Angular.JS. The community is developing their own and many are merged into the main Che repository. Che can be installed on any operating system that supports Docker 1.8+ or Java 1.8 – desktop, server or cloud and has been tested on Linux, MacOS and Windows. It is licensed as EPL 1.0. -# Getting Started diff --git a/docs/_docs/setup/che-setup-managing.md b/docs/_docs/setup/che-setup-managing.md new file mode 100644 index 0000000000..11598291d0 --- /dev/null +++ b/docs/_docs/setup/che-setup-managing.md @@ -0,0 +1,114 @@ +--- +tags: [ "eclipse" , "che" ] +title: Managing +excerpt: "" +layout: docs +permalink: /:categories/managing/ +--- +# Scaling +Eclipse Che is a workspace server. It supports the provisioning and management of numerous workspaces for users. The default configuration of Che has a single identity per server, where the identity manages IDE preferences and SSH keys for workspaces and GitHub. + +There are three aspects to scaling Che: +1. Multi-client [collaboration]() within a workspace +2. Scaling Che using a [Che farm]() +3. [Upgrade to Codenvy](http://codenvy.com) + +## Workspace Sizing +The Che server requires 256MB RAM and can handle 1000s of concurrent workspaces. + +For each workspace, assume that the Che RAM overhead is 200MB-1.5GB, but it varies widely by the type of intellisense you add into the workspace. Your users will get the remaining RAM for use by their commands. So if you create a workspace with 2GB of RAM, some of that will be used by Che for its internal management of the workspace itself. + +The RAM variation and amount is relatively high and a function of which plug-ins are deployed into the workspace agent. For example, the Java plug-in which uses JDT core to do intellisense can require up to 1GB of RAM. If a developer is doing intensive compilation or dependency analysis, the workspace will bear the burden of providing the resources needed for these actions. + +Your workspace RAM can go higher if your users are creating multiple machines. Each workspace is given at least one machine. If you permit developers to launch other machines in a single workspace, those machines by default do not have a workspace agent and all of the RAM allocated to that machine will be granted to the user. + +Storage is consumed by: +1. Images downloaded and cached by Che for creating new workspaces. +2. Project files. +3. Workspace snapshots, which create new images saved in a registry. + +Generally, workspace images start at 180MB. If you permit workspace snapshots, those files can grow quite significantly, especially if your developers have large dependency sets such as maven repositories that they want captured in the snapshot. + +## Multi-Client Collaboration +Workspaces are both portable and shared. Multiple browser clients (and humans!) can connect to a single Che server running multiple workspaces, or if you prefer, to a single workspace. Users within a single workspace can make use of the runtime and project files. Che implements a last-write-wins policy when multiple users modify the same file. + +## Scaling Che Using a Che Farm + +![Capture_.PNG]({{ base }}/assets/imgs/Capture_.PNG) +You can deploy Che in a farm with an Nginx router. Each user would be provisioned their own Che instance, either running on its own port in a VM. In this configuration, each user can have their own workspaces and identity profile. Note that since Che exports two IP addresses, one for Che and another for the workspace machine running Docker, your router will need to manage traffic for all possible routes [between browser, Che and machines.]() + +## Scaling Che with Codenvy +Your Eclipse Che workspaces and plug-ins will work within [Codenvy](http://codenvy.com). Codenvy is a multi-tenant, multi-user and elastic cloud installed locally or used as a SaaS: +* Workspace distribution with an embedded Docker Swarm +* Operational solutions for monitoring, scaling, upgrading and archiving workspaces +* Team management, permissions and resource policy management tools +* User authentication, single-sign on, and LDAP +* Self-service user registration +![ScaleCodenvy.PNG]({{ base }}/assets/imgs/ScaleCodenvy.PNG) +Codenvy uses Docker to install, configure, and update various internal services. This creates a simple management interface for administrators with flexibility on how many physical nodes to allocate along with the resource policy management that is applied to users and accounts. + +# Upgrading +Upgrading Che is done by downloading a `eclipse/che-cli:` that is newer than the version you currently have installed. You can run `eclipse/che-cli version` to see the list of available versions that you can upgrade to. + +For example, if you have 5.0.0-M2 installed and want to upgrade to 5.0.0-M8, then: +``` +# Get the new version of Che +docker pull eclipse/che-cli:5.0.0-M8 + +# 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-M8 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: +1. Performs a version compatibility check +2. Downloads new Docker images that are needed to run the new version of Che +3. Stops Che if it is currently running +4. Triggers a maintenance window +5. Backs up your installation +6. Initializes the new version +7. Starts Che + +# Backup +You can run `che 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 restore` to recover che from a particular backup snapshot. The backup is saved as a TAR file that you can keep in your records. You can then use `che restore` to recover your user data and configuration. + +# Security +Eclipse Che is designed as a single identity system to be used by an individual or small team working in a trusted environment. The following outlines some of the security capabilities and known gaps in Che. + +## Securing Che Ports +Firewall rules can be added to prevent access to ports that shouldn't be externally accessible. Refer to [network topology docs]() for additional information on ports. + +When a remote user (outside the local network) requires access to Che, firewall rules can be setup to allow only certain ip-addresses access. + +## Limiting Che Ports +Eclipse Che uses Docker to power its workspaces. Docker uses the [ephemeral port range](https://en.wikipedia.org/wiki/Ephemeral_port) when exposing ports for services running in the container. So when a Tomcat server is started on port 8080 inside a Che workspace Docker automatically selects an available port from the ephemeral range at runtime to map to that Tomcat instance. + +Docker will select its ports from anywhere in the ephemeral range. If you wish to reduce the size of the ephemeral range in order to improve security you can do so, however, keep in mind that each Che workspace will use at least 2 ports plus whatever ports are required for the services the user adds to their workspace. + +Limiting the ephemeral range can only be done at the host level - you can read more about it (and some of the risks in doing so) here: http://www.ncftp.com/ncftpd/doc/misc/ephemeral_ports.html + +To change the ephemeral range: + * On Linux: http://www.ncftp.com/ncftpd/doc/misc/ephemeral_ports.html#Linux + * On Windows: http://www.ncftp.com/ncftpd/doc/misc/ephemeral_ports.html#Windows + +## Securing a Workspace from the Che Host +It is possible for admins to mount files from your server's host file system to be available to your users within their workspaces with the `CHE_WORKSPACE_VOLUME` and `CHE_DOCKER_PRIVILEGED_MODE` parameters are potential secrity risks as you open the possiblity of sending host-specific files into a workspace or giving a workspace user access to the host system. These options are useful for certain development situations but should be minimized to increase security to the host system whenever possible. + +## Workspace Permissions +Eclipse Che is a single identity system. All users accessing a Che server share an identity and user preferences. There are no identity-based permissions since all users share the same identity. Users have access and control over all workspace environments. + +For a simple separation of workspaces for small development teams, without requiring workspace permissions, administrators can create separate Che server for each user. Each server, if ran on same host, would need to be setup on different ports using the `CHE_PORT` environment variable and different data folders mounted `:/data`. + +Codenvy provides an implementation of Eclipse Che that is multi-tenant, multi-user with distributed access and permissions controls for teams. Each user has a different login which enables access controls, workspace collaboration, and other forms of sharing. You can install Codenvy with a CLI that is nearly identical to Che with `docker run codenvy/cli start. Learn more at [https://codenvy.com](https://codenvy.com). + +## Authenticated Access +The Che server itself is unauthenticated. Che is extensible allowing different dashboard front ends or proxies to implement authenticated access to the Che server. Bitnami's deployment of Eclipse Che includes an authenticated front-end implemented as a proxy. Many users deploy nginx in front of Che to provide an authentication layer within the system. + +Bitnami requires an existing account with cloud providers such as Google, Amazon AWS, or Microsoft Azure which may require monthly service charges from cloud providers. Refer to [Usage: Private Cloud](doc:usage-bitnami) for additional information. + +Codenvy also provides an implementation of Eclipse Che that has multi-user and multi-tenant capabilities. + +## HTTP/S +HTTPS is not provided by Eclipse Che. It would require a more complex architecture with multi-service deployments, making Che more challenging for developers and small teams to use. Codenvy gives you the option of running the system with HTTP/S and providing your own SSL certificate. diff --git a/docs/_docs/setup/che-setup-networking.md b/docs/_docs/setup/che-setup-networking.md deleted file mode 100644 index 3994fdbdfc..0000000000 --- a/docs/_docs/setup/che-setup-networking.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -tags: [ "eclipse" , "che" ] -title: Config: Networking -excerpt: "" -layout: docs -permalink: /:categories/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. -![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 with [Configuration](doc:configuration). - -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. - -| Linux | Windows/Mac -| --- | --- -| >>>>>>>>>>>Connection>>>>>> | `Che Server => Docker Daemon` -| 1. Use the value of `che.properties` property named `docker.client.daemon_url`.\n\n2. Else, use the value of `DOCKER_HOST` system environment variable. \n\n3. Else, use Unix socket over `unix:///var/run/docker.sock`. | 1) Use the value of `docker.client.daemon_url`.\n\n2) Else use the `DOCKER_HOST` environment variable. If `DOCKER_HOST` value is malformed, catch `URISyntaxException` and use the default `https://192.168.99.100:2376`..\n\n3) Else uses default value: `https://192.168.99.100:2376` -| `Che Server => Workspace`\n`Browser => Workspace` | 1. Use the value of `che.properties` property named `machine.docker.local_node_host`.\n\n2. Else, use the value of `CHE_DOCKER_MACHINE_HOST` system environment variable.\n\n3. Else, if server connects to Docker via Unix socket then use `localhost`.\n\n4. Else, get the value that the Che server used when it connected to the Docker daemon `DOCKER_HOST`. - -### 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. -# Ports -Inside of your workspace containers, Che launches microservices on port `4401` and `4403`. We also launch SSH agents on port `22`. The bash terminal accessible in the workspace is also launched as an agent in the workspace on port `4411`. Custom stacks (configured in the dashboard) may expose additional services on different ports. - -Docker uses ephemeral port mapping. The ports accessible to your clients start at port `32768` and go through a wide range. When we start services internal to Docker, they are mapped to one of these ports. It is these ports that the browser (or SSH) clients connect to, and would need to be opened if connecting through a firewall. - -Additionally, if services are started within the workspace that expose their own ports, then those ports need to have an `EXPOSE ` command added to the workspace image Dockerfile. As a courtesy, we expose port `80` and `8080` within the container for any users that want to launch services on those ports. -# Firewall -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. -```shell -# Check firewall status -sudo ufw status - -# Disable firewall -sudo ufw disable - -# Allow 8080 port of Che server -sudo ufw allow 8080/tcp\ -``` diff --git a/docs/_docs/setup/che-setup-scaling.md b/docs/_docs/setup/che-setup-scaling.md deleted file mode 100644 index b8d5650c25..0000000000 --- a/docs/_docs/setup/che-setup-scaling.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -tags: [ "eclipse" , "che" ] -title: Config: Scaling -excerpt: "Sizing guide and approaches for scaling Che to millions of concurrent developers" -layout: docs -permalink: /:categories/scaling/ ---- -Eclipse Che is a workspace server. It supports the provisioning and management of numerous workspaces for users. The default configuration of Che has a single identity per server, where the identity manages IDE preferences and SSH keys for workspaces and GitHub. - -There are three aspects to scaling Che: -1. Multi-client [collaboration](https://eclipse-che.readme.io/docs/scaling#multi-user-collaboration) within a workspace -2. Scaling Che using a [Che farm](https://eclipse-che.readme.io/docs/scaling#scaling-che-using-a-che-farm) -3. [Upgrade to Codenvy](https://eclipse-che.readme.io/docs/scaling#scaling-che-with-codenvy) -# Workspace Sizing -The Che server requires 256MB RAM and can handle 1000s of concurrent workspaces. - -For each workspace, assume that the Che RAM overhead is 200MB-1.5GB, but it varies widely by the type of intellisense you add into the workspace. Your users will get the remaining RAM for use by their commands. So if you create a workspace with 2GB of RAM, some of that will be used by Che for its internal management of the workspace itself. - -The RAM variation and amount is relatively high and a function of which plug-ins are deployed into the workspace agent. For example, the Java plug-in which uses JDT core to do intellisense can require up to 1GB of RAM. If a developer is doing intensive compilation or dependency analysis, the workspace will bear the burden of providing the resources needed for these actions. - -Your workspace RAM can go higher if your users are creating multiple machines. Each workspace is given at least one machine. If you permit developers to launch other machines in a single workspace, those machines by default do not have a workspace agent and all of the RAM allocated to that machine will be granted to the user. - -Storage is consumed by: -1. Images downloaded and cached by Che for creating new workspaces. -2. Project files. -3. Workspace snapshots, which create new images saved in a registry. - -Generally, workspace images start at 180MB. If you permit workspace snapshots, those files can grow quite significantly, especially if your developers have large dependency sets such as maven repositories that they want captured in the snapshot. -# Multi-Client Collaboration -Workspaces are both portable and shared. Multiple browser clients (and humans!) can connect to a single Che server running multiple workspaces, or if you prefer, to a single workspace. Users within a single workspace can make use of the runtime and project files. Che implements a last-write-wins policy when multiple users modify the same file. -# Scaling Che Using a Che Farm - -![Capture_.PNG]({{ base }}/assets/imgs/Capture_.PNG) -To scale out Che, you can either attempt to separate some Che services onto different nodes, or run a Che farm. - -1. (Coming Soon). Your workspace runtimes are Docker containers that do not have to reside on the same machine as the Che server, which is the workspace master. You can optionally deploy Docker onto a different physical node apart from the Che server. You can then size the Docker node based upon the number of concurrent workspaces that you want to have active and / or snapshot. Since Che has a single embedded identity in its default configuration, SSH keys and IDE preferences will be shared across all users accessing workspaces on a single server. - -2. You can deploy Che in a farm with an Nginx router. Each user would be provisioned their own Che instance, either running on its own port in a VM. In this configuration, each user can have their own workspaces and identity profile. Note that since Che exports two IP addresses, one for Che and another for the workspace machine running Docker, your router will need to manage traffic for all possible routes [between browser, Che and machines.](doc:networking) -# Scaling Che with Codenvy -Your Eclipse Che workspaces and plug-ins will work within [Codenvy](http://codenvy.com). Codenvy is a multi-tenant, multi-user and elastic cloud installed locally or used as a SaaS: -* Workspace distribution with an embedded Docker Swarm -* Operational solutions for monitoring, scaling, upgrading and archiving workspaces -* Team management, permissions and resource policy management tools -* User authentication, single-sign on, and LDAP -* Self-service user registration -![ScaleCodenvy.PNG]({{ base }}/assets/imgs/ScaleCodenvy.PNG) -Codenvy uses Puppet to install, configure, and update various internal services. This creates a simple management interface for administrators with flexibility on how many physical nodes to allocate along with the resource policy management that is applied to users and accounts. diff --git a/docs/_docs/setup-alternatives/che-setupalt-electron.md b/docs/_docs/use-che-as-an-ide/ide-electron.md similarity index 73% rename from docs/_docs/setup-alternatives/che-setupalt-electron.md rename to docs/_docs/use-che-as-an-ide/ide-electron.md index 15212e669a..9559edc0bb 100644 --- a/docs/_docs/setup-alternatives/che-setupalt-electron.md +++ b/docs/_docs/use-che-as-an-ide/ide-electron.md @@ -1,11 +1,11 @@ --- tags: [ "eclipse" , "che" ] -title: Usage: Electron Clients -excerpt: "Install Electron, a fast OS-specific desktop client for Eclipse Che" +title: Install Che Desktop Client +excerpt: "Install an electron application, a fast desktop client for Eclipse Che" layout: docs permalink: /:categories/electron/ --- -We have created Electron clients that you can use instead of your browser. Electron applications are native OS applications that run a Chromium client. Electron is small and loads faster than a browser. It has all the power of Chrome packaged as an OS-specific binary. You can distribute these clients such that they are pre-configured with the URL of your Che server. +You can install a desktop application client for Che. The Che desktop clients are Electron applications, which runs a lightweight chrome browser client packaged as a native application that you install for your operating system. Electron is small and loads faster than a browser. It has all the power of Chrome packaged as an OS-specific binary. You can distribute these clients such that they are pre-configured with the URL of your Che server. ![Capture2.PNG]({{ base }}/assets/imgs/Capture2.PNG) #### Eclipse Che Electron Clients diff --git a/docs/_docs/setup/che-setup-ssh.md b/docs/_docs/use-che-as-an-ide/ide-ssh.md similarity index 92% rename from docs/_docs/setup/che-setup-ssh.md rename to docs/_docs/use-che-as-an-ide/ide-ssh.md index a24d9f5e3c..6c80dcf5b1 100644 --- a/docs/_docs/setup/che-setup-ssh.md +++ b/docs/_docs/use-che-as-an-ide/ide-ssh.md @@ -1,14 +1,13 @@ --- tags: [ "eclipse" , "che" ] -title: Usage: SSH -excerpt: "Connect to your workspace runtimes" +title: SSH +excerpt: "Connect to your workspaces using SSH" layout: docs permalink: /:categories/ssh/ --- -#### Requires 5.0.0-M7 -} +Workspaces are configured with an SSH agent, which runs an SSH daemon within your workspace runtime. You can connect to your workspace on the command line and get root access to the runtime (similar to what the Web terminal provides) from other machines. You can optionally disable the SSH agent for your workspace from within the dashboard. -## Public / Private Key Generation +# Public / Private Key Generation If your workspace has the SSH agent activated in the dashboard, then Che runs an SSH daemon within the machines that are part of your workspace. The SSH agent is activated by default with all new workspaces and you can manually disable it within the dashboard. If your workspace is powered by Docker Compose, then the SSH agent is deployed into every container that makes up your compose services. You can optionally remove the agent from selected machines of your compose services from within the dashboard. Each new workspace has a default key-pair generated for it. The private key for the workspace is inserted into each machine and they will all share the same public key. You can generate a new key-pair in the dashboard, or remove the default one to be replaced with yours. @@ -16,6 +15,7 @@ Each new workspace has a default key-pair generated for it. The private key for Eclipse Che does not have any user authentication, so any client can connect to the Che server REST API and then request the public key for the workspace. In Codenvy, API clients must be authenticated with appropriate permissions before they can request the public key for a workspace. We then provide various client utilities (authored in Docker!) for connecting to a workspace using SSH. + # List Workspaces You can get a list of workspaces in a Che server that have an SSH agent deployed. These are the workspaces that you can SSH into. ```shell diff --git a/docs/_docs/setup/che-setup-desktop-ide-mounting.md b/docs/_docs/use-che-as-an-ide/ide-sync.md similarity index 97% rename from docs/_docs/setup/che-setup-desktop-ide-mounting.md rename to docs/_docs/use-che-as-an-ide/ide-sync.md index 959cf71d26..f220c4339d 100644 --- a/docs/_docs/setup/che-setup-desktop-ide-mounting.md +++ b/docs/_docs/use-che-as-an-ide/ide-sync.md @@ -1,12 +1,10 @@ --- tags: [ "eclipse" , "che" ] -title: Usage: Local IDE Sync -excerpt: "Using your desktop IDE with an Eclipse Che workspace." +title: Local IDE Sync +excerpt: "Synchronize Che workspaces with your desktop IDE with live sync." layout: docs -permalink: /:categories/desktop-ide-mounting/ +permalink: /:categories/sync/ --- -#### Requires 5.0.0-M7 -} Che ships a super fast Fuse-based mount and sync mechanism. This is delivered as a Docker container that combines `sshfs` with `unison`. You can perform a mount on any operating system that supports Docker. However, if you are on Windows using Boot2Docker, you can only mount directories in `%userprofile%`. # List Workspaces diff --git a/docs/_docs/workspace-administration/ws-data-model-samples.md b/docs/_docs/workspace-administration/ws-data-model-samples.md new file mode 100644 index 0000000000..be8694eaf2 --- /dev/null +++ b/docs/_docs/workspace-administration/ws-data-model-samples.md @@ -0,0 +1,162 @@ +--- +tags: [ "eclipse" , "che" ] +title: Project Samples Data Model +excerpt: "Defines code sample and commands used to bootstrap a new project in a workspace." +layout: docs +permalink: /:categories/data-model-samples/ +--- +Users can add additional code-based project samples that are cloned into a workspace during workspace activation or by a project wizard. The `samples` JSON object defines a code sample and commands that can be used to bootstrap the content of a new project. + +# Samples Object +Project samples (code snippets to be converted with a project type) are defined in JSON: +```json +samples : { + "name" : STRING, # Name of the project + "displayName" : STRING, # Name of the project to be displayed in wizard + "path" : STRING, # Path to the project in a workspace behaviors + "description" : STRING, # Description of the project to appear on the dashboard + "projectType" : STRING, # Project type. Projects type descriptions are in the Factory docs + "mixins" : {}, # Mixins add sets of behavior attributes to a project. + "attributes" : {}, # List of project type attributes. List varies by type selected + "modules" : {}, # (Optional) Project components. Set by server + "problems" : {}, # (Optional) Errors occurred in the project. Set by server + "source" : {}, # The source code imported attributes to a project + "commands" : {}, # Set of the commands available for the project. + "links" : {}, # List of the method links + "category" : STRING, # Category to be displayed in the IDE Create Project wizard + "tags" : ARRAY # Values used to filter samples +} + +``` +## Source +```json +samples.source : { + "type" : [git | svn | zip], # Version control system + "location" : URL, # Location of version control or ZIP archive + "parameters" : {} # (Optional) Configure location access - varies by type +} +``` +When using `source.type` with `git` or `svn`, the `source.location` should be URL of a publicly available repo. Referencing private repos over HTTPS will result in clone failure unless credentials are provided in the URL itself. Using SSH URLs is possible, however, a user will need ssh key to complete this operation, therefore, it is recommended to use HTTPS URLs to public repos. +```json +"source" : { + "type" : "git", + "location" : "https://github.com/tomitribe/tomee-jaxrs-angular-starter-project.git", + "parameters" : {} +}, +``` + +`zip` archives are referenced as URLs to remotely hosted archives that are publicly available i.e. require no login/password to be downloaded. It is not possible to reference local URLs unless you run a local server to host them (in this case a local IP is used e.g. `http://192.168.0.10/projecs/myproject.zip`). + +```json +"source" : { + "type" : "zip", + "location" : "http://192.168.0.10/projecs/myproject.zip", + "parameters" : {} +}, +``` + +### Parameters +```json +samples.source.parameters : { + "branch" : STRING, # Clone from this branch + "keepVcs" : [true | false], # Keep the .git folder after clone. + "commitId" : STRING, # Clone from a commit point. Branch precedes this property + "keepDir" : STRING, # Sparse Checkout to clone only sub-directory of repository + "fetch" : REF-SPEC # Clone from patch set of provided ref-spec +} +``` + +## Commands +You can add predefined sets of commands that will appear in the command selector for any user that creates a project from this sample. +```json +samples.commands : [{ + # Add command JSON objects here +}] +``` +See [Command]() reference. + + +## Tags +Tags are used for stacks and samples objects. Those values are used to determine if a sample is compatible with a stack. Tags are used to filter the list of project samples that a user can choose when selecting a stack in the user dashboard. +```json +samples.tags : [{ + "tag1" + "tag2" + "..." +}] +``` +# Samples Reference +```json +[ + { + "name":"web-javaee-jaxrs", + "displayName":"web-javaee-jaxrs", + "path":"/web-javaee-jaxrs", + "description":"A basic example demonstrating JAXRS running on Apache TomEE", + "projectType":"maven", + "mixins":[], + "attributes":{ + "language":[ + "java" + ] + }, + "modules":[], + "problems":[], + "source":{ + "type":"git", + "location":"https://github.com/tomitribe/tomee-jaxrs-angular-starter-project.git", + "parameters":{} + }, + "commands":[ + { + "name":"build", + "type":"mvn", + "commandLine":"mvn -f ${current.project.path} clean install + && cp ${current.project.path}/target/*.war $TOMEE_HOME/webapps/ROOT.war", + "attributes":{ + "previewUrl":"" + } + }, + { + "name":"run tomee", + "type":"custom", + "commandLine":"$TOMEE_HOME/bin/catalina.sh run", + "attributes":{ + "previewUrl":"http://${server.port.8080}" + } + }, + { + "name":"stop tomee", + "type":"custom", + "commandLine":"$TOMEE_HOME/bin/catalina.sh stop", + "attributes":{ + "previewUrl":"" + } + }, + { + "name":"build and run", + "type":"mvn", + "commandLine":"mvn -f ${current.project.path} clean install + && cp ${current.project.path}/target/*.war $TOMEE_HOME/webapps/ROOT.war + && $TOMEE_HOME/bin/catalina.sh run", + "attributes":{ + "previewUrl":"http://${server.port.8080}" + } + }, + { + "name":"debug", + "type":"mvn", + "commandLine":"mvn -f ${current.project.path} clean install + && cp ${current.project.path}/target/*.war $TOMEE_HOME/webapps/ROOT.war + && $TOMEE_HOME/bin/catalina.sh jpda run", + "attributes":{ + "previewUrl":"http://${server.port.8080}" + } + } + ], + "links":[], + "category":"Samples", + "tags":["maven","java","javaee","jaxrs"] + } +] +``` \ No newline at end of file diff --git a/docs/_docs/che-data-model/che-data-model-stack.md b/docs/_docs/workspace-administration/ws-data-model-stacks.md similarity index 98% rename from docs/_docs/che-data-model/che-data-model-stack.md rename to docs/_docs/workspace-administration/ws-data-model-stacks.md index c9d430ecff..85f5b4dd5f 100644 --- a/docs/_docs/che-data-model/che-data-model-stack.md +++ b/docs/_docs/workspace-administration/ws-data-model-stacks.md @@ -1,13 +1,13 @@ --- tags: [ "eclipse" , "che" ] -title: Stack -excerpt: "Sample code that can be used to bootstrap the content of a new project." +title: Runtime Stacks Data Model +excerpt: "Defines the runtimes for a workspace." layout: docs -permalink: /:categories/stack/ +permalink: /:categories/data-model-stacks/ --- -JSON workspace object defines the contents and structure of a workspace. A workspace configuration is used to define the workspace to be generated. +Admins and users typically use our graphical dashboard for adding and configuring stacks within the product. However, you can also add these directly with REST or in the product using a JSON data model. -## Stack Object +# Stack Object Stacks are referenced in JSON format: ```json { diff --git a/docs/docs.sh b/docs/docs.sh index 03fad473fa..2694e6d009 100644 --- a/docs/docs.sh +++ b/docs/docs.sh @@ -4,6 +4,12 @@ # # Optionally - you can run 'jekyll/jekyll jekyll serve' to get a local server on port 9080 # NOTE - these files will not work without a hosted server right now - they are not static stand alone +# +# Usage: bash docs.sh [--build|--run\ +# +# --build - one-time generation of the Web site into _site +# --run - runs jekyll's Web server on port 9080 +# GLOBAL_HOST_ARCH=$(docker version --format {{.Client}} | cut -d" " -f5) docker() {