Creating a factory in the dashboard

You can create a factory based on an existing workspace. You can also create factories based on a template or by pasting in a .factory.json file and then generating a factory URL using the Che CLI or API. To learn more about the JSON structure and options, see Factory JSON reference.

A factory created from the dashboard is persisted on Che and retained when upgrading to a newer version.

To create a factory on the dashboard:

  1. In the IDE, click Dashboard > Factories > Create Factory.

Creating a factory in the IDE

Creating a factory in the IDE in a running workspace generates a factory to replicate that workspace including the runtime and project settings.

A factory created from the dashboard is persisted on Che and retained when upgrading to a newer version.

To create a factory in the IDE:

  1. In the IDE, click Workspace > Create Factory.

Creating a factory based on a repository

URL factories work with GitHub and GitLab repositories. By using URL factories, the project referenced by the URL is automatically imported.

To create a factory based on a repository:

  1. Specify the repository URL. Ensure that you store the configuration in the repository.

Sample factories:

The factory URL can include a branch or a subdirectory. Following are examples of optional parameters:

  • ?url=https://github.com/eclipse/che Che is imported with the master branch.

  • ?url=https://github.com/eclipse/che/tree/5.0.0 Che is imported by using the 5.0.0 branch.

  • ?url=https://github.com/eclipse/che/tree/5.0.0/dashboard subdirectory dashboard/ is imported by using the 5.0.0 branch.

Customizing URL factories

The following are two ways to customize the runtime and configuration:

Customizing only the runtime

Providing a .factory.json file inside the repository signals to Che URL factory to configure the project and runtime according to this configuration file. When a .factory.json file is stored inside the repository, any Dockerfile content is ignored because the workspace runtime configuration is defined inside the JSON file.

Customizing the Dockerfile

(This only works on Docker infrastructure. On recent Che versions, support of this feature may be reduced or dropped.) Providing a .factory.dockerfile inside the repository signals to the URL factory to use this Dockerfile for the workspace agent runtime. By default, imported projects are set to a blank project type. You can also set the project type in the .factory.json file or in the workspace definition that the factory inherits from.

Configuring factory policies

Policies are a way to send instructions to the automation engine about the number of workspaces to create and their meta data such as lifespan and resource allocation.

Setting factory limitations

Referer

Checks the hostname of the acceptor and only allows the factory to execute if there is a match.

Since and Until

Defines the time window in which the factory can be activated. For example, instructors who want to create an exercise that can only be accessed for two hours should set these properties.

Setting factory multiplicity

Multiplicity defines the number of workspaces that can be created from the factory.

Multiple workspaces (perClick)

Every click of the factory URL generates a different workspace, each with its own identifier, name, and resources.

Single workspace (perUser)

Exactly one workspace is generated for each unique user that clicks on the factory URL. Existing workspaces are reopened.

To learn how to configure factory policies, see the JSON reference.

Customizing the IDE

You can instruct the factory to invoke a series of IDE actions based on events in the lifecycle of the workspace.

Lifecycle Events

The lifecycle of the workspace is defined by the following events:

  • onAppLoaded: Triggered when the IDE is loaded.

  • onProjectsLoaded: Triggered when the workspace and all projects have been activated.

  • onAppClosed: Triggered when the IDE is closed.

Each event type has a set of actions that can be triggered. There is no ordering of actions executed when you provide a list; Che asynchronously invokes multiple actions if appropriate.

Factory actions

The following is a list of all possible actions that can be configured with your factory.

Run Command

Specify the name of the command to invoke after the IDE is loaded.
Associated Event: onProjectsLoaded

Open File

Open project files in the editor. Optionally, define the line to be highlighted.
Associated Event: onProjectsLoaded

Open a Welcome Page

Customize content of a welcome panel displayed when the workspace is loaded.
Associated Event: onAppLoaded

Warn on Uncommitted Changes

Opens a warning pop-up window when the user closes the browser tab with a project that has uncommitted changes.
Associated Event: onAppClosed

To learn how to configure factory actions, see the Factory JSON reference.

Finding and replacing variables

Factories make it possible to replace variables or placeholders in the source code — used to avoid exposing sensitive information (passwords, URLs, account names, API keys) — with real values. To find and replace a value, you can use the run command during an onProjectsLoaded event. You can use sed, awk, or other tools available in your workspace environment.

For a sample of how to configure finding and replacing a value, see the Factory JSON reference section. Alternatively, you can add IDE actions in the Factory tab, on the user Dashboard.

Use regular expressions in sed, both in find-replace and file-file type patterns.

Pull request workflow

Factories can be configured with a dedicated pull request workflow. The PR workflow handles local and remote branching, forking, and issuing the pull request. Pull requests generated from within Che have another factory placed into the comments of the pull requests that a PR reviewer can use to quickly start the workspace.

When enabled, the pull request workflow adds a contribution panel to the IDE.

pr panel

Repository badging

If you have projects in GitHub or GitLab, you can help your contributors to get started by providing them ready-to-code developer workspaces. Create a factory and add the following badge on your repositories readme.md:

[![Developer Workspace](https://che.openshift.io/factory/resources/factory-contribute.svg)](your-factory-url)

Next steps