Using Z Open Editor on GitHub Codespaces

IBM Z® Open Editor, Zowe™ Explorer and Zowe™ CLI can run on Microsoft's GitHub Codespaces.

Overview

GitHub Codespaces is built on VS Code's Dev Container technology, which allows developers to write their code in a container that runs either locally or remotely. VS Code can then connect to that container and allow access to the folders inside the container. It also installs VS Code extensions from the marketplace in the container, so the extension can work with the files located there. In addition to connect the rich VS Code client to the container, it also supports to run the VS Code editor client in the browser where a VS Code Server, which runs inside the container, renders the editor in browser. See Developing inside a Container in the VS Code documentation for more details on the underlying technology. To learn everything about GitHub Code Spaces go to the official Documentation.

When using GitHub codespaces, the container runs in Microsoft's Azure Cloud and gets dynamically created for your account on a virtual machine managed by Azure. As a user, you need not procure a development machine that can run containers; all you need is browser and a GitHub account with Git projects to write code. You can use the same container specification, the devcontainer files that you are using for Codespaces for local or on-premises deployment of these containers as well, giving you great flexibility to decide where to run your remote development environments. This allows you to chose between paying for Cloud-based compute resources or to manage your own infrastructure of virtual machines in which the containers can run.

This architecture is different than Red Hat® OpenShift Dev Spaces, which comes with pros and cons:

• Codespaces runs in a container and not Kubernetes: The biggest difference is that Codespaces runs in a container that can be modified by the developer at runtime. Developers can install additional software and update components. You can even make devcontainer configuration changes on the fly and let VS Code recreate the container with the new components and settings from within VS Code. OpenShift Dev Spaces workspaces run in Kubernetes as immutable containers that cannot be modified by the developer. For installing additional or updated software, Dev Spaces requires building and publishing a new image from a dockerfile. The advantage is that these containers are more secure, because developers cannot randomly install software that was not reviewed and approved by your organization. This also ensures that all developers in a team work with the exact same versions and configuration settings, avoiding the "it runs in my container" effect.
• Codespaces is only available at github.com: OpenShift Dev Spaces can be installed wherever OpenShift runs, which includes on-premises deployments using x86 as well as s390x Linux on Z platforms, deployments at all the major Cloud providers such as IBM Cloud®, AWS, or Azure, and even your personal laptop or developer machine with OpenShift Local. GitHub Codespaces is only available on github.com. It is not available for GitHub Enterprise for on-premises deployments. However, you can use it from a private organization and you can configure it with access to your company network using OpenVPN technology as described below in Connecting to a z/OS system using a VPN.
• Codespaces configuration files are portable to custom containers: The devfiles you create for OpenShift DevSpaces workspaces can only be used at the moment, in an OpenShift Dev Spaces deployment. However, the Codespaces devcontainer files and dockerfiles can generally be used interchangeably between Codespaces and personal containers to run locally on your developer machine or on on-premises virtual machines.

Configure a sample Z Open Editor workspace

In our Z Open Editor Samples Git repository at https://github.com/IBM/zopeneditor-sample we provide a special branch called "devcontainer" that contains examples for Codespaces configuration files that you can try. As described in the Quickstart section of Overview to using Cloud and Browser-based platforms, you can easily start a Codespaces workspace with our samples repository loaded and Z Open Editor and other extensions preloaded by clicking or copy-pasting a simple URL:

https://github.com/codespaces/new?skip_quickstart=true&machine=basicLinux32gb&repo=160883618&ref=devcontainer&geo=UsWest&devcontainer_path=.devcontainer%2Fdevcontainer.json

If you examine this URL carefully, you see various parameters that specify what should be loaded into the workspace. When you click the link, you see all the parameters in a Web form to change or just confirm. The parameters provide the location and type of the virtual machine to be used, the GitHub repository to load identified with its global integer ID, the branch of the repository to check out, as well as the location of the devcontainer specification file to use. The last parameter allows you to manage several alternative devcontainer specification files in the same branch, but loads different development configurations on demand if needed. In our sample repository, you also find several examples inside this folder organized in sub-directories, which is discussed throughout this documentation.

To examine the sample devcontainer specification file provided with our Z Open Editor samples, open the following file from the Git repository: https://github.com/IBM/zopeneditor-sample/blob/devcontainer/.devcontainer/devcontainer.json

The file is located in a folder called ".devcontainer", together with a Bash script called "installZowe.sh". Inside the JSON file, you can see various configuration settings:

