Skip to content

installation.md

Latest commit

 

History

History
310 lines (219 loc) · 7.01 KB

installation.md

File metadata and controls

310 lines (219 loc) · 7.01 KB
Raw

Installation Guide

Complete step-by-step guide to installing PowerShell DevKit.

Before You Begin

  1. Review the Requirements
  2. Close all PowerShell windows (setup will reload profile automatically)
  3. Ensure you have internet connectivity

Installation Methods

Method 1: Automated Setup (Recommended)

This is the easiest way to get started.

Step 1: Clone the Repository

=== "Windows" powershell cd C:\Dev # or your preferred location git clone https://github.com/Tsabo/PowerShell-DevKit.git cd PowerShell-DevKit

=== "macOS" bash git clone https://github.com/Tsabo/PowerShell-DevKit.git cd PowerShell-DevKit

=== "Linux / WSL" bash git clone https://github.com/Tsabo/PowerShell-DevKit.git cd PowerShell-DevKit

Step 2: Run Setup Script

=== "Windows — As Administrator (Recommended)"

```powershell
# Right-click PowerShell and "Run as Administrator"
cd C:\Dev\PowerShell-DevKit
.\Scripts\Setup.ps1

# Optional: enable local admin shares policy (c$, d$, etc.)
.\Scripts\Setup.ps1 -EnableAdminShares
```

**Benefits:**
- All components install successfully
- Windows Terminal configured automatically
- No UAC prompts during installation

=== "Windows — As Standard User"

```powershell
.\Scripts\Setup.ps1
```

**Limitations:**
- Some components may be skipped
- May require manual UAC approval
- Windows Terminal config might need manual copy

=== "macOS"

```bash
./Scripts/Setup-macOS.ps1
```

=== "Linux / WSL"

```bash
pwsh -File ./Scripts/Setup-Linux.ps1
```

!!! tip "Linux / WSL — Full Guide"
    See the dedicated [Linux / WSL Setup Guide](linux-setup.md) for details on fonts, PATH configuration, and WSL-specific notes.

Step 3: Verify Installation

# Run the test script
.\Scripts\Test.ps1

Expected output shows all components installed with ✓ marks.

Method 2: Manual Installation

If you prefer to install components individually:

1. Install Core Tools

# Install oh-my-posh
winget install JanDeDobbeleer.OhMyPosh

# Install Yazi
winget install sxyazi.yazi

# Install fzf
winget install junegunn.fzf

# Install zoxide
winget install ajeetdsouza.zoxide

2. Install PowerShell Modules

Install-Module -Name PSFzf -Scope CurrentUser
Install-Module -Name Terminal-Icons -Scope CurrentUser
Install-Module -Name F7History -Scope CurrentUser
Install-Module -Name posh-git -Scope CurrentUser

3. Deploy Configuration

# Run deployment scripts individually
.\Scripts\Deploy-Terminal.ps1
.\Scripts\Deploy-PowerShellProfile.ps1

Post-Installation

Reload Your Profile

# Apply the new configuration
. $PROFILE

Verify Installation

Run the test script to ensure everything is working:

=== "Windows" powershell .\Scripts\Test.ps1

=== "macOS" powershell pwsh -File ./Scripts/Test-macOS.ps1

=== "Linux / WSL" powershell pwsh -File ./Scripts/Test-Linux.ps1

Install Optional Components

# Install Yazi optional dependencies
Install-YaziOptionals

# Install just plugins
Install-YaziOptionals -PluginsOnly

# Install just dependencies
Install-YaziOptionals -DependenciesOnly

Optional: Enable Local Administrative Shares (Windows)

If you need local administrative shares such as c$ or d$ with local administrator accounts, run setup with:

.\Scripts\Setup.ps1 -EnableAdminShares

This writes:

  • HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System\LocalAccountTokenFilterPolicy = 1

Notes:

  • Windows only
  • Requires Administrator privileges
  • Skipped when using -SkipOptional

Setup Process Details

What the Setup Script Does

  1. Prerequisites Check

    • Validates PowerShell version
    • Checks for winget availability
    • Verifies internet connectivity

  2. Core Installation

    • Installs oh-my-posh with CascadiaCode font
    • Installs Yazi file manager
    • Installs fzf, zoxide, and other tools
    • Installs PowerShell modules from Gallery

  3. Configuration Deployment

    • Copies Windows Terminal settings
    • Deploys PowerShell profile
    • Deploys oh-my-posh themes
    • Clones Yazi configuration

  4. Yazi Ecosystem

    • Installs optional dependencies (FFmpeg, 7-Zip, etc.)
    • Installs Yazi plugins (git, githead)
    • Sets up themes (flexoki-light, vscode-dark-plus)

  5. Verification

    • Runs component tests
    • Displays installation summary
    • Shows any issues that need attention

Optional with -EnableAdminShares:

  • Applies LocalAccountTokenFilterPolicy=1 for local administrative share access

Progress Indicators

During installation, you'll see:

🔹 Installing oh-my-posh...
  → Checking if already installed...
  ✓ oh-my-posh installed successfully

🔹 Installing Yazi...
  → Installing Yazi...
  ✓ Yazi binary installed
  → Installing optional dependencies for enhanced functionality...
    → [1/7] Checking FFmpeg (for video thumbnails)...
      ✓ FFmpeg installed

Timeout Protection

All package installations have built-in timeouts:

  • 15 seconds for checking if already installed
  • 60 seconds for package installation
  • 30 seconds for git operations

If any operation times out, it's skipped and installation continues.

Troubleshooting Installation

Common Issues

!!! warning "Execution Policy Error" Error: cannot be loaded because running scripts is disabled

**Solution:**
```powershell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```

!!! warning "winget Not Found" Error: winget: The term 'winget' is not recognized

**Solution:**
- Update Windows to latest version
- Install [App Installer](https://www.microsoft.com/p/app-installer/9nblggh4nns1) from Microsoft Store

!!! warning "Module Installation Failed" Error: Unable to install module from PSGallery

**Solution:**
```powershell
# Trust PSGallery
Set-PSRepository -Name PSGallery -InstallationPolicy Trusted
```

Checking Logs

Setup logs are saved to .\Scripts\Logs\Setup_YYYYMMDD_HHMMSS.log

# View the most recent log
Get-Content .\Scripts\Logs\Setup_*.log | Select-Object -Last 50

Getting Help

Next Steps

Updating

After initial installation, keep everything up to date:

# Run the update script
.\Scripts\Update.ps1

This updates:

  • All winget packages
  • PowerShell modules
  • Yazi configuration
  • Yazi plugins and themes