DOCSEARCHbyAlgolia
Submit Docs

Boxstarter Documentation

repository·develop·Indexed 23 days ago

https://github.com/chocolatey-community/boxstarter

Boxstarter is a tool for creating repeatable, reboot-resilient Windows environment installations using Chocolatey packages. It supports unattended installations, remote deployments via PowerShell Remoting, and integration with virtualization platforms like Hyper-V and Azure. Key features include the Boxstarter.Chocolatey module for packaging, Boxstarter.WinConfig for Windows customization, and automated handling of administrative privileges, UAC, and system reboots.

Tokens
7K
Snippets
5
Records
47
Agent score
77%

What's inside Boxstarter

  1. Boxstarter execution environment and privileges

    develop

    Boxstarter manages the execution environment to ensure scripts run with the necessary permissions and minimal interruption:

    • Administrator Elevation: Boxstarter ensures scripts run as Administrator. If Invoke-Boxstarter is called from a non-elevated shell, it will launch an elevated shell for the remainder of the session.
    • UAC Management: If reboots are enabled and UAC is active, Boxstarter will temporarily disable UAC to allow for an unattended execution experience and re-enable it after the machine reboots and the script restarts.
    • Service Management: To minimize interruptions, Boxstarter stops the Windows Update Service and the System Configuration Client (if installed) during execution. These services are automatically restarted when the script completes.
    • Logging: Boxstarter provides functions to log to the screen, the Boxstarter Log, or both simultaneously. It also captures standard output and error streams from command-line executables.

  2. How AAAPackageDev workflow works

    develop

    AAAPackageDev follows a standard pattern for creating Sublime Text extensions (snippets, completions, build systems, etc.):

    1. Run a new_* command (e.g., new_raw_snippet, new_completions, new_syntax_def) via the Command Palette.
    2. Edit the file using the provided syntax definitions, completions, or snippets.
    3. Save the file.

    Note: Some files, like raw snippets, may require a conversion step (e.g., to .sublime-snippet) using included commands before they can be used by Sublime Text.

  3. How to handle reboots in Boxstarter scripts

    develop

    Boxstarter does not currently have a checkpointing mechanism. When a reboot occurs, Boxstarter simply reruns the entire script from the beginning.

    To write reliable Boxstarter scripts, you must ensure your scripts are idempotent (repeatable). Your script should include logic to check if a task has already been completed before attempting it. For example, check if a software package is already installed before running the installer.

    Key Workflow:

    1. Check if a reboot is pending using Test-PendingReboot.
    2. If a reboot is needed, call Invoke-Reboot.
    3. Ensure all installation logic is wrapped in checks (e.g., if (-not (Test-Path ...))) so that rerunning the script after a reboot is safe.

  4. How Boxstarter handles reboots during installation

    develop

    Boxstarter provides unattended reboot handling to manage complex environment setups (e.g., installing services or patches).

    Reboot Logic:

    • Pre-emptive Check: Boxstarter intercepts Chocolatey install commands and checks for pending reboots before calling Chocolatey. If a reboot is pending, Boxstarter reboots the machine and automatically logs back in with your provided credentials to continue the unattended session.
    • Exit Code 3010: If a Chocolatey package returns the MSI reboot required exit code 3010, Boxstarter will trigger a reboot. This allows the package to succeed on the subsequent run.

    Best Practices for Package Authors:

    • Idempotency: Packages must be repeatable. Because Boxstarter reboots and starts the package from the beginning, the script must be able to run multiple times without breaking.
    • Avoid Dependencies for Reboots: If you need to install multiple packages, call choco install directly inside your ChocolateyInstall.ps1 instead of declaring them as Chocolatey dependencies. Boxstarter cannot intercept Chocolatey dependencies, meaning those sub-packages will not benefit from Boxstarter's reboot protection.

  5. What the Boxstarter variable is and how to use it

    develop
    The Boxstarter variable is a globally accessible hashtable used for persisting Boxstarter settings. Different Boxstarter modules use this hashtable to store various configurations. While many of these settings can be configured directly via switches in the Invoke-Boxstarter command, they can also be modified within the Boxstarter hashtable to control the behavior of the bootstrapper and its modules.

  6. Automatic Logon and Security

    develop

    When reboots are enabled, Boxstarter requires a password to facilitate automatic logon after a restart.

    • Password Collection: When Invoke-Boxstarter is first called, the user is prompted for a password, which is handled as a SecureString.
    • Authentication: Boxstarter uses the current user's domain and username and will attempt to authenticate the password up to three times.
    • Storage: If authentication succeeds, the password is stored in an encrypted area intended for auto-logon.
    • Cleanup: Once the Boxstarter script completes, all logon information is removed from the registry, and subsequent logons will require manual credentials.

  7. Use the Boxstarter variable for global settings

    develop
    The Boxstarter variable is a globally accessible hashtable used to persist Boxstarter settings. Different Boxstarter modules may store different settings within this hashtable. While some settings can be configured via the Invoke-ChocolateyBoxstarter command, the Boxstarter variable serves as the central storage for these configurations.

  8. Develop Syntax Definitions in JSON

    develop

    Syntax definitions in AAAPackageDev are written in JSON. Since Sublime Text requires .tmLanguage files (which use Property Lists), you must convert them.

    Workflow:

    1. Create a new template via Tools | Packages | Package Development or the Command Palette.
    2. Set the build system to JSON to Property List via Tools | Build System (or leave it as Automatic).
    3. Press F7 to trigger the conversion.

  10. Set up Boxstarter TestRunner for Continuous Integration

    develop

    To integrate testing into a build system (TeamCity, Jenkins, TFS, etc.), use the Install-BoxstarterScripts command. This embeds an MSBuild file (Boxstarter.proj), a bootstrapper, and a PowerShell script into your repository.

    Pattern 1: Dedicated Build Server

    Use this if you own and control the build machine. You can pre-install the TestRunner and configure settings (like credentials) once on the machine.

    1. Install the module: choco install Boxstarter.TestRunner.
    2. Configure secrets using Set-BoxstarterDeploymentOptions and Set-BoxstarterFeedAPIKey (these are stored encrypted on the machine).
    3. Configure Azure if using Azure VMs: Run Get-AzurePublishSettingsFile and Import-AzurePublishSettingsFile.
    4. Configure your build step to call Boxstarter.proj.

    Pattern 2: Hosted or Shared Build Server

    Use this for environments like Visual Studio Online where the environment is wiped after each build. You must pass all settings as MSBuild parameters during the build execution.

    MSBuild Parameters for Boxstarter.proj

    When running the MSBuild file, you can pass these parameters:

    • PublishSuccesfulPackages: (bool) Set to true to publish successful packages.
    • DeploymentTargetUserName: Username for target connections.
    • DeploymentTargetPassword: Password for target connections.
    • FeedAPIKey: API key for the NuGet feed.
    • AzureSubscriptionName: Name of the Azure subscription.
    • AzureSubscriptionId: GUID of the Azure subscription.
    • AzureSubscriptionCertificate: Base64 encoded content of the certificate (from the ManagementCertificate attribute in your Azure publish settings file).

  12. Use the Windows Powershell Pipeline in Sublime Text

    develop

    PowershellUtils allows you to filter selected text through a PowerShell pipeline. The plugin takes all currently selected regions in Sublime Text and pipes them sequentially into your command.

    Workflow

    1. Execute the run_powershell command (or your bound key combination).
    2. Type your Windows Powershell command.
    3. Press Enter.

    How it works

    The plugin performs the following operation behind the scenes: reg1..regN | <your command> | out-string

    Each selected region is accessible within your command via the automatic variable $_. The resulting output is then inserted back into each region in turn. You can also ignore the piped content and treat your command as the start of a new pipeline.

    Intrinsic Commands

    Certain commands have special meanings within the plugin:

    • !mkh: Saves the current session's command history to a file.
    • !h: Displays the command history so you can select and re-run a previous command.