From c98a7905d371b269380b167866fcdb27f9006137 Mon Sep 17 00:00:00 2001 From: zachaugenfeld <62358918+zachaugenfeld@users.noreply.github.com> Date: Sun, 22 Dec 2024 10:42:41 -0500 Subject: [PATCH] add powershell script install info (#445) * added powershell script install info * spellcheck * upd * upd * upd * upd * upd --------- Co-authored-by: Benson Lee --- .wordlist.txt | 6 +- docs/app/agents/DebuggingAgents.mdx | 117 ++++++++++++++++++++++++---- sidebars.js | 2 +- 3 files changed, 107 insertions(+), 18 deletions(-) diff --git a/.wordlist.txt b/.wordlist.txt index a40e2d5c..83749f34 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -409,4 +409,8 @@ GPT walkthroughs PlateReader QuickstartBuildFlow -DashboardTips \ No newline at end of file +DashboardTips +displayValue +tagTypeId +connectionName +installPath diff --git a/docs/app/agents/DebuggingAgents.mdx b/docs/app/agents/DebuggingAgents.mdx index 937621c8..28a6ee70 100644 --- a/docs/app/agents/DebuggingAgents.mdx +++ b/docs/app/agents/DebuggingAgents.mdx @@ -2,6 +2,7 @@ id: DebuggingAgents title: Agent FAQ and Troubleshooting displayed_sidebar: webUiSidebar +toc_max_heading_level: 5 --- ## FAQ @@ -42,11 +43,97 @@ watch_directory = Path(kwargs.get("vars", {}).get("input_path", DEFAULT_PATH)) #### Q: Can Windows Agents be installed headlessly? -A: Yes - Agent installers (v4.10+) can be installed headlessly. +A: Yes - Agent installers (v4.10+) can be installed headlessly, either with a [Powershell script](#using-a-powershell-script) or a [Windows batch script](#using-a-batch-script). -##### Requirements +##### Using a Powershell Script -The following files are needed: +###### Prerequisites + +- Agent installer (EXE, not MSI) with a minimum core Agent version of 4.10 +- A Powershell script (.ps1 file), such as the one shown below: + +```powershell +param ( + [string]$environment, + [string]$connectionName, + [array]$tagParams, + [string]$installPath +) + +# Get install path or use default +if ($installPath -eq '') { + $installPath = "C:\Program Files\Ganymede" +} +Write-Output "Will install to $installPath" + +# Get Connection name, or use computer name as default +if ($connectionName -eq '') { + $connectionName = $env:COMPUTERNAME +} +Write-Output "Connection will be named $connectionName" + +# Define the content of the YAML file +$content = @" +environment: $environment +name: $connectionName +tagParams:`n +"@ + +# Add Tag configuration to Connection +foreach ($tag in $tagParams) { + $content += " - tagTypeId: $($tag.tagTypeId)`n displayValue: $($tag.displayValue)`n" +} + +# Save the content to connection.yaml in the same folder +$filePath = Join-Path -Path $PSScriptRoot -ChildPath "connection.yaml" +$content | Out-File -FilePath $filePath -Encoding utf8 +Write-Output "File 'connection.yaml' created successfully at $filePath" + +# Create the install directory if it doesn't exist +New-Item -Path $installPath -Type "directory" -Force >$null + +# Copy the connection.yaml to the install directory +Copy-Item -Path $PSScriptRoot\connection.yaml -Destination $installPath -Force +Write-Output "File 'connection.yaml' copied to $installPath" + +# Copy the Agent installation executable (agent.exe) to the install directory +$agentFileName = Get-ChildItem -Path $PSScriptRoot -Filter *.exe |Select -First 1 +Copy-Item -Path $PSScriptRoot\$agentFileName -Destination $installPath -Force +Write-Output "File $agentFileName copied to $installPath" + +# Run agent.exe and wait for it to finish +$agentInstallerPath = Join-Path -Path $installPath -ChildPath $agentFileName +Start-Process -FilePath $agentInstallerPath -Wait + +Write-Output "$agentFileName has finished running" +``` + +###### Steps for executing headless installation script + +1. Ensure PowerShell is installed on your system. +1. Ensure the agent executable (.exe) and script file (.ps1) are in the same directory. +1. From a Powershell terminal, navigate to this directory. +1. Run the script using the following command: + +```powershell +.\.ps1 -environment -connectionName -tagParams -installPath +``` + +Parameters are defined as follows: +- **-environment** (string, required): Specifies the full environment name to install the agent in (e.g., development, staging, production). +- **-tagParams** (array, required): An array of tags to include in the YAML file. Each tag should be an object with tagTypeId and displayValue properties. +- **-connectionName** (string, optional): Sets the name for the connection. Defaults to the computer name if not provided. +- **-installPath** (string, optional): Path to the installation directory. Defaults to C:\Program Files\Ganymede if not specified. + +###### Example + +```powershell +.\agent_installer_script.ps1 -environment "env-prod" -connectionName "Hamilton PC 6" -tagParams @(@{tagTypeId="instrument"; displayValue="H6"}, @{tagTypeId="site"; displayValue="New York"}) -installPath "C:\Install\Agent\Here" +``` + +##### Using a Batch Script + +###### Prerequisites - Agent installer (EXE, not MSI) with a minimum core Agent version of 4.10 - Configuration file (YAML); examples of this can be found in the directory specified by the installer when not installed headlessly. Start with an existing YAML configuration and modify as follows: @@ -60,8 +147,7 @@ The following files are needed: - inferredData (any) - startTime - Version - -A Windows batch script, such as the one shown below, saved to a .bat file: +- A Windows batch script, such as the one shown below, saved to a .bat file: ```shell @ECHO OFF @@ -87,7 +173,7 @@ copy "%~dp0agent.exe" "%installpath%" /v /y ECHO Step 3: Adding user-provided variables to config file echo name: %connectionname%>>"%~dp0connection.yaml" echo variables:>>"%~dp0connection.yaml" -echo input_path: %watchdir%>>"%~dp0connection.yaml" +echo input_path: %watchdir%>>"%~dp0connection.yaml" ECHO Step 4: Copying config file copy "%~dp0connection.yaml" "%installpath%" /v /y @@ -103,17 +189,17 @@ An example for the configuration file (YAML) used with headless install is shown ```yaml environment: env-prod tagParams: -- displayValue: Microlab STAR 1 - tagId: null - tagTypeId: instrument - url: null -- displayValue: Hamilton - tagId: null - tagTypeId: vendor - url: null + - displayValue: Microlab STAR 1 + tagId: null + tagTypeId: instrument + url: null + - displayValue: Hamilton + tagId: null + tagTypeId: vendor + url: null ``` -##### Execution steps +###### Steps for executing headless installation script 1. Rename agent installer “agent.exe” 1. Name configuration file “connection.yaml” (if it has a different name) @@ -264,4 +350,3 @@ sc delete GanymedeAgent- ``` where _agent_name_ is the name of the Agent Connection. - diff --git a/sidebars.js b/sidebars.js index 708d9f6a..9435cd4e 100644 --- a/sidebars.js +++ b/sidebars.js @@ -143,7 +143,7 @@ module.exports = { { type: 'doc', id: 'app/agents/DebuggingAgents', - label: 'Troubleshooting Agents & FAQ' + label: 'Agent FAQ and Troubleshooting' }, { type: 'doc',