From 152ff2d1bdc27936e58737bdc89252b05148d6d4 Mon Sep 17 00:00:00 2001 From: Richard Waal Date: Tue, 13 Apr 2021 21:01:56 +0200 Subject: [PATCH 01/10] add instructions for win & macos Instructions have been added for MacOs. To keep the README.md file uncluttered, I've moved the prerequisites installation to a separate markdown file. --- README.md | 43 +------------------------------ docs/prerequisites.md | 60 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 61 insertions(+), 42 deletions(-) create mode 100644 docs/prerequisites.md diff --git a/README.md b/README.md index 65d25f2..b23cb78 100644 --- a/README.md +++ b/README.md @@ -143,54 +143,13 @@ Azure Subscription with: ## Local development -If you want to further develop or test AIPAS you need to install the following prerequisites on your Windows development machine. - -### Install local development prerequisites - -- Git client -- Visual Studio Code -- Azure Function Core Tools (version 3.0.3160 or higher) -- PowerShell (Core) -- HTTP Testing and Debugging tool like [Httpmaster](https://www.httpmaster.net/) of [Insomnia](https://insomnia.rest/) - -If you installed [Chocolatey](https://chocolatey.org/) (a Windows Apt-Get kinda tool) you can install above software with the following commands: - -```PowerShell -# Install Git -choco install git -# Install VSCode -choco install vscode -# Install Azure Function Core Tools -choco install azure-functions-core-tools-3 -# Install PowerShell Core -choco install pwsh -# Install HttpMaster -choco install httpmaster-express -``` +AIPAS uses Azure Functions. You can develop, test and run Azure functions locally on your machine. Please see the [instructions](docs/prerequisites.md) for installing the prerequisites on Windows and MacOs. ### Clone AIPAS Repository ```PowerShell git clone https://github.com/stefanstranger/AIPAS.git ``` - -### Install PowerShell Modules - -After cloning the Git Repository you can use the bootstrap.ps1 script to install the required PowerShell modules. - -![Bootstrap screenshot](pictures/bootstrap.png) - -The following PowerShell Modules need to be installed: - -- InvokeBuild -- Pester -- PlatyPS -- Az PowerShell modules* - -\* The installation of the Az PowerShell modules are not part of the bootstrap.ps1 script. If you have not installed these PowerShell modules run Install-Module -Name Az on your development machine. - - - ### Deploy Azure Storage Table Within the Git Repository there are Azure Resource Manager Template files that can be used to deploy a new Resource Group with an Azure Storage Table. diff --git a/docs/prerequisites.md b/docs/prerequisites.md new file mode 100644 index 0000000..8e233fd --- /dev/null +++ b/docs/prerequisites.md @@ -0,0 +1,60 @@ +# Installing prerequisites + +The following things are required on your system. + +- git +- VS Code +- Azure Function Core Tools (version 3.0.3160 or higher) +- PowerShell 7 +- HTTP Testing and Debugging tool like [Postman](https://www.postman.com/), [Httpmaster](https://www.httpmaster.net/) or [Insomnia](https://insomnia.rest/) + + +## Windows + +The prerequisites on Windows can be installed using [Chocolatey](https://chocolatey.org/) (a package manager for Windows). + +``` +# Install Git +choco install git +# Install VSCode +choco install vscode +# Install Azure Function Core Tools +choco install azure-functions-core-tools-3 +# Install PowerShell Core +choco install pwsh +# Install HttpMaster +choco install postman +``` + +## MacOs +The prerequisites on MacOs can be installed using [brew](https://brew.sh/) (a package manager for Mac). + +``` +# Install Git +brew install git +# Install VSCode +brew install --cask visual-studio-code +# Install dotnet +brew tap caskroom/caskbrew cask install dotnet +# Install Azure Function Core Tools +brew install azure-functions-core-tools@3 +# Install PowerShell 7 +brew install --cask powershell +# Install Postman +brew install --cask postman +``` + +## Install PowerShell Modules + +After cloning the Git Repository you can use the bootstrap.ps1 script to install the required PowerShell modules. + +![Bootstrap screenshot](/pictures/bootstrap.png) + +The following PowerShell Modules need to be installed: + +- InvokeBuild +- Pester +- PlatyPS +- Az PowerShell modules* + +\* The installation of the Az PowerShell modules are not part of the bootstrap.ps1 script. If you have not installed these PowerShell modules run `Install-Module -Name Az`on your development machine. From 996f1977020a2fbf36180afe9c37834e9e475bb2 Mon Sep 17 00:00:00 2001 From: Richard Waal Date: Tue, 13 Apr 2021 21:18:31 +0200 Subject: [PATCH 02/10] remove out-gridview not being cross platform Removing Out-GridView as it's not cross platform. This change allows the code to work on all PowerShell 7 compatible platforms. --- README.md | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index b23cb78..8b8739b 100644 --- a/README.md +++ b/README.md @@ -161,17 +161,12 @@ Run the following PowerShell Azure commands: Run from within your cloned repo folder #> +$subscription = '' + #region Login to Azure Add-AzAccount #endregion -#region Select Azure Subscription -$subscription = -(Get-AzSubscription | - Out-GridView ` - -Title 'Select an Azure Subscription ...' ` - -PassThru) - Set-AzContext -SubscriptionId $subscription.subscriptionId -TenantId $subscription.TenantID #endregion From eeb68c4bbcd567bbe3ffcc82165cc3870a8919fb Mon Sep 17 00:00:00 2001 From: Richard Waal Date: Tue, 13 Apr 2021 21:23:02 +0200 Subject: [PATCH 03/10] remove tentant --- README.md | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 8b8739b..8d1f028 100644 --- a/README.md +++ b/README.md @@ -167,7 +167,7 @@ $subscription = '' Add-AzAccount #endregion -Set-AzContext -SubscriptionId $subscription.subscriptionId -TenantId $subscription.TenantID +Set-AzContext -SubscriptionId $subscription.subscriptionId #endregion #region Create a new Resource Group @@ -211,19 +211,13 @@ $RoleDefinitionName = "Storage Account Contributor" $ADApplicationName = "AIPAS" $PlainPassword = "[enter password for SPN]" $StorageAccountName = "[Configure here the name of the previously deployed Storage Account]" -$SubscriptionId = "[enter subscriptionid]"" #SubscriptionId where the Vnets will be deployed. E.g. the Landing Zone Subscription. If multiple Subscriptions are used rerun for each Subscription +$SubscriptionId = "[enter subscriptionid]" #SubscriptionId where the Vnets will be deployed. E.g. the Landing Zone Subscription. If multiple Subscriptions are used rerun for each Subscription #region Login to Azure Add-AzAccount #endregion #region Select Azure Subscription -$subscription = -(Get-AzSubscription | - Out-GridView ` - -Title 'Select an Azure Subscription ...' ` - -PassThru) - Set-AzContext -SubscriptionId $subscription.subscriptionId -TenantId $subscription.TenantID #endregion From 37d3c9ae2fd5a82253078f4e990342f9136bae9b Mon Sep 17 00:00:00 2001 From: Richard Waal Date: Tue, 13 Apr 2021 21:38:22 +0200 Subject: [PATCH 04/10] change subscriptionId Context will be set using the variable $SubscriptionId, in which user manually entered the subscription Id. Necessary because the Out-Gridview was removed in a previous commit. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 8d1f028..c2ce8b9 100644 --- a/README.md +++ b/README.md @@ -218,7 +218,7 @@ Add-AzAccount #endregion #region Select Azure Subscription -Set-AzContext -SubscriptionId $subscription.subscriptionId -TenantId $subscription.TenantID +Set-AzContext -SubscriptionId $SubscriptionId #endregion #region create SPN with Password From cb91ebb1ac7816449ac64689af72435a4473a4c9 Mon Sep 17 00:00:00 2001 From: Richard Waal Date: Tue, 13 Apr 2021 21:53:44 +0200 Subject: [PATCH 05/10] change env vars to local.settings.json Setting the environment variables in the original script doesn't work on MacOs. Instead, a local.settings.json file is used. It provides the same capabilities; storing app settings that the local core tools will use. --- .vscode/local.settings.json | 14 ++++++++++++++ README.md | 27 +++++++++++++++++++-------- 2 files changed, 33 insertions(+), 8 deletions(-) create mode 100644 .vscode/local.settings.json diff --git a/.vscode/local.settings.json b/.vscode/local.settings.json new file mode 100644 index 0000000..73d323e --- /dev/null +++ b/.vscode/local.settings.json @@ -0,0 +1,14 @@ +{ + "IsEncrypted": false, + "Values": { + "AzureWebJobsStorage": "UseDevelopmentStorage=true", + "FUNCTIONS_WORKER_RUNTIME_VERSION": "~7", + "FUNCTIONS_WORKER_RUNTIME": "powershell", + "AIPASStorageAccountName": "rwaalsa2020", + "AIPASTenantId": "9f7931d9-b0a4-4080-9dd3-e58cf077d7ca", + "AIPASSubscriptionId": "0f4c38a7-812e-44cc-b93b-924363020f9c", + "AIPASResourceGroupName": "AIPAS-rg", + "AIPASClientId": "4ab61761-bd60-4b15-ae7d-c7a7ad74e9e3", + "AIPASClientSecret": "L0udn3ss2021!!" + } +} diff --git a/README.md b/README.md index c2ce8b9..508ecf4 100644 --- a/README.md +++ b/README.md @@ -242,14 +242,25 @@ Get-AzADServicePrincipal -ServicePrincipalName $($app.ApplicationId.Guid) -OutVa } | Convertto-json #endregion -#region create local environment variables -[Environment]::SetEnvironmentVariable("AIPASClientId", "$($app.ApplicationId)", "User") -[Environment]::SetEnvironmentVariable("AIPASClientSecret", "$PlainPassword", "User") -[Environment]::SetEnvironmentVariable("AIPASSubscriptionId", "$($subscription.subscriptionId)", "User") -[Environment]::SetEnvironmentVariable("AIPAStenantId", "$($subscription.TenantID)", "User") -[Environment]::SetEnvironmentVariable("AIPASResourceGroupName", $ResourceGroupName, "User") -[Environment]::SetEnvironmentVariable("AIPASStorageAccountName", $StorageAccountName, "User") -# Restart VSCode to have access to the environment variables +#region create local settings file +$json = @" +{ + "IsEncrypted": false, + "Values": { + "AzureWebJobsStorage": "UseDevelopmentStorage=true", + "FUNCTIONS_WORKER_RUNTIME_VERSION": "~7", + "FUNCTIONS_WORKER_RUNTIME": "powershell", + "AIPASStorageAccountName": "$StorageAccountName", + "AIPASTenantId": "$((Get-AzContext).Tenant.Id)", + "AIPASSubscriptionId": "$SubscriptionId", + "AIPASResourceGroupName": "$ResourceGroupName", + "AIPASClientId": "$($app.ApplicationId)", + "AIPASClientSecret": "$PlainPassword" + } +} +"@ +$json | Out-File -Path .vscode\local.settings.json +# Restart VSCode to load the local settings #endregion ``` From 12aa57e7ada20fbf7241b2bcadfb68a3867b4067 Mon Sep 17 00:00:00 2001 From: Richard Waal Date: Tue, 13 Apr 2021 22:01:02 +0200 Subject: [PATCH 06/10] add macos support to tasks The original tasks do not run on macos. These additions are automatically used on macos systems and will run the alternative command. --- .vscode/tasks.json | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/.vscode/tasks.json b/.vscode/tasks.json index 38d0e88..b68336d 100644 --- a/.vscode/tasks.json +++ b/.vscode/tasks.json @@ -7,6 +7,9 @@ "label": "CopyModuleFiles", "type": "shell", "command": "Invoke-Build -Task CopyModuleFiles -File './aipas.build.ps1'", + "osx": { + "command": "pwsh -c Invoke-Build -Task CopyModuleFiles -File './aipas.build.ps1'" + }, "problemMatcher": "$msCompile", "presentation": { "echo": false, @@ -17,6 +20,9 @@ "label": "Test", "type": "shell", "command": "Invoke-Build -Task Test -File './aipas.build.ps1'", + "osx": { + "command": "pwsh -c Invoke-Build -Task Test -File './aipas.build.ps1'" + }, "problemMatcher": "$msCompile", "presentation": { "echo": false, @@ -27,6 +33,9 @@ "label": "Startfunction", "type": "shell", "command": "Invoke-Build -Task Startfunction -File './aipas.build.ps1'", + "osx": { + "command": "pwsh -c Invoke-Build -Task Startfunction -File './aipas.build.ps1'" + }, "problemMatcher": "$msCompile", "presentation": { "echo": false, @@ -37,6 +46,9 @@ "label": "Clean", "type": "shell", "command": "Invoke-Build -Task Clean -File './aipas.build.ps1'", + "osx": { + "command": "pwsh -c Invoke-Build -Task Clean -File './aipas.build.ps1'" + }, "problemMatcher": "$msCompile", "presentation": { "echo": false, @@ -47,6 +59,9 @@ "label": "Testfunction", "type": "shell", "command": "Invoke-Build -Task TestFunction -File './aipas.build.ps1'", + "osx": { + "command": "pwsh -c Invoke-Build -Task TestFunction -File './aipas.build.ps1'" + }, "problemMatcher": "$msCompile", "presentation": { "echo": false, @@ -57,6 +72,9 @@ "label": ".", "type": "shell", "command": "Invoke-Build -Task . -File './aipas.build.ps1'", + "osx": { + "command": "pwsh -c Invoke-Build -Task . -File './aipas.build.ps1'" + }, "problemMatcher": "$msCompile", "presentation": { "echo": false, @@ -71,6 +89,9 @@ "label": "?", "type": "shell", "command": "Invoke-Build -Task ? -File './aipas.build.ps1'", + "osx": { + "command": "pwsh -c Invoke-Build -Task ? -File './aipas.build.ps1'" + }, "problemMatcher": "$msCompile", "presentation": { "echo": false, From d434c2807020c6f25313bad32346c0fcfa934391 Mon Sep 17 00:00:00 2001 From: Richard Waal Date: Tue, 13 Apr 2021 22:06:35 +0200 Subject: [PATCH 07/10] fix typo --- docs/prerequisites.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/prerequisites.md b/docs/prerequisites.md index 8e233fd..f19cd50 100644 --- a/docs/prerequisites.md +++ b/docs/prerequisites.md @@ -23,7 +23,7 @@ choco install azure-functions-core-tools-3 # Install PowerShell Core choco install pwsh # Install HttpMaster -choco install postman +choco install httpmaster-express ``` ## MacOs From 036fcd48b981ae7678b3ea25e1abd6fd0daf1cae Mon Sep 17 00:00:00 2001 From: Richard Waal Date: Tue, 13 Apr 2021 22:07:53 +0200 Subject: [PATCH 08/10] Add comment about postmaster --- docs/prerequisites.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/prerequisites.md b/docs/prerequisites.md index f19cd50..a17db96 100644 --- a/docs/prerequisites.md +++ b/docs/prerequisites.md @@ -40,7 +40,7 @@ brew tap caskroom/caskbrew cask install dotnet brew install azure-functions-core-tools@3 # Install PowerShell 7 brew install --cask powershell -# Install Postman +# Install Postman (alternative to httpmaster, which is only available for Windows) brew install --cask postman ``` From 312676ac665a0872e6b57e37702add662f6f9ef2 Mon Sep 17 00:00:00 2001 From: Richard Waal Date: Tue, 13 Apr 2021 22:20:32 +0200 Subject: [PATCH 09/10] add local.settings.json to gitignore Local settings should be committed to source control. Especially because there will probably be secrets inside of these files. --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index 37d0f1e..41c9b08 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,4 @@ __blobstorage* __azurite* __queuestorage* debug.ps1 +local.settings.json From 38d80fa328d1d93c1609fb4b940f73d254fa86c5 Mon Sep 17 00:00:00 2001 From: Richard Waal Date: Tue, 13 Apr 2021 23:49:56 +0200 Subject: [PATCH 10/10] deleting unwanted local.settings.json This was placed before the local.settings.json was in .gitignore and should not have been committed. And for those interested, the SPN is long gone and cannot be used ;-) --- .vscode/local.settings.json | 14 -------------- 1 file changed, 14 deletions(-) delete mode 100644 .vscode/local.settings.json diff --git a/.vscode/local.settings.json b/.vscode/local.settings.json deleted file mode 100644 index 73d323e..0000000 --- a/.vscode/local.settings.json +++ /dev/null @@ -1,14 +0,0 @@ -{ - "IsEncrypted": false, - "Values": { - "AzureWebJobsStorage": "UseDevelopmentStorage=true", - "FUNCTIONS_WORKER_RUNTIME_VERSION": "~7", - "FUNCTIONS_WORKER_RUNTIME": "powershell", - "AIPASStorageAccountName": "rwaalsa2020", - "AIPASTenantId": "9f7931d9-b0a4-4080-9dd3-e58cf077d7ca", - "AIPASSubscriptionId": "0f4c38a7-812e-44cc-b93b-924363020f9c", - "AIPASResourceGroupName": "AIPAS-rg", - "AIPASClientId": "4ab61761-bd60-4b15-ae7d-c7a7ad74e9e3", - "AIPASClientSecret": "L0udn3ss2021!!" - } -}