The CLI is a Docker image (rbrain/rideserver-cli) that is used to install, configure, start and manage RIDE Server. Running rbrain/rideserver-cli executes RIDE Server'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 RIDE Server. 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 initand 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 RIDE Server. 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 RIDE Server. 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 RIDE Server. 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> rbrain/rideserver-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 RIDE Server 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

COMMANDS:
  action <action-name>                 Start action on RIDE Server instance
  backup                               Backups RIDE Server configuration and data to /data/backup volume mount
  config                               Generates a RIDE Server config from vars; run on any start / restart
  destroy                              Stops services, and deletes RIDE Server instance data
  dir <command>                        Use Chedir and Chefile in the directory mounted to :/chedir
  download                             Pulls Docker images for the current RIDE Server version
  help                                 This message
  info                                 Displays info about RIDE Server and the CLI
  init                                 Initializes a directory with a RIDE Server install
  offline                              Saves RIDE Server Docker images into TAR files for offline install
  restart                              Restart RIDE Server services
  restore                              Restores RIDE Server 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 RIDE Server services
  stop                                 Stops RIDE Server services
  sync <wksp-name>                     Synchronize workspace with local directory mounted to :/sync
  test <test-name>                     Start test on RIDE Server instance
  upgrade                              Upgrades RIDE Server from one version to another with migrations and backups
  version                              Installed version and upgrade paths
  add-node                             Adds a physical node to serve workspaces into the RIDE Server cluster
  list-nodes                           Lists all physical nodes that are part of the RIDE Server cluster
  remove-node <ip>                     Removes the physical node from the RIDE Server 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 RIDE Server 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 codenvy.env.

init

Initializes an empty directory with a RIDE Server configuration and instance folder where user data and runtime configuration will be stored. You must provide a <path>:/data volume mount, then RIDE Server creates a instance and 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 /data.

These variables can be set in your local environment shell before running and they will be respected during initialization: 

RIDE Server depends upon Docker images. We use Docker images in three ways:

  1. As cross-platform utilites within the CLI. For example, in scenarios where we need to perform a curl operation, we use a small Docker image to perform this function. We do this as a precaution as many operating systems (like Windows) do not have curl installed.
  2. To look up the master version and upgrade manifest, which is stored as a singleton Docker image called rideserver-cli/version.
  3. To perform initialization and configuration of RIDE Server such as with rideserver-cli/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.
  4. To run RIDE Server and its dependent services, which include RIDE Server, HAproxy, nginx, Postgres, socat, and Docker Swarm.

You can control the nature of how RIDE Server downloads these images with command line options. All image downloads are performed with docker pull.

You can reinstall RIDE Server on a folder that is already initialized and preserve your /data/codenvy.env values by passing the --reinit flag.

config

Generates a RIDE Server instance configuration that is placed in /data/instance. This command uses puppet to generate configuration files for RIDE Server, haproxy, swarm, socat, nginx, and postgres which are mounted when RIDE Server services are started. This command is executed on every rbrain/rideserver-cli start or rbrain/rideserver-cli restart.

If you are using a rbrain/rideserver-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 --no-force, --pull, --force, and --offline.

start

Starts RIDE Server and its services using docker-compose. If the system cannot find a valid configuration it will perform a rbrain/rideserver-cli init. Every rbrain/rideserver-cli start and rbrain/rideserver-cli restart will run a rbrain/rideserver-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 RIDE Server 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:preflight and --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.

stop

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 --user and --password

restart

Performs a rbrain/rideserver-cli stop followed by a rbrain/rideserver-cli start, respecting --pull, --force, and --offline.

destroy

Deletes /docs, codenvy.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 RIDE Server 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 RIDE Server 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:<image-name> will download a single stack image and can be used multiple times on the command line. You can use --all-stacks or --no-stacksto download all or none of the optional stack images.

rmi

Deletes the Docker images from the local registry that RIDE Server 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 RIDE Server to do initialization and configuration, and for the runtime images that RIDE Server needs when it starts. This command respects --offline, --pull, --force, and --no-force(default). This command is invoked by rbrain/rideserver-cli init, rbrain/rideserver-cli config and rbrain/rideserver-cli start.

This command is invoked by init before initialization to download the images for the version specified by rbrain/rideserver-cli:<version>

version

Provides information on the current version and the available versions that are hosted in RIDE Server's repositories. 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 RIDE Server from one version to another. Run rbrain/rideserver-cli version to get a list of available versions that you can upgrade to.

Upgrading RIDE Server is done by using a rbrain/rideserver-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 RIDE Server
docker pull rbrain/rideserver-cli:5.0.0-M7

# You now have two rbrain/rideserver-cli images (one for each version)
# Perform an upgrade - use the new image to upgrade old installation
docker run <volume-mounts> rbrain/rideserver-cli:5.0.0-M7 upgrade

The upgrade command has numerous checks to prevent you from upgrading RIDE Server if the new image and the old version are not compatible. 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 RIDE Server, c) stops RIDE Server if it is currently running triggering a maintenance window, d) backs up your installation, e) initializes the new version, and f) starts RIDE Server.

You can run rbrain/rideserver-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 backupcan be very expensive operation if /instance folder is really big due to many user worksapces and projects.

info

Displays system state and debugging information. --network runs a test to take your CODENVY_HOST value to test for networking connectivity simulating browser > RIDE Server and RIDE Server > 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.

Did this answer your question?