Ruby, InSpec, and Terminal Customization Setup Guide (Windows)¶

Windows Development Environment

This guide provides a comprehensive setup for Ruby and InSpec development on Windows, including modern terminal customization for an enhanced developer experience.

1. Ruby Version Management¶

Recommended Tools

RubyInstaller - Official Ruby distribution for Windows
uru - Lightweight Ruby version manager for Windows

Installation Steps¶

Download and install Ruby (with DevKit) from RubyInstaller.
Install uru (via Chocolatey or manual download):
```
choco install uru
```
Register each Ruby version:
```
uru admin add C:\Ruby34-x64\bin
```
Switch versions:
```
uru <label>
```
List registered Rubies:
```
uru ls
```

Installing uru with Chocolatey

Chocolatey is the easiest way to install uru on Windows:

choco install uru

While the uru downloads page doesn't prominently mention this option, the uru installation wiki provides comprehensive details.

2. Disable Gem Documentation (Faster Installs)¶

Speed up gem installations

Create or edit %USERPROFILE%\.gemrc to disable documentation generation:

gem: --no-document

gem install inspec inspec-bin inspec-core --no-document

4. Terminal Customization¶

Modern Terminal Stack

Transform your Windows terminal into a powerful, beautiful development environment:

Essential Components¶

Windows TerminalPowerShell 7+

Install from Microsoft Store for a modern, GPU-accelerated terminal experience.

Install via winget or Chocolatey:

winget install Microsoft.PowerShell
# or
choco install powershell-core

Prompt Customization¶

Oh My Posh:

winget install JanDeDobbeleer.OhMyPosh
oh-my-posh init pwsh --config "$(oh-my-posh get shell-path pwsh)" | Invoke-Expression

Starship:

winget install Starship.Starship
echo 'Invoke-Expression (&starship init powershell)' >> $PROFILE

Nerd Fonts Required

Download and install a Nerd Font for proper icon display in your customized prompt. Popular choices include:

FiraCode Nerd Font
Meslo Nerd Font
JetBrains Mono Nerd Font

5. Troubleshooting & Tips¶

Common Issues and Solutions

Path Issues: Ensure Ruby's bin directory is in your PATH.
Permissions: Run terminals as a regular user unless you need admin rights.
Native Gem Builds: May be slow on Windows VMs/Citrix; be patient.
Switching Rubies: Use uru to change Ruby versions as needed.

Multiple Gem Versions

Check for multiple versions:

gem list inspec
gem list ffi

Uninstall old/conflicting versions:

gem uninstall inspec
gem uninstall ffi

Ruby Version Activation

Always activate the correct Ruby version with uru <label> before installing or running gems.

Removing Directories

Use PowerShell to remove directories:

Remove-Item -Recurse -Force <directory>

SSL/Certificate Issues

If you encounter SSL errors with gem or ruby:

Ensure your system certificates are up to date

For organizational CAs, add the certificate to Windows certificate store:

[System.Environment]::SetEnvironmentVariable("SSL_CERT_FILE", 
    "C:\\path\\to\\your\\ca-bundle.crt", 
    [System.EnvironmentVariableTarget]::User)

Update Ruby's certificate bundle if needed - see Ruby SSL Troubleshooting

FFI Troubleshooting

If you see ffi errors:

Install with platform flag:
```
gem install ffi --platform=ruby
```
Ensure you have a compatible Ruby and DevKit/MSYS2 environment

6. VS Code Setup¶

Enhanced Development Experience

Install VS Code.
Recommended extensions:
Ruby
Solargraph
VSCode Ruby
Test Explorer UI
PowerShell (for Windows)
Configure your terminal in VS Code to use Windows Terminal or PowerShell as preferred.

7. Resources¶

Resource	Description	Link
RubyInstaller	Official Ruby distribution for Windows	rubyinstaller.org
uru	Lightweight Ruby version manager	bitbucket.org/jonforums/uru
InSpec	Infrastructure testing framework	inspec.io
Oh My Posh	Prompt theme engine for any shell	ohmyposh.dev
Starship	Cross-shell prompt	starship.rs
Nerd Fonts	Patched fonts with icons	nerdfonts.com

8. Additional Best Practices & FAQ¶

Environment Isolation¶

Project Isolation with Bundler

Use Bundler and a Gemfile for project-specific dependencies:

# Gemfile
source 'https://rubygems.org'
gem 'inspec', '~> 6.0'

Then run:

gem install bundler
bundle install

This helps avoid global gem conflicts and ensures consistent environments.

Automated Setup Script¶

Automation Opportunity

Consider creating a PowerShell script to automate the setup process for new team members, including Ruby installation, uru configuration, and gem setup.

Checking Ruby & Gem Health¶

Verify your environment:
```
ruby -v
gem -v
gem env
where inspec
```

Proxy/Firewall/Corporate Network Issues¶

If your organization uses a proxy, set these environment variables:

[System.Environment]::SetEnvironmentVariable("HTTP_PROXY", "http://proxy.example.com:8080", [System.EnvironmentVariableTarget]::User)
[System.Environment]::SetEnvironmentVariable("HTTPS_PROXY", "http://proxy.example.com:8080", [System.EnvironmentVariableTarget]::User)

Windows Defender/Antivirus¶

Some antivirus or Defender settings may block Ruby or gem executables. If you encounter issues, whitelist the Ruby install directory.

Sample PowerShell Profile¶

Add this to your $PROFILE to auto-activate a Ruby version and set up your prompt:

# Auto-activate Ruby version with uru
uru 344  # or your preferred label
# Optional: initialize Oh My Posh or Starship
oh-my-posh init pwsh --config "$(oh-my-posh get shell-path pwsh)" | Invoke-Expression
# or
Invoke-Expression (&starship init powershell)

Frequently Asked Questions¶

FAQ

Why do I get SSL errors?
Your system or Ruby certificates may be out of date. See the SSL/Certificate Issues section above.
How do I fix ffi build errors?
Ensure you have the correct DevKit/MSYS2 installed and try gem install ffi --platform=ruby.
How do I clean up old Ruby or gem versions?
Use uru admin rm <label> to remove old Rubies, and gem uninstall <gemname> to remove old gems.
How do I check which Ruby or gem is active?
Run ruby -v, gem env, and where inspec to verify your environment.

9. Referenced Sources & Validation Summary¶

Official Documentation & References¶

Feel free to share this guide with your team or adapt it for your organization!