Stack overview

A stack is a workspace configuration template. Stacks are used to create workspaces in the User Dashboard. The stack includes meta-information such as scope, tags, components, description, name, and identification. You can filter stacks by machine type and scope. The type is either single machine or multi machine. You can also search for a stack by keyword. Stacks are displayed in the User Dashboard on the Create a workspace page.

See the Creating and starting workspaces user guide for more information.

Importing community supported stacks and applications

Che includes some stacks and sample applications that are pre-configured and tested. Stacks that are contributed by the Che community are not tested. Community stacks are located in the community stacks GitHub repository.

Each directory has ${technology}-stack.json and ${technology}-samples.json.

To import a stack, follow these steps:

  1. Copy the content of the JSON files.

  2. Go to ${CHE_HOST}/swagger/#!/stack/createStack.

  3. Paste the content of the JSON file to the body field.

  4. Click the Try it out button.

You can choose a different name or ID when there is a conflict with the stack ID or name.

For a multi-user setup, you can make your stack available for a particular user or all users in the system. See stack sharing for more information.

To import sample applications, move *-stacks.json files to:

  • ${LOCAL_STORAGE}/instance/data/templates for Docker infrastructure.

  • ${mount-path-of-che-data-volume}/templates for OpenShift and Kubernetes infrastructure. You need administrator privileges to get the host path and to access the host directory. Also, the new JSON files have the same permissions as the original samples.json file.

You can find Dockerfiles for all stacks in the Che Dockerfiles repository.

Sharing stacks and system stacks

You can share stacks with selected users or with all users in the system if you have system privileges. You share stacks by making REST calls.

To share stacks with users:

  • Log in as administrator

  • Go to /swagger/#!/stack/searchStacks to get a list of all stacks. You may filter search by tags.

  • Find your stack by name and get its ID.

  • The next API to use is: /swagger/#!/permissions

  • Find the below POST method:

stack permissions
  • Use the following JSON file and replace ${STACK_ID} with an actual ID:

"userId": "*",
  "domainId": "stack",
  "instanceId": "${STACK_ID}",
  "actions": [

If you get 204, all the users in the system see the stack. To share a stack with a particular user, get the user’s ID and use it instead of * in the JSON file.

The administrator can remove pre-configured stacks and replace them with custom stacks. The administrator can also remove permissions from stacks. You can create stacks either in the user dashboard or by using any REST client. You can use Swagger ($CHE_HOST:$CHE_PORT/swagger) to bundle with Che.

Loading stacks

Stacks are loaded from a JSON file that is packaged into resources of a special component that is deployed with the workspace master. This JSON file is not exposed to users. You can perform stack management using REST APIs in the User Dashboard.

When a user first starts Che, stacks are loaded from a JSON file only when the database is initialized. This is the default policy that can be changed. To keep getting stack updates with the new Che stacks, set CHE_PREDEFINED_STACKS_RELOADONSTART=true in che.env. When set to true, stacks.json is used to update Che database each time the Che server starts. This means Che gets all the stacks in stacks.json and uploads the stacks to a database. This allows you to keep existing custom stacks and get stack updates from new Che releases. New and edited stacks that have fixes in the stack definition are merged in with the other stacks.

Name conflicts are possible. A name conflict happens when a new Che version provides a stack with a name that already exists in the database.