diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 0000000..e2c28d7 --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,37 @@ +# Contributing to Vester + +Everyone is welcome to contribute to this project. +The goal is to add fine-grained tests that look at specific values within a vSphere environment, compare them to defined configuration value, and optionally remediate discrepancies if the user so decides. +However, there is nothing wrong with submitting a pull request (PR) with a non-remediating test. +This is a great starting point for those newer to coding with PowerShell! + +## Contribution Requirements + +Every test that is added to Vester needs three things: + +1. An update to the example [`Config.ps1`][config] file with your required configuration value(s), comments, and accepted input type. +2. An update to the [`Config.Tests.ps1`][config.tests] file to validate that the `Config.ps1` file contains valid entries. +3. A test file using a properly formatted `Verb-Noun` format (use `Get-Verb` for more details) placed into the Tests folder. + +## Your First Contribution + +If you're looking for your first bit of code to add, try this list: + +1. Identify a configuration value in your vSphere environment that isn't being inspected by Vester. +2. Use the [Template][template] to create a test that inspects this value and try it out locally. +3. At this point you can submit a pull request (PR) for a non-remediating test. +If someone else wants the remediation code added, they will grab your code and write that portion. +4. Optionally, write the remediation portion yourself to make a fully remediating test. + +## Contribution Process + +1. Create a fork of the project into your own repository. +2. From your fork, create a new feature branch (other than master) that expresses your feature or enhancement. +3. Make all your necessary changes in your feature branch. +4. Create a pull request with a description on what was added or removed and details explaining the changes in lines of code. + +If approved, project owners will merge it. + +[config]: https://github.com/WahlNetwork/Vester/blob/master/Configs/Config.ps1 +[config.tests]: https://github.com/WahlNetwork/Vester/blob/master/Configs/Config.Tests.ps1 +[template]: https://github.com/WahlNetwork/Vester/blob/master/Templates/Update-Template.ps1 \ No newline at end of file diff --git a/.gitignore b/.gitignore index adde6c5..0f2045a 100644 --- a/.gitignore +++ b/.gitignore @@ -44,3 +44,9 @@ Thumbs.db +# Custom Test Config # +###################### +Vester/Configs/config.json + +# Documentation Folders/Files # +############################### +compiled_docs +public +*.pdf \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index 2e7d70d..7c545e1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -67,19 +67,19 @@ I learned that we need to publish releases far more often. :) - VDS-VlanMTU-HealthCheck ### Changed -- #114/#115: `Invoke-Vester` is **more than twice as fast** now! We removed repeated `Get` calls within private file `VesterTemplate.Tests.ps1`. Big thanks to @Midacts/@jpsider/@jonneedham for collaborating on this. -- #118/#119: `Config.json` files now sort their settings within each scope. +- [#114][issue-114] / [#115][issue-115]: `Invoke-Vester` is **more than twice as fast** now! We removed repeated `Get` calls within private file `VesterTemplate.Tests.ps1`. Big thanks to @Midacts/@jpsider/@jonneedham for collaborating on this. +- [#118][issue-118] / [#119][issue-119]: `Config.json` files now sort their settings within each scope. ### Fixed -- #90: `Invoke-Vester -Test $TestList` should execute all tests in the array, instead of just the final one after ignoring the rest. Now they do again. -- #99: Re-implemented `-PassThru` on `Invoke-Vester`. -- #116/#129: The name of the active vCenter connection was not being reported properly. -- #154: Network test VDS-MTUsize had an incorrect parameter. +- [#90][issue-90]: `Invoke-Vester -Test $TestList` should execute all tests in the array, instead of just the final one after ignoring the rest. Now they do again. +- [#99][issue-99]: Re-implemented `-PassThru` on `Invoke-Vester`. +- [#116][issue-116] / [#129][issue-129]: The name of the active vCenter connection was not being reported properly. +- [#154][issue-154]: Network test VDS-MTUsize had an incorrect parameter. - Cleaned up VM test files: - Tools-DiskWiperDisable - Tools-HGFS-ServerDisable -### Much :heart: +### Much ❤ [@jeffgreenca](https://github.com/jeffgreenca) [@haberstrohr](https://github.com/haberstrohr) [@jonneedham](https://github.com/jonneedham) [@Midacts](https://github.com/Midacts) [@jpsider](https://github.com/jpsider) [@Factorization](https://github.com/Factorization) @@ -89,3 +89,13 @@ Initial availability as a PowerShell module ## [1.0.0] - 2016-11-10 [YANKED] Published just to reserve the name on the PowerShell Gallery. If you have this version, please update! + +[issue-90]: https://github.com/WahlNetwork/Vester/issues/90 +[issue-99]: https://github.com/WahlNetwork/Vester/issues/99 +[issue-114]: https://github.com/WahlNetwork/Vester/issues/114 +[issue-115]: https://github.com/WahlNetwork/Vester/issues/115 +[issue-116]: https://github.com/WahlNetwork/Vester/issues/116 +[issue-118]: https://github.com/WahlNetwork/Vester/issues/118 +[issue-119]: https://github.com/WahlNetwork/Vester/issues/119 +[issue-129]: https://github.com/WahlNetwork/Vester/issues/129 +[issue-154]: https://github.com/WahlNetwork/Vester/issues/154 \ No newline at end of file diff --git a/Media/lab-config-example.jpg b/Media/lab-config-example.jpg deleted file mode 100644 index 47724cd..0000000 Binary files a/Media/lab-config-example.jpg and /dev/null differ diff --git a/README.md b/README.md index 630d959..fc3eda3 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,16 @@ -Vester -====================== +# Vester [![Documentation Status](https://readthedocs.org/projects/vester/badge/?version=latest)](http://vester.readthedocs.io/en/latest/?badge=latest) -Vester is a community project that aims to provide an extremely light-weight approach to vSphere configuration management using Pester and PowerCLI. The end-state configuration for each vSphere component, such as clusters and hosts, are abstracted into a simple config file. The configuration is tested--and optionally remediated--when drift is identified. The entire project is written in PowerShell. +Vester is a community project that aims to provide an extremely light-weight approach to vSphere configuration management using Pester and PowerCLI. +The end-state configuration for each vSphere component, such as clusters and hosts, are abstracted into a simple config file. +The configuration is tested -- and, optionally, remediated -- when drift is identified. +The entire project is written in PowerShell. -March 2017: To learn how to use [Vester 1.0](https://www.powershellgallery.com/packages/Vester/1.0.1), there is a [three-part blog series](http://www.brianbunke.com/blog/2017/03/07/introducing-vester/) and accompanying [video demo](https://youtu.be/6DYZR-xFt-4). (Which is really long. You've been warned.) +March 2017: To learn how to use [Vester 1.0](https://www.powershellgallery.com/packages/Vester/1.0.1), there is a [three-part blog series](http://www.brianbunke.com/blog/2017/03/07/introducing-vester/) and accompanying [video demo](https://youtu.be/6DYZR-xFt-4). +(Which is really long. You've been warned.) -> The below documentation link is outdated. We'll remove this comment when we've finished refreshing that info. +> The below documentation link is outdated. +> We'll remove this comment when we've finished refreshing that info. Please visit the **[full documentation](http://vester.readthedocs.io/en/latest/)** for more details. diff --git a/build.ps1 b/build.ps1 new file mode 100644 index 0000000..2733267 --- /dev/null +++ b/build.ps1 @@ -0,0 +1,35 @@ +[cmdletbinding()] +Param ( + [string]$ApiKey, + [string[]]$PowerShellModules = @("Pester","Psake","BuildHelpers","Plaster"), + [string[]]$PackageProviders = @('NuGet','PowerShellGet'), + [string[]]$TaskList +) + +# Install package providers for PowerShell Modules +ForEach ($Provider in $PackageProviders) { + If (!(Get-PackageProvider $Provider -ErrorAction SilentlyContinue)) { + Install-PackageProvider $Provider -Force -ForceBootstrap -Scope CurrentUser + } +} + +# Install the PowerShell Modules +ForEach ($Module in $PowerShellModules) { + If (!(Get-Module -ListAvailable $Module -ErrorAction SilentlyContinue)) { + Install-Module $Module -Scope CurrentUser -Force -Repository PSGallery + } + Import-Module $Module +} + +Push-Location $PSScriptRoot +Write-Output "Retrieving Build Variables" +Get-ChildItem -Path env:\bh* | Remove-Item +Set-BuildEnvironment + +If ($TaskList.Count -gt 0) { + Write-Output "Executing Tasks: $TaskList`r`n" + Invoke-Psake -buildFile .\psake.ps1 -properties $PSBoundParameters -noLogo -taskList $TaskList +} Else { + Write-Output "Executing Unit Tests Only`r`n" + Invoke-Psake -buildFile .\psake.ps1 -properties $PSBoundParameters -nologo +} diff --git a/docs/.bookignore b/docs/.bookignore new file mode 100644 index 0000000..3c3629e --- /dev/null +++ b/docs/.bookignore @@ -0,0 +1 @@ +node_modules diff --git a/docs/BuildDocs.ps1 b/docs/BuildDocs.ps1 deleted file mode 100644 index 221fcdf..0000000 --- a/docs/BuildDocs.ps1 +++ /dev/null @@ -1,27 +0,0 @@ -$verbs = (Get-Command -Module Rubrik | - ForEach-Object -Process { - $_.Name.Split('-')[0] - } | -Select-Object -Unique) - -foreach ($verb in $verbs) -{ - $data = @() - $data += "$verb Commands" - $data += '=========================' - $data += '' - $data += "This page contains details on **$verb** commands." - $data += '' - foreach ($help in (Get-Command -Module Rubrik | Where-Object -FilterScript { - $_.name -match $verb - })) - { - $data += $help.Name - $data += '-------------------------' - $data += '' - $data += Get-Help -Name $help.name -Detailed - $data += '' - } - - $data | Out-File -FilePath "$PSScriptRoot\cmd_$($verb.ToLower()).rst" -Encoding utf8 -} diff --git a/docs/FAQ.md b/docs/FAQ.md new file mode 100644 index 0000000..b0ba9b0 --- /dev/null +++ b/docs/FAQ.md @@ -0,0 +1,6 @@ +# Frequently Asked Questions + +This section will contain a list of questions that have been received (and answered) by the Project Team. + +## 1. Is this project open source? If so, using what license? +This project _is_ open sourced under the [Apache 2.0 license](https://github.com/WahlNetwork/Vester/blob/master/LICENSE). \ No newline at end of file diff --git a/docs/book.json b/docs/book.json new file mode 100644 index 0000000..0788c45 --- /dev/null +++ b/docs/book.json @@ -0,0 +1,7 @@ +{ + "title": "Vester", + "description": "Easily validate and remediate your vSphere configuration", + "author": "Chris Wahl", + "language": "en", + "plugins": ["expandable-chapters-small"] +} diff --git a/docs/concept/readme.md b/docs/concept/readme.md new file mode 100644 index 0000000..68dcc30 --- /dev/null +++ b/docs/concept/readme.md @@ -0,0 +1,8 @@ +# Concept Documentation +The following chapters contain concept guides which explain, in detail, one or more of the following: + ++ Why a design decision was made ++ How an internal component works and why it was used ++ When and when not to use particular features or components ++ What to do when implementing this project in the user's environment ++ Which patterns are best practices and which patterns should be avoided diff --git a/docs/contribution.rst b/docs/contribution.rst deleted file mode 100644 index 5b96ac6..0000000 --- a/docs/contribution.rst +++ /dev/null @@ -1,38 +0,0 @@ -Contribution -======================== - -Everyone is welcome to contribute to this project. The goal is to add fine-grained tests that look at specific values within a vSphere environment, compare them to defined configuration value, and optionally remediate discrepancies if the user so decides. However, there is nothing wrong with submitting a pull request (PR) with a non-remediating test. This is a great starting point for those newer to coding with PowerShell! - -Contribution Requirements ------------------------- - -Every test that is added to Vester needs three things: - -1. An update to the example `Config.ps1`_ file with your required configuration value(s), comments, and accepted input type. -2. An update to the `Config.Tests.ps1`_ file to validate that the `Config.ps1` file contains valid entries. -3. A test file using a properly formatted `Verb-Noun` format (use `Get-Verb` for more details) placed into the Tests folder. - -.. _`Config.ps1`: https://github.com/WahlNetwork/Vester/blob/master/Configs/Config.ps1 -.. _`Config.Tests.ps1`: https://github.com/WahlNetwork/Vester/blob/master/Configs/Config.Tests.ps1 - -Your First Contribution ------------------------- - -If you're looking for your first bit of code to add, try this list: - -1. Identify a configuration value in your vSphere environment that isn't being inspected by Vester. -2. Use the `Template`_ to create a test that inspects this value and try it out locally. -3. At this point you can submit a pull request (PR) for a non-remediating test. If someone else wants the remediation code added, they will grab your code and write that portion. -4. Optionally, write the remediation portion yourself to make a fully remediating test. - -.. _`Template`: https://github.com/WahlNetwork/Vester/blob/master/Templates/Update-Template.ps1 - -Contribution Process ------------------------- - -1. Create a fork of the project into your own repository. -2. From your fork, create a new feature branch (other than master) that expresses your feature or enhancement. -3. Make all your necessary changes in your feature branch. -4. Create a pull request with a description on what was added or removed and details explaining the changes in lines of code. - -If approved, project owners will merge it. diff --git a/docs/faq.rst b/docs/faq.rst deleted file mode 100644 index fa22acb..0000000 --- a/docs/faq.rst +++ /dev/null @@ -1,4 +0,0 @@ -Frequently Asked Questions -======================== - -This section will contain a list of questions that have been received (and answered) by the Project Team. diff --git a/docs/getting_started.rst b/docs/getting_started.rst deleted file mode 100644 index ce1c112..0000000 --- a/docs/getting_started.rst +++ /dev/null @@ -1,102 +0,0 @@ -Getting Started -======================== - -This project ultimately uses Pester to provide the testing framework. Because of this, we leverage a combination of Pester variables and custom ones written for Vester. If you're wondering why the command structure looks a bit complex, reference `Pester Issue 271`_ and `Pester Issue 423`_. - -.. _Pester Issue 271: https://github.com/pester/Pester/issues/271 -.. _Pester Issue 271: https://github.com/pester/Pester/issues/423 - -Path Variable ------------------------- - -Type: String - -* Used to tell ``Invoke-Pester`` the relative path to where you have downloaded the Vester tests. -* Some folks like to use different versions of tests, or subdivide tests into smaller groups. -* The ``path`` input is required by Pester when sending parameters as shown in the examples below. - -Default: - None hard-coded. Your current location when calling ``Invoke-Pester``, or the relative/absolute path you provide - -Remediate Variable ------------------------- - -Type: Bool (boolean) - -* Tells Vester in which mode to operate. -* Set to ``$false`` to report on differences without any remediation. -* Set to ``$true`` to report on differences while also trying to remediate them. - -Default: - ``$false`` - -Config Variable ------------------------- - -Type: String - -* The relative path to where you have located a Vester config file. -* You can use multiple config files to represent your different environments, such as Prod and Dev, while at the same time using the same testing files. - -Default: - ``Vester\Configs\Config.ps1`` - -Usage Instructions -------------------------- - -The end-state configuration for each vSphere component is stored inside of the ``Config.ps1`` file. Make sure to read through the configuration items and set them with your specific environmental variables for DRS, NTP, SSH, etc. - -If you have multiple environments that have unique settings, create a copy of the ``Config.ps1`` file for each environment and call it whatever you wish (such as ``Config-Prod.ps1`` for Production and ``Config-Dev.ps1`` for your Dev). - -Once that's complete, you can start running Pester tests by opening your PowerShell console, using ``Connect-VIServer`` to authenticate to your vCenter Server, and finally using the parameters and examples below. - -.. image:: http://i.imgur.com/qXrGlar.png - :target: https://www.youtube.com/watch?v=CyVfzZ4jA8Q - -Example 1 - Validation using Defaults ---------------------------- - -``Invoke-Pester .\Vester`` - -* Runs all tests underneath directory ``.\Vester`` -* Will validate that the default config file has proper values first, then run all tests -* Uses the default remediation value of ``$false`` (disabled) - drift will be shown but not corrected -* Uses the default configuration settings found in ``.\Vester\Configs\Config.ps1`` - -Example 2 - Validation using Different Config Values ---------------------------- - -``Invoke-Pester -Script @{Path = '.\Vester'; Parameters = @{ Config = '.\Vester\Configs\Config-Prod.ps1' }}`` - -* Runs all tests underneath directory ``.\Vester``. Path is mandatory if supplying a parameter -* Will validate config and then run all tests -* Configuration settings found in ``.\Vester\Configs\Config-Prod.ps1`` will be used -* By not supplying the Remediate parameter, it defaults to ``$false`` - -Example 3 - Remediation using Different Config Values ---------------------------- - -``Invoke-Pester -Script @{Path = '.\Vester\Tests'; Parameters = @{ Remediate = $true ; Config = '.\Vester\Configs\Config-Prod.ps1' }}`` - -* Runs all tests found in the path ``.\Vester\Tests`` -* Remediation is ``$true`` (enabled) - drift will be shown and also corrected -* Configuration settings found in ``.\Vester\Configs\Config-Prod.ps1`` will be used - -Example 4 - Single Test Validation and NUnit Output (for Jenkins, AppVeyor, etc.) ---------------------------- - -``Invoke-Pester .\Vester\Tests -TestName '*DNS*' -OutputFormat NUnitXml -OutputFile .\Vester\results.xml`` - -* Runs any test under the path ``.\Vester\Tests`` with the string "DNS" found in the name -* NUnitXml output will be created in the file ``.\Vester\results.xml`` -* Because there are no hashtables ``@{}``, defaults for Config/Remediate would be used -* Can easily be combined with Examples 2-3 to use a different config file and/or remediate - -Example 5 - Validation using Tags ---------------------------- - -``Invoke-Pester .\Vester\Tests -Tag host -ExcludeTag nfs`` - -* At the path ``.\Vester\Tests``, runs all tests with the "host" tag, except for those also tagged "nfs" -* Because there are no hashtables ``@{}``, defaults for Config/Remediate would be used -* Can easily be combined with Examples 2-3 to use a different config file and/or remediate \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index 70b9e42..0000000 --- a/docs/index.rst +++ /dev/null @@ -1,45 +0,0 @@ -Vester - Configuration Management for vSphere -======================== - -.. image:: http://readthedocs.org/projects/vester/badge/?version=latest - :target: http://vester.readthedocs.io/en/latest/?badge=latest - -Vester is a community project that aims to provide an extremely light-weight approach to vSphere configuration management using Pester and PowerCLI. The end-state configuration for each vSphere component, such as clusters and hosts, are abstracted into a simple config file. The configuration is tested and optionally remediated when drift is identified. The entire project is written in PowerShell. The code is open source, and `available on GitHub`_. - -.. _available on GitHub: https://github.com/WahlNetwork/Vester - -.. toctree:: - :maxdepth: 2 - :hidden: - :caption: User Documentation - - requirements - installation - getting_started - support - contribution - licensing - faq - -.. toctree:: - :maxdepth: 2 - :hidden: - :caption: Command Documentation - - cmd_connect - cmd_get - cmd_new - cmd_protect - cmd_remove - cmd_set - cmd_start - cmd_stop - cmd_sync - -.. toctree:: - :maxdepth: 2 - :hidden: - :caption: Workflow Examples - - flow_audit - flow_backup_validation diff --git a/docs/installation.rst b/docs/installation.rst deleted file mode 100644 index 1c9a240..0000000 --- a/docs/installation.rst +++ /dev/null @@ -1,4 +0,0 @@ -Installation -======================== - -Because this repository is simply a collection of Pester tests, there is no installation. Download the files contained within this project anywhere you want. diff --git a/docs/licensing.rst b/docs/licensing.rst deleted file mode 100644 index 446635b..0000000 --- a/docs/licensing.rst +++ /dev/null @@ -1,6 +0,0 @@ -Licensing -======================== - -Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. \ No newline at end of file diff --git a/docs/narrative/readme.md b/docs/narrative/readme.md new file mode 100644 index 0000000..b1322a5 --- /dev/null +++ b/docs/narrative/readme.md @@ -0,0 +1,7 @@ +# Narrative Documentation +The following chapters attempt to communicate how and why to perform actions in the context of this project. +These narratives are intended to help you be successful when using this project and to show you best practices while also showing you example use cases. + +These documents are as important to us as the code this project relies on; if you find any errors or issues, please let us know. + +If any code you find in any of these documents causes you to run into errors (and there's no note in the document about dealing with that error), we consider this a **critical bug**. diff --git a/docs/reference/readme.md b/docs/reference/readme.md new file mode 100644 index 0000000..6cf3ecf --- /dev/null +++ b/docs/reference/readme.md @@ -0,0 +1,6 @@ +# Reference Documentation +Documentation in this section can best be understood as: + +> Information about the exact usage and functionality of this project which explains precisely how to work within the project and elaborates on the parameters, types, and technical interfaces of the project. + +The documentation you find in the following chapters is intended to be reviewed when using the project. diff --git a/docs/reference/tests/readme.md b/docs/reference/tests/readme.md new file mode 100644 index 0000000..5c5a7c6 --- /dev/null +++ b/docs/reference/tests/readme.md @@ -0,0 +1,3 @@ +# Vester Tests +The following chapters capture the information of the available Vester tests by type. +These documents are auto-generated from the tests on build. \ No newline at end of file diff --git a/docs/requirements.rst b/docs/requirements.rst deleted file mode 100644 index 40ea1a3..0000000 --- a/docs/requirements.rst +++ /dev/null @@ -1,15 +0,0 @@ -Requirements -======================== - -The code assumes that you've already deployed at least one Rubrik Brik into your environment and have completed the initial configuration process to form a cluster. At a minimum, make sure you have installed the following: - -1. PowerShell version 4+ -2. `PowerCLI`_ version 6.0+ -3. `Pester`_ -4. (optional) `Windows Management Framework 5.0`_ - -Note: Although an alpha build of PowerShell exists for Linux and Mac OS environments, the code is currently being written and validated using a Microsoft Windows Server environment. - -.. _PowerCLI: http://www.vmware.com/go/powercli -.. _Windows Management Framework 5.0: https://www.microsoft.com/en-us/download/details.aspx?id=50395 -.. _Pester: https://github.com/pester/Pester diff --git a/docs/support.rst b/docs/support.md similarity index 52% rename from docs/support.rst rename to docs/support.md index fcfd719..c89a6c6 100644 --- a/docs/support.rst +++ b/docs/support.md @@ -1,8 +1,7 @@ -Support -======================== +# Support The community module is not officially supported and should be **used at your own risk**. -To report a bug, request an enhancement, or provide feedback about this project, please `open an issue`_. +To report a bug, request an enhancement, or provide feedback about this project, please [open an issue][new-issue]. -.. _open an issue: https://github.com/WahlNetwork/Vester/issues +[new-issue]: https://github.com/WahlNetwork/Vester/issues \ No newline at end of file diff --git a/psake.ps1 b/psake.ps1 new file mode 100644 index 0000000..24f518a --- /dev/null +++ b/psake.ps1 @@ -0,0 +1,135 @@ +# PSake makes variables declared here available in other scriptblocks +# Init some things +Properties { + $ProjectRoot = $env:BHProjectPath + $ChocolateyPackages = @('nodejs','calibre') + $NodeModules = @('gitbook-cli','gitbook-summary') + $Timestamp = Get-date -uformat "%Y%m%d-%H%M%S" + $ApiKey = $env:APIKEY + $CompilingFolder = "$env:BHProjectPath/compiled_docs" + $OutputPdfPath = "$ProjectRoot/$env:BHProjectName.pdf" + $OutputSitePath = "$ProjectRoot/public" +} + +Task Default -Depends InstallPrerequisites + +Task InstallChocolatey { + # Install Chocolatey + If (!(Get-Command choco -ErrorAction SilentlyContinue)) { + # Check to see if admin; if not, this will fail! + If (!([Security.Principal.WindowsPrincipal] [Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole]"Administrator")) { + Write-Error "Chocolatey is not installed; Administrator permissions are required to install chocolatey`r`nPlease elevate your permissions and try again." + } Else { + Invoke-Expression ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1')) + } + } +} + +Task InstallChocolateyPackages -depends InstallChocolatey { + # Install needed chocolatey packages + ForEach ($Package in $ChocolateyPackages) { + If (!(choco list --local-only | Where-Object {$_ -Match "^${Package}\s"})) { + If (!([Security.Principal.WindowsPrincipal] [Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole]"Administrator")) { + Write-Error "Administrator permissions are required to install chocolatey packages`r`nPlease elevate your permissions and try again." + } Else { + choco install $Package -y + } + } + } + # Update the Path Variables + Import-Module C:\ProgramData\chocolatey\helpers\chocolateyProfile.psm1 + Update-SessionEnvironment +} + +Task InstallNodePackages -depends InstallChocolateyPackages { + If (Get-Command npm -ErrorAction SilentlyContinue) { + $GloballyInstalledModules = (npm ls --global --json | convertfrom-json).Dependencies + ForEach ($Module in $NodeModules) { + If ([string]::IsNullOrEmpty($GloballyInstalledModules."$Module")) { + npm install -g $module + } + } + } Else {Write-Warning "NPM not found; node modules not installed!"} +} + +Task InstallPrerequisites -depends InstallNodePackages + +Task Clean { + If (Test-Path $CompilingFolder) { + Remove-Item $CompilingFolder -Recurse -Force + } + If (Test-Path $OutputSitePath) { + Remove-Item $OutputSitePath -Recurse -Force + } + If (Test-Path $OutputPdfPath) { + Remove-Item $OutputPdfPath + } +} + +Task Compile -depends Clean { + Write-Host -ForegroundColor DarkMagenta "Scaffolding the compiling folder..." + $null = mkdir $CompilingFolder + + Write-Host -ForegroundColor DarkMagenta "Copying metadocuments..." + Copy-Item -Path $ProjectRoot/*.md -Destination $CompilingFolder -Force + + Write-Host -ForegroundColor DarkMagenta "Copying documents..." + Copy-Item -Path $ProjectRoot/docs/* -Destination $CompilingFolder -Recurse -Force + + Write-Host -ForegroundColor DarkMagenta "Generating function reference documents..." + Import-Module PlatyPS + $Module = Import-Module $ProjectRoot/vester/vester.psd1 -PassThru + $null = New-MarkdownHelp -Module $env:BHProjectName -OutputFolder $CompilingFolder/reference/functions + $FunctionReferenceReadmePath = "$CompilingFolder/reference/functions/readme.md " + $FunctionReferenceReadmeValue = @( + "---" + "Module Name: $($Module.Name)" + "Module Guid: $($Module.Guid)" + "Help Version: $($Module.Version)" + "Locale: en-US" + "---" + "# Function Reference" + "The following chapters provide the online help for the public functions of the $env:BHProjectName module" + "$(Get-Command -Module $env:BHProjectName | ForEach-Object { + $Info = Get-Help $PSItem + "# [``$($Info.Name)``]($($Info.Name).md)`r`n$($Info.Synopsis)`r`n" + })" + ) + $null = New-Item -Path $FunctionReferenceReadmePath -Value ($FunctionReferenceReadmeValue -join("`r`n")) + Write-Host -ForegroundColor DarkMagenta "Generating test reference documents..." + ForEach ($Test in (Get-ChildItem -Path $ProjectRoot/Vester/Tests -Recurse -File)) { + [string]$Category = $(Split-Path -Path (Split-Path -Path $Test.FullName -Parent) -Leaf) + . $Test.FullName + $DocumentPath = "$CompilingFolder/reference/tests/$Category/$($Title.replace(' ','-').replace(':','')).md" + If (!(Test-Path -Path (Split-Path $DocumentPath -Parent))) { + $null = New-Item -Path "$(Split-Path $DocumentPath -Parent)/readme.md" -Value "# $Category Tests`r`nSee the following chapters for more information." -Force + } + If (!(Test-Path -Path $DocumentPath)) { + $null = New-Item -Path $DocumentPath -Value "# $Title`r`n$Description" -Force + } + @( + "`r`n## Discovery Code`r`n" + '```powershell' + "$Actual" + '```' + "`r`n## Remediation Code`r`n" + '```powershell' + "$Fix" + '```' + ) | Add-Content -Path $DocumentPath + } + Push-Location -Path $CompilingFolder + Write-Host -ForegroundColor DarkMagenta "Generating summary file..." + book sm + Write-Host -ForegroundColor DarkMagenta "Installing gitbook plugins..." + gitbook install + Pop-Location +} + +Task GenerateSite -depends Compile { + gitbook build $CompilingFolder $OutputSitePath +} + +Task GeneratePdf -depends Compile { + gitbook pdf $CompilingFolder $OutputPdfPath +} + +Task LivePreview -depends Compile { + Push-Location -Path $CompilingFolder + gitbook serve + Pop-Location +} \ No newline at end of file