Adding Documentation (#19)

* Update to support PowerShell Core & Linux

Signed-off-by: Florian Wagner <[email protected]>

* PowerShell style doc - fixed nslookup in CreateSSL

Signed-off-by: Florian Wagner <[email protected]>

* PowerShell style doc - fixed nslookup in CreateSSL

Signed-off-by: Florian Wagner <[email protected]>

* Documentation Update

Signed-off-by: Florian Wagner <[email protected]>

* Filename corrections and adding links

Signed-off-by: Florian Wagner <[email protected]>

Deploy/CreateSSL.ps1

@@ -35,7 +35,6 @@ param(
     [Parameter(HelpMessage="The domain (CN) name for the SSL certificate")]
     [string] $YOUR_DOMAIN,
 
-
     # $True -> Use Let's Encrypt staging for script testing (Bot cannot be reached from Bot Framework Service) - Default: $False
     [Parameter(HelpMessage="`$True -> Use Let's Encrypt staging for script testing (Bot cannot be reached from Bot Framework Service) - Default: `$False")]
     [bool] $LETS_ENCRYPT_STAGING = $False,
@@ -99,7 +98,6 @@ elseif ($YOUR_DOMAIN -ne $TrafficManager.fqdn) {
         Write-Host "### WARNING, there is no CNAME entry for domain '$YOUR_DOMAIN' pointing to '$($TrafficManager.fqdn)'."
         Write-Host "### Please check your DNS entry, or create the missing CNAME entry. Sleeping for $waitretrysec seconds and try again..."
         Start-Sleep -s $waitretrysec
-
         # Not working in PowerShellCore: $resolved = Resolve-DnsName -Name $YOUR_DOMAIN -DnsOnly 2> $null
         # Changing to nslookup
         $resolved = nslookup $YOUR_DOMAIN 2> $null

Deploy/HelperFunctions.ps1

@@ -41,7 +41,6 @@ function Get-TerraformAutoApproveFlag {
     }
 }
 
-
 function Get-ScriptPath {
     <#
     .SYNOPSIS

Doc/CreateMarkdown-FromPS1.md

@@ -0,0 +1,29 @@
+# CreateMarkdown-FromPS1.ps1
+
+Creates Markdown files from PowerShell Get-Help output
+
+## Description
+
+Creates Markdown files from PowerShell Get-Help output
+
+Helper Tool to create GitHub Markdown files from PS1 scripts. 
+Will check for all PS1 scripts in a given folder and try to create a markdown file.
+If flowcharts are available integrates those into the markdown.
+Since this is a helper script for the repos documentation it has limitations on usage
+
+## Parameters
+
+| Name | Type | Required | Default | Description |
+| - | - | - | - | - |
+| dir | String | true |  | Directory with PS1 scripts |
+| savepath | String | false | . | Markdown file directory |
+
+## Examples
+
+```powershell
+.\CreateMarkdown-FromPS1.ps1 -dir ..\Deploy -savepath .\Deploy
+
+.\CreateMarkdown-FromPS1.ps1 -dir . -savepath .
+
+```
+

Doc/CreateMarkdown-FromPS1.ps1

@@ -0,0 +1,154 @@
+<#
+.SYNOPSIS
+Creates Markdown files from PowerShell Get-Help output
+
+.DESCRIPTION
+Creates Markdown files from PowerShell Get-Help output
+
+Helper Tool to create GitHub Markdown files from PS1 scripts. 
+Will check for all PS1 scripts in a given folder and try to create a markdown file.
+If flowcharts are available integrates those into the markdown.
+Since this is a helper script for the repos documentation it has limitations on usage
+
+.EXAMPLE
+.\CreateMarkdown-FromPS1.ps1 -dir ..\Deploy -savepath .\Deploy
+
+.EXAMPLE
+.\CreateMarkdown-FromPS1.ps1 -dir . -savepath .
+
+.INPUTS
+None. You cannot pipe objects.
+
+.OUTPUTS
+None.
+
+#>
+param(
+    # Directory with PS1 scripts
+    [Parameter(Mandatory=$True,HelpMessage="Directory with PS1 scripts")]
+    [string] $dir,
+
+    # Markdown file directory
+    [Parameter(HelpMessage="Markdown file directory")]
+    [string] $savepath = "."
+)
+
+function Get-ParameterMarkdownTable {
+    param (
+        # Get-Help Object
+        [Parameter(Mandatory=$True,HelpMessage="Get-Help Object")]
+        [object] $help
+    )
+
+    $result = "| Name | Type | Required | Default | Description |`n| - | - | - | - | - |"
+
+    #Write-Host $help
+
+    $help.parameters[0].parameter.foreach({
+        #Write-Host "`nParameter: $_"
+        # try parse default from description
+        $description = $_.description.text
+        $default = ""
+        if(($_.description.text -match "- Default: (.+)$"))
+        {
+            $default = $Matches[1]
+            $description = $_.description.text.replace("- Default: $default", "")
+        }
+        if(($_.defaultValue -ne ""))
+        {
+            $default = $_.defaultValue
+        }
+
+        $result += "`n| $($_.name) | $($_.type.name) | $($_.required) | $($default) | $($description) |"
+    })
+
+    return $result
+}
+
+function Get-Examples {
+    param (
+        # Get-Help Object
+        [Parameter(Mandatory=$True,HelpMessage="Get-Help Object")]
+        [object] $help
+    )
+
+    $result = "``````powershell`n"
+    $help.Examples[0].example.foreach({
+        #Write-Host "`Examples: $($_.code)"
+
+        $result += "$($_.code)`n`n"
+    })
+    $result += "```````n";
+    return $result
+}
+
+function Get-FlowChart {
+    param (
+        # Filename
+        [Parameter(Mandatory=$True,HelpMessage="Filename")]
+        [string] $file
+    )
+
+    $fileparts = $file.Split('.')
+    $flowchartfile = "flowchart/$($fileparts[0]).flowchart"
+    if (Test-Path -Path $flowchartfile)
+    {
+        # render flowchart
+        diagrams flowchart $flowchartfile > $null 
+
+        return "`n`n## Flowchart`n`n<div align='center'>`n`n![Flowchart for $file](../$flowchartfile.svg)`n</div>"
+
+    } else {
+        return ""
+    }
+
+}
+
+function ConvertHelpToMarkdown {
+
+    param (
+        # PS1 file name
+        [Parameter(Mandatory=$True,HelpMessage="PS1 file name")]
+        [object] $file,
+
+        # Markdown file directory
+        [Parameter(HelpMessage="Markdown file directory")]
+        [string] $savepath = "."
+    )
+
+    Write-Host "Processing $($file.name)..."
+    $help = Get-Help -Name "$($file.FullName)" -full
+    #$help
+
+    if ($help.description -ne $null)
+    {
+        # Headline + SYNOPSIS
+        $markdown = "# $($file.name)`n`n$($help.synopsis)"
+
+        # Description
+        $markdown += "`n`n## Description`n`n$($help.description.text)"
+
+        # Parameters
+        $parameters = Get-ParameterMarkdownTable -help $help
+        $markdown += "`n`n## Parameters`n`n$($parameters)"
+
+        # Examples
+        $examples = Get-Examples -help $help
+        $markdown += "`n`n## Examples`n`n$($examples)"
+
+        # flowchart
+        $markdown += Get-FlowChart -file $file.name
+
+        $markdownfile = $file.name.replace("ps1","md")
+        Set-Content -Path "$savepath/$markdownfile" -Value $markdown
+        Write-Host "Created $savepath/$markdownfile..."
+    } else {
+        Write-Host "Skipped $($file.name)..."
+    }
+}
+
+# Load ps1 files in folder
+$FILES = @(Get-ChildItem -Path $dir -File -Recurse) | Where-Object -FilterScript {$_.name.contains(".ps1")}
+# Create Markdown files
+$FILES.ForEach({ConvertHelpToMarkdown -file $_ -savepath $savepath})
+

Doc/Deploy/ActivateSSL.md

@@ -0,0 +1,38 @@
+# ActivateSSL.ps1
+
+Activate Custom Domain Name SSL Certificate and activate TrafficManager Endpoints
+
+## Description
+
+Activate Custom Domain Name SSL Certificate and activate TrafficManager Endpoints
+
+This script will do following steps:
+
+1. Import information from previous Terraform runs
+2. Terraform execution to activate certificate and map TrafficManager endpoints
+3. Update Bot Endpoint
+
+After the script is successfully executed the bot should be in a usable state from WebChat
+
+## Parameters
+
+| Name | Type | Required | Default | Description |
+| - | - | - | - | - |
+| YOUR_DOMAIN | String | false |  | The domain (CN) name for the SSL certificate |
+| AUTOAPPROVE | Boolean | false | False | Terraform and SSL creation Automation Flag. $False -> Interactive, Approval $True -> Automatic Approval |
+| KEYVAULT_CERT_NAME | String | false | SSLcert | KeyVault certificate key name |
+
+## Examples
+
+```powershell
+.\ActivateSSL.ps1 -YOUR_DOMAIN bot.mydomain.com
+
+```
+
+
+## Flowchart
+
+<div align='center'>
+
+![Flowchart for ActivateSSL.ps1](../flowchart/ActivateSSL.flowchart.svg)
+</div>

Doc/Deploy/CheckExistingSSL.md

@@ -0,0 +1,35 @@
+# CheckExistingSSL.ps1
+
+Check if already a SSL certificate was imported to KeyVault
+
+## Description
+
+Check if already a SSL certificate was imported to KeyVault
+
+This script will do following steps:
+
+1. Read values from Terraform IaC run (Bot deployment scripts)
+2. Check if certificate exists in Key Vault
+
+Returns $True if certificate already exists
+
+## Parameters
+
+| Name | Type | Required | Default | Description |
+| - | - | - | - | - |
+| KEYVAULT_CERT_NAME | String | false | SSLcert | KeyVault certificate key name |
+
+## Examples
+
+```powershell
+.\CheckExistingSSL.ps1 -KEYVAULT_CERT_NAME SSLcert
+
+```
+
+
+## Flowchart
+
+<div align='center'>
+
+![Flowchart for CheckExistingSSL.ps1](../flowchart/CheckExistingSSL.flowchart.svg)
+</div>

Doc/Deploy/CreateOrImportSSL.md

@@ -0,0 +1,55 @@
+# CreateOrImportSSL.ps1
+
+Import existing or create/issue new SSL certificate
+
+## Description
+
+Import existing or create/issue new SSL certificate
+
+This script will do following steps:
+
+1. Validate Parameters
+
+2. Deactivate SSL Endpoints (in FORCE mode e.g. changing certificate or changing to custom domain name)
+
+In Import Mode
+  3. Execute Import script
+
+In Issuing Mode
+  3. Execute Issuing script
+
+4. Terraform execution to activate certificate
+
+After the script is successfully executed the Bot should be in a usable from within Bot Framework Service (WebChat) and Bot Emulator
+
+## Parameters
+
+| Name | Type | Required | Default | Description |
+| - | - | - | - | - |
+| YOUR_CERTIFICATE_EMAIL | String | false |  | Mail to be associated with Let's Encrypt certificate |
+| YOUR_DOMAIN | String | false |  | The domain (CN) name for the SSL certificate |
+| LETS_ENCRYPT_STAGING | Boolean | false | False | $True -> Use Let's Encrypt staging for script testing (Bot cannot be reached from Bot Framework Service)  |
+| PFX_FILE_LOCATION | String | false |  | SSL CERT (PFX Format) file location |
+| PFX_FILE_PASSWORD | String | false |  | SSL CERT (PFX Format) file password |
+| KEYVAULT_CERT_NAME | String | false | SSLcert | KeyVault certificate key name |
+| AUTOAPPROVE | Boolean | false | False | Terraform and SSL creation Automation Flag. $False -> Interactive, Approval $True -> Automatic Approval |
+| ALREADYCONFIRMED | Boolean | false | False | Flag to determine if run from within OneClickDeploy.ps1 |
+| FORCE | Boolean | false | False | Force Reimport or Reissuing if certificate already exists |
+| RERUN | Boolean | false | False | To change existing infrastructure, e.g. skips DNS check. $False -> first run/no infrastructure, $True -> subsequent run, existing infrastructure |
+
+## Examples
+
+```powershell
+.\CreateOrImportSSL.ps1 -YOUR_CERTIFICATE_EMAIL [email protected] -YOUR_DOMAIN bot.mydomain.com -LETS_ENCRYPT_STAGING $False -AUTOAPPROVE $True
+
+.\CreateOrImportSSL.ps1 -PFX_FILE_LOCATION ../SSL/mybot.pfx -PFX_FILE_PASSWORD securesecret -AUTOAPPROVE $False
+
+```
+
+
+## Flowchart
+
+<div align='center'>
+
+![Flowchart for CreateOrImportSSL.ps1](../flowchart/CreateOrImportSSL.flowchart.svg)
+</div>

Doc/Deploy/CreateSSL.md

@@ -0,0 +1,43 @@
+# CreateSSL.ps1
+
+Issue new SSL certificate from Let's Encrypt
+
+## Description
+
+Issue new SSL certificate from Let's Encrypt
+
+This script will do following steps:
+
+1. Read values from previous Infrastructure Deployment run (Terraform & Bot Deployment) 
+2. If custom domain is set, check if it points to TrafficManager DNS entry
+3. Terraform execution to spin up container who issues SSL cert and stores in KeyVault
+4. Check if certificate was created
+5. Terraform destroy to clean up resources only need for SSL issuing
+
+After the script is successfully executed the certificate should be stored in KeyVault
+
+## Parameters
+
+| Name | Type | Required | Default | Description |
+| - | - | - | - | - |
+| YOUR_CERTIFICATE_EMAIL | String | true |  | Mail to be associated with Let's Encrypt certificate |
+| YOUR_DOMAIN | String | false |  | The domain (CN) name for the SSL certificate |
+| LETS_ENCRYPT_STAGING | Boolean | false | False | $True -> Use Let's Encrypt staging for script testing (Bot cannot be reached from Bot Framework Service)  |
+| AUTOAPPROVE | Boolean | false | False | Terraform Automation Flag. $False -> Interactive, Approval $True -> Automatic Approval |
+| KEYVAULT_CERT_NAME | String | false | SSLcert | KeyVault certificate key name |
+| MAX_WAIT_TIME_MIN | Int32 | false | 15 | Maximum wait time for DNS resolve and certificate generation in minutes. Default 15 min |
+
+## Examples
+
+```powershell
+.\CreateSSL.ps1 -YOUR_CERTIFICATE_EMAIL [email protected] -YOUR_DOMAIN bot.mydomain.com -LETS_ENCRYPT_STAGING $False -AUTOAPPROVE $True
+
+```
+
+
+## Flowchart
+
+<div align='center'>
+
+![Flowchart for CreateSSL.ps1](../flowchart/CreateSSL.flowchart.svg)
+</div>