From 0525bc062305fdb1bff5829e4394d92405653d37 Mon Sep 17 00:00:00 2001 From: "S. Ishida" Date: Thu, 24 Oct 2019 16:19:40 -0400 Subject: [PATCH] Update to latest 050 (#194) Signed-off-by: Sarah Ishida --- docs/_data/newstoc.yml | 3 + docs/_documentations/dockerregistry.md | 2 +- docs/_documentations/installoncloud.md | 38 +++-- docs/_documentations/mdt-che-overview.md | 12 ++ .../mdt-eclipse-importedprojects.md | 8 +- .../mdt-vsc-commands-project.md | 21 +-- .../mdt-vsc-importedprojects.md | 8 +- docs/_documentations/mdt-vsc-overview.md | 2 +- docs/_documentations/troubleshooting.md | 142 +++++++++++++++++- docs/_includes/topbar.html | 2 +- docs/_news/news05.md | 35 +++++ 11 files changed, 242 insertions(+), 31 deletions(-) create mode 100644 docs/_news/news05.md diff --git a/docs/_data/newstoc.yml b/docs/_data/newstoc.yml index 296f47b8..7329b604 100644 --- a/docs/_data/newstoc.yml +++ b/docs/_data/newstoc.yml @@ -1,3 +1,6 @@ +- title: 'Codewind 0.50' + url: news05.html + - title: 'Codewind 0.40' url: news04.html diff --git a/docs/_documentations/dockerregistry.md b/docs/_documentations/dockerregistry.md index ca69b001..99c673d9 100644 --- a/docs/_documentations/dockerregistry.md +++ b/docs/_documentations/dockerregistry.md @@ -50,7 +50,7 @@ Before you deploy your project with Codewind, first specify a deployment registr 1. When you first deploy a project in Codewind, Codewind prompts you to set a deployment registry. - If Codewind detects the registry is unset, Codewind prompts before deploying a project. 2. Enter a path with which to push your container. - - **Important:** Before attempting this step, ensure that you have entered the registry credentials with the Che dashboard. + - **Important:** Before attempting this step, ensure that you have correctly entered the registry credentials in the Che dashboard in Step 1. 3. Codewind asks if you want to verify push permissions. If you select **yes**, Codewind pushes a small `hello-world` image to the registry to verify permissions. ### Instructions specific to IBM Cloud Private diff --git a/docs/_documentations/installoncloud.md b/docs/_documentations/installoncloud.md index b0d6244f..c7b376a8 100644 --- a/docs/_documentations/installoncloud.md +++ b/docs/_documentations/installoncloud.md @@ -19,6 +19,7 @@ parent: root 4. [After installing Che](#after-installing-che) 5. [Creating the Codewind workspace](#creating-the-codewind-workspace) 6. [Updating the version](#updating-the-version) +7. [Adding additional rules to support Codewind ODO extension](#adding-additional-rules-to-support-codewind-odo-extension) ## Prerequisites - Set up the PersistentVolume (PV) with either Network File System (NFS) or GlusterFS. @@ -27,7 +28,7 @@ parent: root - Ensure the cluster can pull images from `docker.io/eclipse`. - Both Eclipse Che and Eclipse Codewind host their Docker images on `docker.io/eclipse`. Ensure that your cluster can pull from that registry and does not have `PodSecurityPolicies` blocking it from accessing Docker Hub. - Set up the ClusterRole for Codewind. - 1. Clone the [Codewind Che plug-in repository](https://github.com/eclipse/codewind-che-plugin) + 1. Clone the [Codewind Che plug-in repository](https://github.com/eclipse/codewind-che-plugin). 2. Enter the `cd` command to go to the `codewind-che-plugin` repository. 3. Run the `kubectl apply -f setup/install_che/codewind-clusterrole.yaml` command to create a cluster role with the required permission. 4. Next, run the `kubectl apply -f setup/install_che/codewind-rolebinding.yaml` command. @@ -41,7 +42,7 @@ Complete the following steps after you install `chectl`: 1. Download the [codewind-che checluster yaml](https://github.com/eclipse/codewind-che-plugin/blob/master/setup/install_che/che-operator/codewind-checluster.yaml) file to your machine. - You can modify this file, but leave the `spec.server.cheWorkspaceClusterRole` field set to `eclipse-codewind` and the `spec.storage.preCreateSubPaths` field set to `true`. 2. If you're installing on a Kubernetes platform other than OpenShift, determine your Ingress domain. If you're unsure of your Ingress domain, ask your cluster administrator. - - Set the `spec.server.ingressDomain` field in the Che .yaml to the Ingress domain. + - Set the `spec.server.ingressDomain` field in the Che `.yaml` to the Ingress domain. 3. Install Che: - On OpenShift 3.x run the following command: `chectl server:start --platform=openshift --installer=operator --che-operator-cr-yaml=` - On Kubernetes run the following command: `chectl server:start --platform=k8s --installer=operator --domain= --che-operator-cr-yaml=` @@ -55,21 +56,20 @@ Codewind is required to run as privileged and as root, because it builds contain ### Adding registries in Che After Che is started and running, add the container registry that will be used with Codewind. -- On IBM Cloud Private, push your -to any Docker registry *except* the internal Docker registry -- On OpenShift or other Kube platforms, you can push your images to any Docker registry, such as Dockerhub, Quay.io, Google Cloud Registry (GCR), and more. +- On OpenShift or other Kube platforms, you can push your images to any Docker registry, such as Docker Hub, Quay.io, Google Cloud Registry (GCR), and more. +- On IBM Cloud Private, you can push your image to any Docker registry *except* the internal Docker registry. -Complete the following instructions to add the registries: +You'll need the following information to complete the instructions to add the registries: - Server: `` - Username: `` - Password: `` -For further information on adding deployment registries to Che, consult our [registry documentation](https://www.eclipse.org/codewind/dockerregistry.html) +For information on adding deployment registries to Che, consult our [registry documentation](https://www.eclipse.org/codewind/dockerregistry.html). ## Creating the Codewind workspace ### Confirm the Docker registry secrets. -Confirm that you added the docker registry secrets in the Che dashboard. Go to **Administration**>**Add Registry** to check for the secrets. +Confirm that you added the Docker registry secrets in the Che dashboard. Go to **Administration**>**Add Registry** to check for the secrets. ### Creating the Codewind workspace with a Devfile The general format for creating a Che workspace via a factory is: @@ -77,7 +77,7 @@ The general format for creating a Che workspace via a factory is: http:///f?url= ``` -We provide a ready-to-use devfile with the Codewind plug-ins. Enter the following URL to create a workspace from the devfile: +Codewind includes a ready-to-use devfile with its plug-ins. Enter the following URL to create a workspace from the devfile: ``` http:///f?url=https://raw.githubusercontent.com/eclipse/codewind-che-plugin/master/devfiles/0.4/devfile.yaml ``` @@ -101,7 +101,7 @@ For more information about Tekton, see [Getting started with the Tekton Dashboar ## After installing Codewind ### Setting the Docker registry -Upon creating a Codewind workspace. The container registry to deploy your projects to must be set. When you go to create or add an existing project to Codewind, Codewind will prompt you for the registry. See (Docker registry docs) for guidance on using proper container registries +After creating a Codewind workspace. The container registry to deploy your projects to must be set. When you go to create or add an existing project to Codewind, Codewind will prompt you for the registry. See [Docker registry docs](https://www.eclipse.org/codewind/dockerregistry.html) for guidance on using proper container registries. If you would like to change the registry that's used at any time, run the `Codewind: Set Deployment Registry` command in Theia to dynamically set a new registry for your workspace.
@@ -136,4 +136,20 @@ Go to **View**>**Find Command…**>**Codewind: Build**. - Enter the following command: `curl -k -H "Content-Type: application/json" -X POST https://codewind-release:9191/api/v1/projects/8801a6d0-7805-11e9-b22f-19482c5ffbd6/build -d '{"action": "build"}'` ## Updating the version -Restart the Codewind workspace in Che. Che automatically pulls the newest version of Codewind and the Theia extension. \ No newline at end of file +Restart the Codewind workspace in Che. Che automatically pulls the newest version of Codewind and the Theia extension. + +## Adding additional rules to support Codewind ODO extension +The Codewind ODO extension needs to add additional rules for accessing OpenShift resources: +1. In your home directory, run the following command to clone the Codewind ODO extension repository: +``` +git clone https://github.com/eclipse/codewind-odo-extension +``` +2. Login to your OpenShift/OKD cluster +3. Go into `~/codewind-odo-extension/odo-RBAC` then run the following commands to add additional rules: +``` +kubectl apply -f codewind-odoclusterrole.yaml +kubectl apply -f codewind-odoclusterrolebinding.yaml +``` + +# Codewind OpenShift Do (ODO) extension +Extension to Codewind providing support for OpenShift projects: https://github.com/eclipse/codewind-odo-extension \ No newline at end of file diff --git a/docs/_documentations/mdt-che-overview.md b/docs/_documentations/mdt-che-overview.md index a0f473fa..0cda99e2 100644 --- a/docs/_documentations/mdt-che-overview.md +++ b/docs/_documentations/mdt-che-overview.md @@ -21,3 +21,15 @@ The Eclipse tools are [open source](https://github.com/eclipse/codewind-eclipse) To get started, see [Getting started with Codewind](mdteclipsegettingstarted.html). To uninstall Codewind, see [Uninstalling Codewind for Eclipse](mdteclipseuninstall.html) + +## Codewind OpenShift (ODO) extension +Extension to Codewind providing support for ODO projects: https://codewind.dev + +### Add additional rules to support Codewind ODO extension +The ODO extension needs to add additional rules for accessing OpenShift resources: +1. In your home directory, run the following command to clone the ODO extension repository: +`git clone https://github.com/eclipse/codewind-odo-extension` +2. Login to your OpenShift/OKD cluster +3. Go into `~/codewind-odo-extension/odo-RBAC` then run the following commands to add additional rules: +`kubectl apply -f codewind-odoclusterrole.yaml` +`kubectl apply -f codewind-odoclusterrolebinding.yaml` \ No newline at end of file diff --git a/docs/_documentations/mdt-eclipse-importedprojects.md b/docs/_documentations/mdt-eclipse-importedprojects.md index 3398eded..2721d931 100644 --- a/docs/_documentations/mdt-eclipse-importedprojects.md +++ b/docs/_documentations/mdt-eclipse-importedprojects.md @@ -12,7 +12,7 @@ order: 0 # Adding existing projects -Modifications are usually required to successfully add and deploy projects that have never been run in Codewind before. This guide covers the basics of configuring a project to run in Codewind. +Modifications are usually required to successfully add and deploy projects that have never been run in Codewind before. This guide covers the basics of configuring a project to run in Codewind. ## What kind of projects can I add? @@ -23,6 +23,7 @@ Codewind is designed to develop cloud native microservices. Therefore, each proj * [Node.js projects](#nodejs-projects) * [Swift projects](#swift-projects) * [Generic Docker projects](#generic-docker-projects) +* [Appsody projects](#appsody-projects) ## MicroProfile/Java EE projects @@ -191,3 +192,8 @@ For example, you should be able to build the project by using the command ## Generic Docker projects If you have a Dockerized application that doesn't fit an existing template, you can still add the project to Codewind by selecting the **Other (Basic Container)** option as the project type. For the application state detection to work, the Dockerfile needs to include an `EXPOSE` instruction to point to the port that is used to determine whether the project is running. + +## Appsody projects + +If you have an existing Appsody project, or a project that you want to add to Codewind as an Appsody project, select the corresponding Appsody project type and, if applicable, the Appsody stack when adding the project. +For more information about Appsody and Appsody stacks, see [https://appsody.dev](https://appsody.dev). diff --git a/docs/_documentations/mdt-vsc-commands-project.md b/docs/_documentations/mdt-vsc-commands-project.md index 9deaba45..81d209ae 100644 --- a/docs/_documentations/mdt-vsc-commands-project.md +++ b/docs/_documentations/mdt-vsc-commands-project.md @@ -23,20 +23,23 @@ Right-click a project in the **Codewind view** to see most project commands. All - **Open app**: Open the project application root endpoint in the system browser. The project must be in the *Running* or *Debugging* state, or the application server won't be available. -- **Open application monitor**: Open the Codewind **Application Monitor** page for this project in the system browser. +- **Open Project Overview**: Open an editor Tab that displays all of the Codewind information for the project. From this page, you can build, disable, or delete the project, and you can change the project auto build setting. -- **Open folder as workspace**: Open the project as your VS Code workspace folder. This command is useful if you want to work on just one project at a time per window. If you want the folder to open in a new window, set *window.openFoldersInNewWindow* to **true**. +- **Open Container Shell**: Open a shell, either *bash* or *sh*, in the project application container with *docker exec*. The project must have a container running. The VS Code integrated terminal needs access to your *PATH* environment variable so that it can run the *docker* command. -- **Show project overview**: Open an editor tab that displays all of the Codewind information for the project. From this page, you can build, disable, or delete the project, and you can change the project auto build setting. This page is the only place in the extension where you can delete a project. If you delete a project, you remove it from both Codewind and from your file system. +- **Open Application Monitor**: Open the Codewind **Application Monitor** page for this project in the system browser. -- **Build**: Manually request an application build for this project. If the project has auto build enabled, this command should not be necessary because builds are triggered automatically with a code change. This command is also available in the project info page. -This command is equivalent to clicking the **Build** button in the Codewind **Overview** page. +- **Open Performance Dashboard**: Opens the performance dashboard in the browser. This action is available only when the application is running or debugging. -- **Toggle auto build**: Enable or disable auto build for the project. This command is also available in the project info page. This command is equivalent to clicking the **Auto Build** toggle in the Codewind **Overview** page. +- **Add Project to Workspace**: Add this project's folder on your local disk to your VS Code workspace. -- **Open container shell**: Open a shell, either *bash* or *sh*, in the project application container with *docker exec*. The project must have a container running. The VS Code integrated terminal needs access to your *PATH* environment variable so that it can run the *docker* command. +- **Build**: Manually request an application build for this project. If the project has auto build enabled, this command should not be necessary because builds are triggered automatically with a code change. This command is also available in the project overview page. This command is equivalent to clicking the **Build** button in the Codewind **Overview** page. -- **Enable or disable project**: Enable or disable the project. This command is also available in the project info page.
+- **Toggle auto build**: Enable or disable auto build for the project. This command is also available in the project overview. + +- **Enable or disable project**: Enable or disable the project. This command is also available in the project overview. + +- **Remove project**: Removes the project from Codewind. The project folder can optionally be deleted from disk after removal. This command is also available in the project overview. ## Logs @@ -46,8 +49,6 @@ This command is equivalent to clicking the **Build** button in the Codewind **Ov - **Manage logs**: This command presents a list of all logs for this project, which you can toggle individually. -- **Project-specific settings**: Edit the internal app and debug ports as well as the **application endpoint**, sometimes known as the **context root**, from the **Project Overview** page. - ## Configuring project settings Project settings tell Codewind more about the specifics of your project and can affect the status and/or behaviour of your application. Project settings can be configured from the Project Overview page that is accessible from a project's context menu, or you can find the project settings in the `.cw-settings` file of the project which you can edit from the IDE. Changes to these fields are automatically picked up by the workspace. diff --git a/docs/_documentations/mdt-vsc-importedprojects.md b/docs/_documentations/mdt-vsc-importedprojects.md index a1f56f21..e866a5f8 100644 --- a/docs/_documentations/mdt-vsc-importedprojects.md +++ b/docs/_documentations/mdt-vsc-importedprojects.md @@ -12,7 +12,7 @@ order: 0 # Adding existing projects -Modifications are usually required to successfully add and deploy projects that have never been run in Codewind before. This guide covers the basics of configuring a project to run in Codewind. +Modifications are usually required to successfully add and deploy projects that have never been run in Codewind before. This guide covers the basics of configuring a project to run in Codewind. ## What kind of projects can I add? @@ -23,6 +23,7 @@ Codewind is designed to develop cloud native microservices. Therefore, each proj * [Node.js projects](#nodejs-projects) * [Swift projects](#swift-projects) * [Generic Docker projects](#generic-docker-projects) +* [Appsody projects](#appsody-projects) ## MicroProfile/Java EE projects @@ -192,3 +193,8 @@ For example, you should be able to build the project by using the command ## Generic Docker projects If you have a Dockerized application that doesn't fit an existing template, you can still add the project to Codewind by selecting the **Other (Basic Container)** option as the project type. For the application state detection to work, the Dockerfile needs to include an `EXPOSE` instruction to point to the port that is used to determine whether the project is running. + +## Appsody projects + +If you have an existing Appsody project, or a project that you want to add to Codewind as an Appsody project, select the corresponding Appsody project type and, if applicable, the Appsody stack when adding the project. +For more information about Appsody and Appsody stacks, see [https://appsody.dev](https://appsody.dev). diff --git a/docs/_documentations/mdt-vsc-overview.md b/docs/_documentations/mdt-vsc-overview.md index b4b9fb71..4b3aa6dd 100644 --- a/docs/_documentations/mdt-vsc-overview.md +++ b/docs/_documentations/mdt-vsc-overview.md @@ -1,6 +1,6 @@ --- layout: docs -title: "Codewindfor VS Code" +title: "Codewind for VS Code" description: "Codewind for VS Code" keywords: introducing, introduction, overview, what is, tools, vscode, visual, studio, code, java, microprofile, spring, node, nodejs, node.js, javascript, Codewind for VS Code, tools, view, debug, integrate, open a shell session, toggle auto build, manually build, scope VS Code workspace, disable, enable, delete duration: 1 minute diff --git a/docs/_documentations/troubleshooting.md b/docs/_documentations/troubleshooting.md index d60996b8..e8003646 100644 --- a/docs/_documentations/troubleshooting.md +++ b/docs/_documentations/troubleshooting.md @@ -23,13 +23,14 @@ The following sections contain workarounds for issues that you might encounter w * [Editing your project](#editing-your-project) * [Disabling development on specific projects](#disabling-development-on-specific-projects) * [Appsody with Codewind](#appsody-with-codewind) +* [ODO with Codewind](#odo-with-codewind) +* [OKD and OpenShift](#okd-and-openshift) * [Codewind and Tekton pipelines](#codewind-and-tekton-pipelines) * [OpenAPI tools](#openapi-tools) *** - # Installing Codewind +## Project creation fails if a persistent volume (PV) is unavailable +If you try to create a project on Codewind for Eclipse Che, errors might occur if a PV is unavailable for your cluster. + +**Workaround:** Run the `kubectl get pv` command to check that a PV is available for each project that you want to create. + +## Projects stuck in starting or stopped state +You might occasionally see projects stuck in the `Starting` or `Stopped` state even though the container logs say the projects are up and running. This can happen when you create a number of projects, for example, using the default and Appsody templates with Codewind 0.5.0. + +**Workaround** Manually rebuild the projects that are stuck in `Starting` or `Stopped` state. To do this: +1. In the **Codewind Explorer** view, right-click your project and select **Build**. +2. Wait for the project state to return to **Running** or **Debugging** in the **Codewind Explorer** view. + +*** # Importing a project +## ODO projects are not deleted after the workspace is deleted + +If you create ODO projects and then delete the workspace without deleting the projects, all your ODO deployments still exist. + +These steps reproduce the issue: +1. Install Codewind Che. +2. Create ODO projects. +3. Delete the Codewind workspace. +4. Create a new workspace. You still see previously created ODO project deployments. + +**Workaround** +1. Login to the OKD/OpenShift cluster. +2. Change to the project where the resources are by running the following command: + + ```sh + oc project + ``` + +3. Delete the ODO project resources by running the following command: + + ```sh + oc delete svc,route,dc,pvc,is -l=app.kubernetes.io/part-of=app + ``` + + Or for individual components: + + ```sh + oc delete svc,route,dc,pvc,is -l=app.kubernetes.io/instance= + ``` + +*** +# OKD and OpenShift + +## Plugin runtime crashes unexpectedly and all plugins are not working +With the latest Eclipse Che Version 7.2, you might see the following error when your user session expires for the Eclipse Che workspace: `Plugin runtime crashed unexpectedly, all plugins are not working, please reload ...` + +These steps reproduce the issue: +1. Install Eclipse Che on an OKD cluster. +2. Create your Codewind workspace from this [devfile](https://raw.githubusercontent.com/eclipse/codewind-che-plugin/master/devfiles/0.5.0/devfile.yaml). +3. After your session expires, you see a `Crash` message in the Codewind workspace. +**Workaround** Go to the `Che workspace` dashboard, log out of the Che workspace, and then log back in to the Che workspace. Access the Codewind workspace. + *** # Codewind and Tekton Pipelines @@ -416,7 +509,46 @@ These steps reproduce the issue: 6. Click **Finish**. The OpenAPI generator fails if the folder doesn't already exist. **Workaround:** -- Manually create the output folder before you start the OpenAPI generator wizard. In the wizard, you can manually edit the **Output folder** text field. Ensure that the path points to a valid folder in the project. -- Or you can use the **Browse...** button to select the folder that you want to use. The **Output folder** field is updated with the path. +For the VS Code extension, manually create the output folder before you start the OpenAPI generator wizard. In the wizard, you can also create the **Output folder** in the browse dialog. Ensure that the path points to a valid folder in the project. + +For post-client or post-server stub generation, use a separate output folder for code generation. Depending on the language and the generator type, the OpenAPI generator generates both source code files and build-related files. Some refactoring might be necessary. For example, move the generated source code to the proper source folder that already exists in the project. However, if your project is empty, the target output folder can be the root of the project, and you don’t need to do as much refactoring and merging. + +For Eclipse, for Java-based code generators, the Open API wizards provide additional support to configure the project. It is recommended that the project's root folder is selected as the output folder of the generator so that `.java` files will be generated into the existing `src/main/java` and `src/test/java` folders. The wizard's default value of the output folder is the project's root folder. The wizard also performs some automatic configuration, including `pom.xml` file merging, and necessary updates to the project's classpath. + + +## Plugin execution validation error in the pom.xml file +When generating a Java client or server stub into an existing Appsody or Codewind Liberty Microprofile project, you might see a plugin execution validation error in the `pom.xml` file: + +```sh +Plugin execution not covered by lifecycle configuration: org.codehaus.mojo:aspectj-maven-plugin:1.0:compile (execution: default, phase: process-classes) +``` + +The build is successful even though the validator reports this issue. + +**Workaround:** To resolve this in Eclipse, surround the plugins element under the `build` element of the `pom.xml` file with the `pluginManagement` element. -For post-client or post-server stub generation, use a separate output folder for code generation. Depending on the language and the generator type, the OpenAPI generator generates both source code files and build-related files. Some refactoring might be necessary. For example, if you are working with an existing Java or Maven project, move the generated source code to the proper source folder that already exists in the project. However, if your project is empty, the target output folder can be the root of the project, and you don't need to do as much refactoring and merging. \ No newline at end of file +```xml + + + + ... +``` + +The following work-around applies to both VS Code and Eclipse. The spring server generator creates invalid source in the `OpenAPI2SpringBoot` class. Simply implement the methods from the interface and save the file. Also add the configuration element to the `pom.xml` file, like this: + +```xml + + + + org.springframework.boot + spring-boot-maven-plugin + + org.openapitools.OpenAPI2SpringBoot + + .... +``` diff --git a/docs/_includes/topbar.html b/docs/_includes/topbar.html index 1b150d1b..843c7fac 100644 --- a/docs/_includes/topbar.html +++ b/docs/_includes/topbar.html @@ -13,7 +13,7 @@ Docs