Merge pull request #206 from b-tsao/silent-install

Silent installation files

Author: equalchenbj

silent_install/README.md

@@ -0,0 +1,109 @@
+# Silently installing VS Code and Db2 Developer Extension
+
+The information in this readme describes how to use the provided sample files to deploy an instance of Microsoft Visual Studio Code (VS Code) that has been preconfigured with IBM Db2 for z/OS Developer Extension to one or more Windows client machines.
+
+Extensions are normally packaged as a vsix artifact and these vsix artifact are typically installed manually into VS Code. The purpose of this silent installation is to automate this installation process consistently across an environment.
+
+---
+
+**IMPORTANT:** The script, sample json files, and instructions are provided only as an example of how you can automate the installation of VS Code and Db2 Developer Extension. Use them as a reference to create an automated installation process for your specific purposes.
+
+---
+
+**CAUTION:** Running the script that is provided in this package will replace any existing VS Code installations with a clean VS Code environment that includes only Db2 for z/OS Developer Extension. Users who have an existing VS Code environment will lose their VS Code environment including all the extensions that they have installed and all customizations that they have made. Handling installations in which users are already using VS Code will require more complex scripting and is outside the scope of these materials.
+
+## Components involved in the installation
+
+This installation process involves several sample files that you will customize for your environment and several external components that you will need to obtain on your own. You must include all components listed in this section when you create your installation package.
+
+The provided sample files include:
+
+-   A Powershell script (setup.ps1) for installing and configuring VS Code and Db2 Developer Extension on Windows
+
+-   settings.json, which controls the VS Code settings for Db2 Developer Extension on each client machine
+
+-   connections.json, which you can use to specify the Db2 connections that you want to create on each client machine
+
+-   tuning_services_servers.json and tuning_associations.json, which you can use to add a tuning services server and to associate a tuning profile with a Db2 connection
+
+Components that you need to obtain or provide include:
+
+-   The VS Code installer, which you can download from https://code.visualstudio.com/download.
+
+-   The Db2 for z/OS Developer Extension vsix artifact, which you can download from https://github.com/IBM/db2forzosdeveloperextension-about/releases
+
+-   A valid jcc license
+
+## Before you begin
+
+-   Make sure that Java is installed on each client machine that you intend to deploy VS Code and Db2 Developer Extension.
+
+-   If you intend to use Db2 Developer Extension to analyze and tune SQL statements, ensure that SQL Tuning Services has been installed and that a connection to the SQL Tuning Services server is available.
+
+## Instructions
+
+1. Download the VS Code installer and the Db2 Developer Extension vsix artifact from the locations identified in the “Components involved in the installation section” and obtain the jcc license file for your organization. Save these files in the same folder as the setup.ps1 script and sample json files.
+
+2. Edit setup.ps1 and set the following variables:
+
+    - Set the `InstallerPath` variable to the folder where you saved the installation files.
+
+    - Set the `JccLicensePath` variable to the name of your Db2 for z/OS JCC driver license.
+
+    At the time of this writing, the values for the `VSCodeInstallerName` and `VSCodeExtensionName` variables were current. These values will need to be updated when newer versions of the installer or extension are released.
+
+3. Optional: Specify any Db2 connections, SQL Tuning Services servers, and tuning profile associations that you want to predefine on client workstations.
+
+    **IMPORTANT:** The connections.json, tuning_services_servers.json, and tuning_associations.json files are provided as examples of the settings for these items. However, instead of modifying these files directly, it is recommended that you copy the relevant files from an existing Db2 Developer Extension installation on which the connections, tuning servers, and tuning profile information have already been defined. By default, this information is stored in the following files:
+
+    - `<VSCode_location_path>/globalStorage/ibm.db2forzosdeveloperextension/connections.json`
+    - `<VSCode_location_path>/globalStorage/ibm.db2forzosdeveloperextension/tuning_services/tuning_services_servers.json`
+    - `<VSCode_location_path>/globalStorage/ibm.db2forzosdeveloperextension/tuning_services/tuning_associations.json`
+
+4. Customize the sample settings.json file with any VS Code settings for Db2 Developer Extension that you want to apply as defaults across your environment. See https://code.visualstudio.com/docs/editor/extension-marketplace#_configuring-extensions for an explanation of VS Code settings.
+
+    The sample setting.json file contains the following parameters:
+
+    - `db2forzosdeveloperextension.db2sqlservice.dependencies` specifies the path to where Db2z jcc license is available.
+
+    - `db2forzosdeveloperextension.java.home` specifies the path to where JAVA_HOME is available.
+
+    - `db2forzosdeveloperextension.db2sqlservice.port` specifies the port that is used exclusively for inter-process communication (IPC), which means that no traffic must go through a firewall.
+
+    - `db2forzosdeveloperextension.db2sqlservice.debugger.sessionManagerPort` specifies the port that needs to be available for traffic inbound via client machine firewall.
+
+        **Note:** These four settings, as well as additional Db2 Developer Extension settings, can be modified manually after the extension has been installed. To do so, click the **Manage** icon at the lower left corner of the VS Code window, then click **Settings > Extension > IBM Db2 for z/OS Developer Extension**.
+
+5. Make sure that the script, sample json files, VS Code installer, and Db2 Developer Extension vsix artifact are in the same folder.
+
+6. The script is now ready to run. Deploy it using whatever mechanism you use to perform silent installations.
+
+After the script completes sucessfully on each client workstation, users should be able to open VS Code and see that Db2 Developer Extension is installed. If you defined Db2 connection information and SQL Tuning Services information, users should see this information in the primary side bar of the Db2 Developer Extension interface.
+
+## Troubleshooting
+
+This section documents some common installation problems and potential solutions:
+
+-   The following error indicates that your system is not enabled to run scripts:
+
+    ```
+    .\setup.ps1 : File C:\Users\Administrator\Downloads\setup\setup.ps1 cannot be loaded because running scripts is disabled on this system.
+    ```
+
+    If so, run the `Set-ExecutionPolicy RemoteSigned` command and then rerun setup.ps1. After you run the script, run the `Set-ExecutionPolicy Restricted` command to revert to the previous security setting.
+
+-   If you receive the following error message:
+
+    ```
+    Access to the registry key
+
+    'HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\PowerShell\1\ShellIds\Microsoft.PowerShell' is denied.
+
+    To change the execution policy for the default (LocalMachine) scope,
+    start Windows PowerShell with the "Run as administrator" option.
+
+    To change the execution policy for the current user,
+    run "Set-ExecutionPolicy -Scope CurrentUser".
+    ```
+
+    Run the `Set-ExecutionPolicy RemoteSigned -Scope CurrentUser` command.

silent_install/connections.json

@@ -0,0 +1,16 @@
+{
+  "16160e89-8ce2-45d0-9045-fda49e87a11d": {
+    "name": "Db2zHost/LOCATION",
+    "server": "Db2zHost",
+    "port": "446",
+    "location": "LOCATION",
+    "authType": "REGULAR",
+    "savePassword": false,
+    "traceLevel": 0,
+    "traceFileAppend": false,
+    "tuningProfileToggle": true,
+    "jdbcProperties": {
+      "ExampleJdbcProp": "ExampleJdbcVal"
+    }
+  }
+}

silent_install/settings.json

@@ -0,0 +1,6 @@
+{
+  "db2forzosdeveloperextension.db2sqlservice.dependencies": "C:\\Users\\Administrator\\Documents\\lib\\*",
+  "db2forzosdeveloperextension.java.home": "C:\\Program Files\\Java\\jre1.8.0_431",
+  "db2forzosdeveloperextension.db2sqlservice.port": "3000-3050",
+  "db2forzosdeveloperextension.db2sqlservice.debugger.sessionManagerPort": "4555-4605"
+}