The CLI is a Docker image (
codenvy/cli) that is used to install, configure, start and manage Codenvy. Running
codenvy/cli executes Codenvy’s CLI launcher from within a Docker container. The CLI launcher uses the
codenvy.env configuration file to launch and configure a set of containers that are then used to run Codenvy. The CLI launcher also includes a number of helper functions for admins.
The CLI has three primary phases: initialization, configuration, and start. The initialization phase is executed by
init and will install version-specific files into the folder mounted to
/data. This includes the universal configuration file named
codenvy.env, a version identifier, and a location where configuration files will be saved. The configuration is executed by the
config command and takes as input your
codenvy.env configuration file, the OS of your host, and then generates an OS-specific set of configuration files in the
/data/instance folder that can be used to run an instance of Codenvy. The configuration phase will run an initialization if a folder is not found. Every execution of the
config command will overwrite the files in
/data/instance with the latest configuration. This way if an admin modifies any configuration file, the instance’s configuration files will be updated to be guaranteed consistent. The CLI generates a large number of configuration files specific to running Codenvy. The configuration files are sourced from Puppet templates that are stored in our GitHub repository under
/dockerfiles/init. The start phase is executed by
start and will use a configuration-generated
docker-compose-container.yml file to launch Codenvy. The start phase always executes a
config command, so any files that were edited in
/data/instance will be overwritten with the generated configuration from the
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.
USAGE: docker run -it --rm <DOCKER_PARAMETERS> codenvy/cli:<version> [COMMAND] MANDATORY DOCKER PARAMETERS: -v <LOCAL_PATH>:/data Where user, instance, and log data saved OPTIONAL DOCKER PARAMETERS: -e CODENVY_HOST=<YOUR_HOST> IP address or hostname where codenvy will serve its users -v <LOCAL_PATH>:/data/instance Where instance, user, log data will be saved -v <LOCAL_PATH>:/data/backup Where backup files will be saved -v <LOCAL_PATH>:/repo codenvy git repo - uses local binaries and manifests -v <LOCAL_PATH>:/assembly codenvy assembly - uses local binaries -v <LOCAL_PATH>:/sync Where remote ws files will be copied with sync command -v <LOCAL_PATH>:/unison Where unison profile for optimizing sync command resides -v <LOCAL_PATH>:/chedir Soure repository to convert into workspace with Chedir utility COMMANDS: action <action-name> Start action on codenvy instance backup Backups codenvy configuration and data to /data/backup volume mount config Generates a codenvy config from vars; run on any start / restart destroy Stops services, and deletes codenvy instance data dir <command> Use Chedir and Chefile in the directory mounted to :/chedir download Pulls Docker images for the current codenvy version help This message info Displays info about codenvy and the CLI init Initializes a directory with a codenvy install offline Saves codenvy Docker images into TAR files for offline install restart Restart codenvy services restore Restores codenvy configuration and data from /data/backup mount rmi Removes the Docker images for <version>, forcing a repull ssh <wksp-name> [machine-name] SSH to a workspace if SSH agent enabled start Starts codenvy services stop Stops codenvy services sync <wksp-name> Synchronize workspace with local directory mounted to :/sync test <test-name> Start test on codenvy instance upgrade Upgrades codenvy from one version to another with migrations and backups version Installed version and upgrade paths add-node Adds a physical node to serve workspaces intto the Codenvy cluster list-nodes Lists all physical nodes that are part of the Codenvy cluster remove-node <ip> Removes the physical node from the Codenvy cluster GLOBAL COMMAND OPTIONS: --fast Skips networking, version, nightly and preflight checks --offline Runs CLI in offline mode, loading images from disk --debug Enable debugging of codenvy server --trace Activates trace output for debugging CLI
You can override any value in
codenvy.env for a single execution by passing in
-e NAME=VALUE on the command line. The CLI will detect the values on the command line and ignore those imported from
Initializes an empty directory with a Codenvy configuration and instance folder where user data and runtime configuration will be stored. You must provide a
<path>:/data volume mount, then Codenvy creates a
backup subfolder of
<path>. 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
codenvy.env file is placed into the root of the path that you mounted to
These variables can be set in your local environment shell before running and they will be respected during initialization:
||The IP address or DNS name of the Codenvy service. We use
Codenvy depends upon Docker images. We use Docker images in three ways:
- As cross-platform utilites within the CLI. For example, in scenarios where we need to perform a
curloperation, 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.
- To look up the master version and upgrade manifest, which is stored as a singleton Docker image called
- To perform initialization and configuration of Codenvy such as with
codenvy/init. This image contains templates that are delivered as a payload and installed onto your computer. These payload images can have different files based upon the image’s version.
- To run Codenvy and its dependent services, which include Codenvy, HAproxy, nginx, Postgres, socat, and Docker Swarm.
You can control the nature of how Codenvy downloads these images with command line options. All image downloads are performed with
||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.|
||Will always perform a
||Performs a forced removal of the local image using
||Loads Docker images from
You can reinstall Codenvy on a folder that is already initialized and preserve your
/data/codenvy.env values by passing the
Generates a Codenvy instance configuration thta is placed in
/data/instance. This command uses puppet to generate configuration files for Codenvy, haproxy, swarm, socat, nginx, and postgres which are mounted when Codenvy services are started. This command is executed on every
codenvy/cli start or
If you are using a
codenvy/cli:<version> image and it does not match the version that is in
/instance/codenvy.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
Starts Codenvy and its services using
docker-compose. If the system cannot find a valid configuration it will perform a
codenvy/cli init. Every
codenvy/cli start and
codenvy/cli restart will run a
codenvy/cli config to generate a new configuration set using the latest configuration. The starting sequence will perform pre-flight testing to see if any ports required by Codenvy are currently used by other services and post-flight checks to verify access to key APIs.
You can skip pre-flight and post-flight checks with
--skip:postflight respectively. The typical Che start sequence includes an invocation of the
config method, which regenerates configuration files placed into the
/instance folder. You can skip this generation with
--skip:config. You can automatically print out the server logs to the console during the booting of the server by appending
--follow. This flag is blocking and requires you to CTRL-C to interrupt the output.
The default stop is a graceful stop where each workspace is stopped and confirmed shutdown before stopping system services. If workspaces are configured to snap on stop, then all snaps will be completed before system service shutdown begins. You can ignore workspace stop behavior and shut down only system services with
--force flag. Your admin user and password are required to perform a shutdown and provided by
codenvy/cli stop followed by a
codenvy/cli start, respecting
/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.
Saves all of the Docker images that Codenvy 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 Codenvy with
--offline, the CLI pre-boot sequence will load all of the Docker images in the
--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:<image-name> will download a single stack image and can be used multiple times on the command line. You can use
--no-stacks to download all or none of the optional stack images.
Deletes the Docker images from the local registry that Codenvy has downloaded for this version.
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 Codenvy to do initialization and configuration, and for the runtime images that Codenvy needs when it starts. This command respects
--no-force (default). This command is invoked by
codenvy/cli config, and
This command is invoked by
init before initialization to download the images for the version specified by
Provides information on the current version and the available versions that are hosted in Codenvy’s repositories.
upgrade enforces upgrade sequences and will prevent you from upgrading one version to another version where data migrations cannot be guaranteed.
Manages the sequence of upgrading Codenvy from one version to another. Run
codenvy/cli version to get a list of available versions that you can upgrade to.
Upgrading Codenvy is done by using a
codenvy/cli:<version> 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 Codenvy docker pull codenvy/cli:5.0.0-M7 # You now have two codenvy/cli images (one for each version) # Perform an upgrade - use the new image to upgrade old installation docker run <volume-mounts> codenvy/cli:5.0.0-M7 upgrade
The upgrade command has numerous checks to prevent you from upgrading Codenvy 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/codenvy.ver’.
The upgrade process: a) performs a version compatibility check, b) downloads new Docker images that are needed to run the new version of Codenvy, c) stops Codenvy if it is currently running triggering a maintenance window, d) backs up your installation, e) initializes the new version, and f) starts Codenvy.
You can run
codenvy/cli version to see the list of available versions that you can upgrade to.
--skip-backup option allow to skip backup during update, that could be useful to speed up upgrade because backup can be very expensive operation if
/instance folder is really big due to many user worksapces and projects.
Displays system state and debugging information.
--network runs a test to take your
CODENVY_HOST value to test for networking connectivity simulating browser > Codenvy and Codenvy > workspace connectivity.
/instance into files and places them into
/backup. These files are restoration-ready.
/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.