• "image": is the base image for the container to be loaded. The recommendation is, if in doubt about which image to use, to list the named "universal" as the default. It is documented at https://github.com/devcontainers/images/tree/main/src/universal. However, there are many special images available as well. Because Z Open Editor requires a Java™ 17 runtime, we selected in our devcontainer file a Java base image. For the full list of available images see here: https://github.com/devcontainers/images/blob/main/README.md
• "features": in addition to the software available on the base image, you can easily specify additional features you want without the need to create a custom container image using a dockerfile. You can just specify features that you want to see, added by name with parameters and loaded dynamically into the container. The first time you load the container, startup of the workspace takes a little bit longer to load the features, but then as a result the container caches and loads up much faster at the next startup. In our example, you see that we configure Java with an additional Maven option, because our Z Open Editor preprocessor samples provided in our repository comes with a Maven Java project. We also install node.js, which is required for Zowe™ CLI. We install Ansible for the z/OS Ansible® playbooks provided in our repository. Once the Codespaces workspace is up, open a Terminal window and check if all the components are available, e.g. run ansible --version or mvn -version to see version information. The list of available features is absolutely massive, as you can see on the reference page here: https://containers.dev/features.
• "updateContentCommand": can provide a command to load additional content into the image that is not available as a feature. In our case we run the "installZowe.sh" script, which simply uses npm to install Zowe CLI and the IBM® RSE API for Zowe CLI plugin.
• "customizations": contains settings to configure VS Code, Codespaces, as well as the VS Code extensions that should be preloaded into the devcontainer. In our example, you see we are loading all the recommended extensions to work with Z Open Editor, which includes Zowe Explorer, Red Hat's YAML extension for editing ZAPP files, Red Hat's Ansible extension, as well as the Java development pack to build the Java samples in our repository mentioned above.

When you load our Z Open Editor sample workspace into Codespaces with the URL listed above. The VS Code starts up in your browser, our sample Git repository gets automatically cloned with the devcontainer branch as specified and loads into VS Code. When you check the list of installed VS Code extensions, you find all the extension listed in the devcontainer.json file ready to go. When you open a Terminal, you can test the installed software, e.g. with the command line examples from above, and you can find everything available as specified.

There a several other ways to configure a devcontainer, including installing additional software with a dockerfile. To learn more about it see the Codespaces documentation.

Connect to a z/OS® system using a VPN

As GitHub Codespaces runs on github.com and Azure, you need to establish a secure network configuration from your devcontainer to your company's intranet to access mainframe resources with Zowe Explorer and Zowe CLI. To accomplish that connect to your organization using a Virtual Private Network as described in the Connecting to a private network in the Codespaces documentation.

The documentation page links to a Git repository with an example that we have integrated into our Z Open Editor sample repository, to try with our editor and Zowe Explorer. Under .devcontainer/vpn you find another complete example for a devcontainer that does everything the specification in the earlier example does, but also adds the ability to connect to a VPN server. To accomplish that it provides the following additions:

• "Dockerfile": which uses the same base image as the devcontainer specification of the previous example and adds the VPN client software installation instructions.
• "devcontainer.json": refers to the dockerfile, instead to load the resulting image. It also adds "runArgs", "initializeCommand", "postStartCommand" to initialize and start the VPN client through scripts provided in the folder as well.
• "save-config.sh": is a Bash script executed from the devcontainer that sets up the VPN client. The main thing it does is takes your personal OpenVPN configuration stored as a secret in Github under the name "OPENVPN_CONFIG" and serializes it to a temporary file that the VPN client can use to connect. See this example for how the secret looks.
• "start-openvpn.sh": starts the VPN client with the configuration prepared by "save-config.sh". You can always manually rerun this script if the VPN connection drops. The log file for the VPN client is stored in ".devcontainer/vpn/openvpn-tmp/openvpn.log", which you can open from your VS Code workspace to review it for any issues in connection.

Try this example in our devcontainer with the following steps:

• Fork our GitHub repository at https://github.com/IBM/zopeneditor-sample and checkout or select the branch "devcontainer".
• Receive an ".ovpn" file from your Open VPN administrator.
• In your personal fork on Github.com go to "Settings > Secrets and variables > Codespaces" and create a secret called "OPENVPN_CONFIG" and paste the contents of the ".ovpn" file.
• Go to the Code tab of your fork and start Codespaces through the "<> Code" dropdown menu to select the "Codespaces" tab and "New with options" from the sub-menu in that tab.
• In the "Create codespace" page, select in the "Dev container configuration" dropdown the value "Z Open Editor container with VPN". (Important to select and not use the default devcontainer without the VPN configuration.)
• Click "Create codespace"
• Once the workspace is up, create a Zowe Explorer Team Configuration file to connect to your z/OS system made available through the VPN.

If you are using IBM Wazi as Service (Documentation) virtual z/OS server instances (VSI) that run in an IBM Cloud® VPC (Virtual Private Cloud), then this is how you can access your VSIs.

• Create a VPN server for your VPC at https://cloud.ibm.com/infrastructure/network/vpngateways.
• Configure a Route and attach your security groups for accessing z/OSMF or RSE API to the VPN server.
• Download the VPN's "Client profile", which is a zip file that contains the ".ovpn" file.
• Paste the contents of the ".ovpn" file as the secret in your Github repository fork.
• Connect as described above.

You can access your Wazi as a Service VSI running in IBM Cloud from your Zowe Explorer running on Azure through a secure VPN tunnel.