Winbox Cookbook

The Winbox cookbook configures Windows workstations for developers. It configures Git, ChefDK, a text editor, and other tools so you can start using it for Chef, Ruby, and other development tasks.

Installation

Copy the following command and paste it into an administrative PowerShell session and run it to install Winbox and all its prerequisites:

powershell.exe -noprofile -executionpolicy unrestricted { . { iwr -UseBasicParsing https://raw.githubusercontent.com/adamedx/winbox/0.1.79/files/default/install.ps1 } | iex;install-workstation }

See additonal instructions for customization and advanced usage and non-default features.

Features and usage

The Winbox cookbook configures the following features on a system:

• Git for source control
• A text editor (configurable, VSCode by default)
• ConEmu terminal replacement
• Chocolatey package manager
• PSGet PowerShell module package manager
• PSReadline module for PowerShell
• Other environmental settings optimized for development

Who should use this cookbook?

Everyone using Windows should use Winbox! It's for developers and operators regardless of platform background:

• Windows users: You live and breathe Windows. If you're a developer, that means a lot of C# / .NET, some C, PowerShell, and maybe even the Win32 API. The tools in this cookbook are best of breed for that kind of work. If you're new to development on Windows, this cookbook gives you the tools used by the most experienced Windows developers.
• Unix users on Windows: You're primarily a Linux-focused developer who finds herself using Windows. This toolset makes sure you won't feel lost without standard-issue Linux capabilities such as a usable terminal, remote package manager, and real text editors with programming language syntax support.

Requirements

This cookbook supports only the Windows operating system. It requires Windows Server 2008 R2 / Windows 7 or later.

For the local workstation configuration use case (i.e. where you're not managing the node via a Chef Server), you must have the following prerequisites installed:

• chef-client and berkshelf: to install these, just install the ChefDK, which includes them.
• git (recommended): The best way to obtain this cookbook is by cloning it from its source on Github. You can install git for Windows by visiting Github in case you don't already have a package manager.

Detailed installation -- your workstation

If your goal is to configure a local workstation (possibly the one you're using to read this) without using a Chef Server, simply do the following from a PowerShell session:

# Clone this repository and cd to it
git clone https://github.com/adamedx/winbox
cd winbox

# Use Berkshelf to download all cookbook dependencies:
berks vendor cookbooks

# Run `chef-client` in local mode to configure the workstation!
chef-client -z --color -o 'winbox'

After a brief period of downloading and installing features and configuring the system, your workstation should be ready to go!

Using with your Chef Server

This cookbook can be used on a managed Chef node like any other cookbook simply by uploading the cookbook to your Chef Server and configuring a node via bootstrap or setting the node's runlist to use a recipe. You can then configure it by converging it with a chef-client run.

winbox::default

Use this recipe to get common tools required for development.

Detailed features

All right, you've installed everything, so what can you do? Here are a few things to try:

• Run ConEmu! ConEmu should be available on your Start Menu / Screen, or by running ConEmu64.exe from within a command-line shell. ConEmu is a replacement for the limited terminal application used by default on Windows. The ConEmu terminal is much more like those on Linux desktop systems; the window is resizable, it supports ANSI color sequences, line-wrapped (instead of block) text selection, and many, many other advanced features. By default, ConEmu will run a PowerShell session in its terminal, though it can be configured to run a different shell.

• Use PSReadline with PowerShell! You should already be using PowerShell as your command-line shell and primary method of interacting with Windows. If you're not familiar with PSReadline, it enhances any PowerShell, even those run in the default terminal application, so that Emacs-style line editing keyboard shortcuts including command history search are available when editing commands. This makes the experience of using PowerShell very similar to Unix shells like bash, which support this editing capability by default.

• Use a real text editor to edit... code! Whether it's Ruby, C++, C#, Java, or PowerShell, any of the editors installed by this cookbook can perform syntax highlighting and in general offer the advanced editing capabilities required by developers. By default, the cookbook will install Visual Studio Code which you can launch from PowerShell by executing the command code. You can override this default using the cookbook's editor attribute. See subsequent sections for details on configuring other editors such as Atom, Emacs, and Vim.

• Install software using Chocolatey. The Chocolatey package manager is similar to those on Linux. Try it out -- usage is similar to apt-get on Debian systems:

  choco install sysinternals

• Install PowerShell modules using PSGet. PSGet is like Chocolatey, except it's focused on PowerShell modules rather than applications:

  install-module pester

• Get detailed command help with man. PowerShell provides a default alias man for the get-help cmdlet which is similar to the Unix man command. Unfortunately, this useful alias defaults to giving very limited help, requiring you to remember to pass the -full switch to man. This cookbook redefines the alias so that it gives full help by default.

• Add some color to your PowerShell prompt. You'll only see this feature if you don't already have a PowerShell profile (see the $PROFILE variable in PowerShell for the location of this file). If you don't have one, this cookbook creates one for you that will add color to the prompt and also show the name of the system you're using along with your username. For advanced usage, it shows the exit code of the last Windows process launched by the shell, and the prompt changes color based the success or failure of the last PowerShell cmdlet that was executed.

• Run a PowerShell script! This cookbook unlocks the revolutionary power of using a scripting language to... run scripts :smile:. It does this by doing something you've most likely already done on your workstation, but in case you haven't, or you're setting up a new workstation, it sets the PowerShell execution policy to Unrestricted so that you can run scripts without signing them.

• Use the ssh client. Because the git client distribution installed by this cookbook also contains an ssh client, you can use it simply by executing the ssh command from PowerShell or other shells on the system.

• Get to your Documents directory fast. This cookbook defines an alias docs that will change your current directory to your Documents directory, even if it's configured to a network location. Very useful since Windows developer workstations often contain more traditional "document" content. Consider this one a bonus feature.

Advanced cookbook usage and notes

Advanced usage includes customizing the file ~/winbox-ps-profile.ps1 used by this cookbook's PowerShell profile. Editing this file is an easy way to update the PowerShell profile directly.

Here is additional behavior related to PowerShell profiles:

• The cookbook never alters an existing PowerShell profile.
• To use this cookbook's PowerShell profile if you have an existing profile, rename your PowerShell profile and run the powershell_dev recipe or any other recipe such as default that includes it.
• The PowerShell profile used by this cookbook actually uses the content in ~/winbox-ps-profile.ps1, which is not updated if it already exists. To get profile changes from subsequent revisions of the cookbook, rename ~/winbox-ps-profile.ps1 and re-run the correct recipe.
• Note that because ~/winbox-ps-profile.ps1 is not updated by this cookbook if it exists, it's safe for you to edit its content to customize your profile.

How to use Windows -- an aside

Efficient, sophisticated users of Windows follow these rules:

• Always use PowerShell. Never use cmd.exe, and no cygwin except for fun.
• Use PowerShell cmdlets for everything instead of GUI tools (e.g. get-eventlog instead of EventViewer)
• Use the man alias in PowerShell to get detailed help on commands.
• Use ConEmu as your PowerShell terminal.
• Use psreadline for bash-like key-bindings, history search
• Use a real editor, not notepad.exe. Emacs, VI(m), Atom, Visual Studio are real editors.
• Use chocolatey as your package manager to obtain software.
• Use psget to obtain PowerShell modules.

See subsequent sections for details on why this advice matters.

Recipe inventory

winbox::default

Use this recipe to get common tools required for development.

In addition to the default recipe, the following recipes with more focused functionalit