Update installation, configuration, and demo guide

Signed-off-by: hhpatel14 <[email protected]>
hhpatel14 · Jan 31, 2025 · 81fa243 · 81fa243
1 parent 20d9c79
commit 81fa243
Show file tree

Hide file tree

Showing 24 changed files with 174 additions and 211 deletions.
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -0,0 +1,31 @@
+# Using the IDE Plugin
+
+## Get a Demo App or Any App You Like to Migrate
+
+1. Clone the Cool-store application:
+   ```bash
+   git clone https://github.com/konveyor-ecosystem/coolstore.git
+   ```
+2. Navigate to File > Open in VSCode and locate the folder we just cloned.
+
+### Running Kai RPC server
+
+1. Users will land on the welcome page after installation as shown below. If the Welcome Page does not appear, proceed to the step 2.
+   ![walkthrough](images/walkthrough-1.png)
+   If "Set up Konveyor" is not available in the list, click the More button for additional options.
+   ![walkthrough](images/walkthrough-2.png)
+2. If the welcome page does not appear, open the command palette by pressing Command + Shift + P. This will bring up a list of commands.
+   ![walkthrough](images/walkthrough-3.png)
+   From the command palette, locate and select the "Set up Konveyor" option. This will guide you through the configuration process.
+   ![walkthrough](images/walkthrough-4.png)
+3. Configure Konveyor for your project.
+   - User has an option to override binaries and custom rules, however it comes with the default packaged binaries and custom rules.
+     ![setup-konveyor](images/setup-konveyor.png)
+   - The Konveyor extension allows you to add custom rules to the analyzer. This is useful when you want to apply your own rules during analysis.
+   - Configuring analysis arguments is necessary to determine which rules apply to the project during analysis. Set up analysis arguments specific to your project by selecting the appropriate options and pressing "OK" to save the changes.
+     - To confirm your arguments, navigate to your project directory and open `/.vscode/settings.json`.
+       ![setup-konveyor](images/setup-konveyor-2.png)
+   - Next, set up the Generative AI key for your project. This step will open the `provider-settings.yaml` file. By default, it is configured to use OpenAI. To change the model, update the anchor `&active` to the desired block. Modify this file with the required arguments, such as the model and API key, to complete the setup. Sample of the `provider-settings.yaml` can be found [here.](https://github.com/konveyor/editor-extensions/blob/main/vscode/resources/sample-provider-settings.yaml)
+   - As the final step, select "Get Solution Parameters".
+4. Once the configuration is done, click on start server button. Logs are collected at output channel named konveyor-analyzer.
+   ![start-server](images/start-server.png)
diff --git a/docs/debug.md b/docs/debug.md
@@ -0,0 +1,48 @@
+# Debug Kai And File Issues
+
+Logs are divided into two separate files under your working directory at /.vscode/konveyor-logs:
+
+- kai-analyzer-server.log: This file is useful for debugging issues related to running analysis. It provides details about the Java and Maven installation, the initialization of the Java connection, and the startup process of the analyzer server.
+
+- kai-rpc-server.log: This log is intended for debugging the RPC server and any communication with the AI system. It captures interactions involved in fixing incidents and retrieving results.
+
+## File an Issue
+
+Please Fill out all the information requested below when opening an issue [here](https://github.com/konveyor/kai/issues).
+
+### Detailed Guidelines
+
+```md
+Help us resolve your issue faster by providing detailed information. Please follow the structure below to ensure we have all the necessary details:
+
+1.Issue Description\*\*
+
+- Summary: Briefly describe the problem.
+- Logs: Attach any relevant log files (e.g., `kai-analyzer-server.log` or `kai-rpc-server.log`) to help us identify the issue.
+
+2. Steps to Reproduce\*\*
+
+- Provide a step-by-step guide on how to reproduce the issue if possible.
+
+3. Environment Details
+   Please include the following information to help us better understand your setup:
+
+- Operating System (OS): (e.g., Windows 11, macOS Ventura, Ubuntu 22.04)
+- Java Version: (e.g., OpenJDK 17.0.2)
+- Maven Version: (e.g., Apache Maven 3.8.4)
+- VS Code Version: (e.g., 1.82.0)
+- Kai Version: (e.g., v0.0.6)
+
+4.  Additional Details
+
+- Error Messages: Include any error messages or stack traces you encountered.
+- Screenshots: Attach screenshots to illustrate the issue, if applicable.
+- Expected Behavior: Describe what you expected to happen.
+- Actual Behavior: Describe what actually happened.
+```
+
+### Troubleshooting
+
+- **No Incidents Found**: Check the `.vscode/settings.json` file in your working directory to ensure the targets are correctly recorded.
+
+- **Failed to Run Initial Analysis**: Verify that the correct Java and Maven versions are set in the current environment. Detailed logs can be found in `kai-analyzer-server.log`.
diff --git a/docs/images/konveyor_analysis_view.png b/docs/images/konveyor_analysis_view.png
diff --git a/docs/images/konveyor_analysis_view_1.png b/docs/images/konveyor_analysis_view_1.png
diff --git a/docs/images/run_analysis.png b/docs/images/run_analysis.png
diff --git a/docs/images/setup-konveyor-2.png b/docs/images/setup-konveyor-2.png
diff --git a/docs/images/walkthrough-1.png b/docs/images/walkthrough-1.png
diff --git a/docs/images/walkthrough-2.png b/docs/images/walkthrough-2.png
diff --git a/docs/images/walkthrough-3.png b/docs/images/walkthrough-3.png
diff --git a/docs/images/walkthrough-4.png b/docs/images/walkthrough-4.png
diff --git a/docs/installation.md b/docs/installation.md
@@ -7,10 +7,8 @@ We provide pre-built versions of the IDE plugin as a `vsix` file at [editor-exte
 ## Pre-requisite
 
 1. Install **Java 17 or later** and the latest version of **Maven**.
-2. Set up the required environment variables for the LLM service you plan to use. Refer to the [LLM Selection Guide](/docs/llm_selection.md) for details.
 
-   - For OpenAI: `OPENAI_API_KEY=my-secret-api-key-value`
-   - For IBM BAM: `GENAI_KEY=my-secret-api-key-value`
+2. Required LLM model and key to use the Kai. Refer to the [LLM Selection Guide](/docs/llm_selection.md) for details.
 
 ## IDE Plugin Installation Methods
 
@@ -38,23 +36,3 @@ Only follow these steps if you decided to skip installing from the UI side and y
    code --install-extension path/to/your-extension.vsix
    ```
 3. Restart/reload VSCode.
-
-## Using the IDE Plugin
-
-### Get a Demo App
-
-1. Clone the Cool-store application:
-   ```bash
-   git clone https://github.com/konveyor-ecosystem/coolstore.git
-   ```
-2. Navigate to File > Open in VSCode and locate the folder we just cloned.
-
-### Running Kai RPC server
-
-1. Open walkthrough after installing the extension to setup Konveyor
-   ![walkthrough](images/walkthrough.png)
-2. User has an option to override binaries and custom rules, however it comes with the default packaged binaries and custom rules.
-   ![setup-konveyor](images/setup-konveyor.png)
-3. Configure analysis argument is necessary in order to know which rules apply to the project during analysis.
-4. Once the configuration is done, click on start server button. Logs are collected at output channel named konveyor-analyzer.
-   ![start-server](images/start-server.png)
diff --git a/docs/scenarios/catalogService.png b/docs/scenarios/catalogService.png
diff --git a/docs/scenarios/cdi_bean_requirement.png b/docs/scenarios/cdi_bean_requirement.png
diff --git a/docs/scenarios/change_import_namespaces.png b/docs/scenarios/change_import_namespaces.png