Running IBM Z® Open Editor in the browser with Eclipse Theia

by Peter Haumer.
Last updated: 4 December 2019

VS Code has become so popular that there are other editors out there now that provide a compatibility API to also consume VS Code extensions. One of the most popular ones is the web-based Eclipse Theia. Theia is also the default editor for the container-based Eclipse Che platform as well. Hence, we develop IBM Z Open Editor not only for VS Code, but also Theia, which opens our editor up for an even larger community than VS Code already provides. In fact, Z Open Editor has actually evolved out of a Theia extension that we introduced in 2018. For more details, see the Overview or a demo showing both user experiences.

API compatibility

Theia strives for full compatibility of the VS Code APIs. As Theia and VS Code evolve, the Theia team is keeping track of the status of the VS Code API implementation in Theia here. If new issues are found, the team accepts issue reports here using the tag vscode.

Building Theia and running IBM Z Open Editor in it

In this article, we will show you three different ways of building Theia and running it with IBM Z Open Editor and optionally Zowe Explorer that gives you access to z/OS® resources:

1. Load it from npmjs.org
2. Load a Docker container
3. Build Theia from source

To run IBM Z Open Editor and optionally Zowe Explorer with Theia, you must first download the vsix file(s) of IBM Z Open Editor VS Code extension and optionally Zowe Explorer VS Code extension from the VS Code Marketplace using the "Download Extension" link on the right.

Alternative 1: Load it from npmjs.org

If you want to try out the user experience for editing COBOL or PL/I code in a browser, you can build a Theia editor instance with our extension on your development machine easily and then run the Theia web server from the command line window. The main prerequisite is to have Node.js V10 (not newer) and yarn installed on your development machine. It can run on Linux, Windows, or macOS.

1. Follow the instructions here to build a Theia instance using Node and Yarn with the two modifications described below.

2. After pasting the contents for the package.json file, add the following additional entries into the dependencies object:

    "@theia/plugin-dev": "next",
    "@theia/plugin-ext-vscode": "next"
   

   As the name indicates, these commands will add VS Code Extension compatibility.

3. Then, use the plain yarn command to build everything.

4. Create a folder called plugins in the directory where you built Theia, and drop the downloaded vsix file(s) into that folder.

5. Start Theia with this augmented command:

   yarn theia start --plugins=local-dir:./plugins
   

6. Now open a web browser and navigate to http://localhost:3000.

Theia will now load and you can create a workspace directory on your local drive with COBOL or PL/I files with Z Open Editor language support. If you also downloaded the Zowe Explorer VS Code extension, you can see the stylized Z icon on the left that you can click to see the Data Set, USS, and JES viewers.

Done. It is that easy.

If you are looking for code samples to try, clone our sample repository with the following command and open that folder by clicking File > Open....

git clone https://github.com/IBM/zopeneditor-sample.git

Alternative 2: Load a Docker container

If you are a fan of Docker, you can get started even faster than the alternative above by using the Theia Docker images that are continuously published. This page provides a great overview to the available Docker images maintained by the Theia team.

As the default Theia Docker image does not include the VS Code extension, we recommend loading the theia-full image.

1. Make sure you are not running any other Theia app anymore or change the mapped port in the command below. Assuming that you have Docker installed and running, execute this command to download the image and start a container:

   docker run -it --init -p 3000:3000 theiaide/theia-full:next --plugins=local-dir:/home/theia/plugins
   

   Note: When you start the container as above, the default workspace in which to store program files will be inside the Docker container. If you want to try Theia with your own local files, you can mount a local directory as the workspace instead. CD into the directory that contains your sample programs first, and then use these modified commands instead that will map the current directory as the /home/project directory in the container.

   Linux or macOS

   docker run -it --init -p 3000:3000 -v "$(pwd):/home/project:cached" theiaide/theia-full:next --plugins=local-dir:/home/theia/plugins
   

   Windows

   docker run -it --init -p 3000:3000 -v "%cd%:/home/project:cached" theiaide/theia-full:next --plugins=local-dir:/home/theia/plugins
   

2. Open a web browser and navigate to http://localhost:3000.

3. The extensions of Z Open Editor and Zowe Explorer are currently not included yet. You need to update the Docker container by copying these extensions into the container. To install Z Open Editor, run the following command. Ensure to replace ${container-id} with the actual container ID and adjust for your OS. You might also need to change the name of the vsix file in the command.

   docker cp ~/Downloads/IBM.zopeneditor-0.4.1.vsix ${container-id}:/home/theia
   

   If you also want to install the Zowe Explorer vsix file, run the command above by replacing the vsix file name, for example, Zowe.vscode-extension-for-zowe-0.29.0.vsix.

4. Then, log on to your container as root and move it in the right location:

   $ docker exec -u 0 -it ${container-id} bash
   # mkdir plugins
   # mv *.vsix plugins
   

5. Restart the container and reload your browser.

You are now able to create COBOL and PL/I files and see the Zowe Explorer views. To install more extensions into the container, go back to the container root shell. For example, you can install Zowe CLI into the container now as well.

Alternative 3: Build Theia from source

If you are interested in the Eclipse Theia project and want to try building it from source to explore it further, you can certainly do that and load Z Open Editor with it.

The Theia development team provides a very detailed document on how to set up your workspace. In particular, it lists all the dependencies required on your development machine, which differs quite a bit depending on the OS you are working on.

For more details, see the main Theia Developer Guide: https://github.com/eclipse-theia/theia/blob/master/doc/Developing.md.

The main prerequisites are still Node V10 and Yarn. However, on a Windows PC, you need more dependencies such as the Windows Build Tools. The developer guide proposes to install the Windows package manager Choco and then use it for the installation of most dependencies including Node and Yarn.

After the prerequisites are set up, the steps for building Theia are basically to clone the repository and run yarn to build everything. If the build process aborts with errors, check for fixes in the Troubleshoot sections of the Theia development guide.

Once everything is built, running Theia with Z Open Editor and Zowe Explorer requires these additional steps:

1. Create a folder called plugins in the top-level Theia folder you cloned.
2. Copy the Z Open Editor and Zowe Explorer vsix files into that plugins folder.
3. Run the command cd examples/browser.
4. Run the command yarn start.
5. Open a web browser and navigate to http://localhost:3000.