Safety & Best Practices

Critical Safety Information

What These Scripts Do

Understanding what automation scripts do to your system is the first and most important step toward using them safely. The Chocolatey Scripts project performs the following types of operations on your Windows machine:

1. Install Software — The scripts download and install the Chocolatey package manager along with any Windows applications you specify. This means new software is being added to your system that was not there before, including executables, libraries, and registry entries.
2. Modify System Settings — The PowerShell execution policy may be changed to allow script execution. Environment variables are configured so that Chocolatey is accessible from any command prompt. Chocolatey's own configuration is adjusted to enable features like global confirmation.
3. Create Scheduled Tasks — If you set up automatic updates, the scripts create Windows Task Scheduler jobs that run in the background on a schedule. These jobs persist across restarts and will continue running until you remove them.
4. Network Operations — Packages and applications are downloaded from the internet via Chocolatey's community repository and official package sources. This generates network traffic and consumes bandwidth during installation and updates.
5. File System Changes — The scripts create directories for logs, configuration files, and package backups. Log files are written to %USERPROFILE%\Logs\. Backup files are stored in %USERPROFILE%\Documents\ChocolateyBackups\.

Potential Risks

Every system automation tool carries inherent risks. Being aware of these risks allows you to make informed decisions and take appropriate precautions:

• System Changes — Modifications to execution policies, environment variables, and installed software may affect how applications and services behave. If you have custom PowerShell profiles or environment configurations, the scripts could potentially interact with them in unexpected ways.
• Network Usage — Downloads can consume significant bandwidth, especially during initial setup when many packages are being installed simultaneously. The essential apps script alone may download several gigabytes of software. Be mindful if you are on a metered connection or have data caps.
• Disk Space — Applications, their dependencies, and Chocolatey's download cache require storage space. A full installation with all the default applications can use 5-10 GB or more of disk space. Running the cleanup script periodically helps manage this.
• Security — Installing any software carries some security risk. While Chocolatey verifies package checksums and uses HTTPS for all downloads, you should always be aware of what you are installing and verify that packages come from trusted sources.
• Administrator Privileges — Most operations require running PowerShell as Administrator. Elevated scripts have full access to your system, including the ability to modify any file, change any setting, and install any software. This power is necessary for package management but should be respected.

Built-in Safety Measures

Chocolatey Scripts includes multiple layers of safety features designed to protect your system and give you full control over every operation. These measures are built into the core of every script, not bolted on as an afterthought.

1. Idempotent Operations

All operations in Chocolatey Scripts are designed to be idempotent, meaning you can run them multiple times without causing problems. Before performing any action, the script checks whether the desired state already exists and skips the operation if it does.

# Safe to run multiple times — checks before acting
if (Get-Command choco -ErrorAction SilentlyContinue) {
    Write-Success "Chocolatey is already installed"
    return
}
# Only reaches here if Chocolatey is NOT installed
Write-Status "Installing Chocolatey..."

This design has several practical benefits. You can safely resume a script after an interruption — it will pick up where it left off without duplicating work. If you run the essential apps script again after adding new apps to the list, it will only install the new ones and skip everything that is already in place. Running a script multiple times will never create duplicate installations, conflicting configurations, or wasted downloads. This idempotent design is a professional software engineering pattern that makes the scripts robust and forgiving.

2. Prerequisite Checks

Before making any changes to your system, the scripts validate that all prerequisites are met. The validation script performs a comprehensive check of your environment and reports all issues at once, rather than failing on the first problem.

# Validates your system before making any changes
.\validate-setup.ps1

The prerequisite checks verify the following:

• PowerShell version meets the minimum requirement (5.1 or later)
• Administrator privileges are available for the current session
• Chocolatey is installed and working (for scripts that depend on it)
• Config file exists and contains valid JSON syntax
• Disk space is sufficient for the planned operations
• Network connectivity is available for downloading packages

If any check fails, the script reports the issue with a clear description and a suggestion for how to fix it. This prevents the frustrating experience of running through half an installation only to have it fail because of a missing prerequisite.

3. Comprehensive Logging

Every operation performed by the scripts is recorded in a detailed log file with timestamps, severity levels, and descriptive messages. This creates a complete audit trail that you can review at any time to understand exactly what happened on your system.

# All operations are logged with timestamps
$LogFile = "$env:USERPROFILE\Logs\ChocolateyInstall.log"

# Example log entries
[2026-02-06 14:30:15] [INFO] Starting Chocolatey installation...
[2026-02-06 14:30:18] [INFO] Downloading Chocolatey from official source
[2026-02-06 14:30:45] [SUCCESS] Chocolatey 2.4.1 installed successfully
[2026-02-06 14:31:02] [INFO] Installing Visual Studio Code...
[2026-02-06 14:31:30] [SUCCESS] Visual Studio Code installed successfully
[2026-02-06 14:31:45] [WARNING] Package 'unknown-app' not found, skipping
[2026-02-06 14:32:00] [ERROR] Failed to install broken-package: checksum mismatch

The log captures every command executed, all configuration changes made, every error and warning encountered, system state information, and timestamps for all operations. If something goes wrong, the log is the single best resource for understanding what happened and why. You can review logs at any time:

# View the most recent log entries
Get-Content "$env:USERPROFILE\Logs\ChocolateyInstall.log" -Tail 30

# Search for errors across all log files
Get-ChildItem "$env:USERPROFILE\Logs\Chocolatey*.log" |
    ForEach-Object { Select-String "ERROR" $_ }

4. Input Validation

Every piece of user input and configuration is validated before it is used. This prevents common mistakes from causing problems downstream, such as invalid file paths, malformed JSON, or placeholder values that were never customized.

# Configuration files are validated before use
try {
    $config = Get-Content $configPath -Raw | ConvertFrom-Json
    Write-Pass "config.json has valid JSON syntax"
}
catch {
    Write-Fail "config.json has invalid JSON: $($_.Exception.Message)"
    return $false
}

# Placeholder values are detected and flagged
if ($config.wifiNetwork -eq "YOUR_WIFI_NAME") {
    Write-Warn "WiFi network is still set to the placeholder value"
}

Validation is performed early in the script's execution, during the pre-flight check phase. This means that if there is a problem with your configuration, you will find out immediately rather than discovering it halfway through a long installation process. The validation covers config file syntax and structure, system requirements and compatibility, network and power conditions, and placeholder values that need to be customized.

5. Error Recovery

When things go wrong — and with network operations, they sometimes do — the scripts handle failures gracefully. Transient errors such as network timeouts are automatically retried with delays between attempts, giving temporary issues time to resolve themselves.

# Automatic retry for transient failures
$retryCount = 0
while ($retryCount -lt $MaxRetries) {
    try {
        # Attempt the operation
        choco install $PackageName -y --no-progress
        if ($LASTEXITCODE -eq 0) {
            Write-Success "$PackageName installed successfully"
            break
        }
    }
    catch {
        Write-Warning "Attempt $($retryCount + 1) failed: $($_.Exception.Message)"
    }

    $retryCount++
    if ($retryCount -lt $MaxRetries) {
        Write-Status "Retrying in $RetryDelay seconds..."
        Start-Sleep -Seconds $RetryDelay
    }
}

When retries are exhausted and an operation truly fails, the script logs a detailed error message and continues with the remaining operations rather than crashing entirely. This graceful degradation means that a single failed app installation does not prevent all the other apps from being installed. At the end of the run, you get a clear summary of what succeeded and what needs attention.

Pre-Installation Checklist

Before running any script for the first time, work through this checklist to make sure your system is prepared. Taking a few minutes to prepare will save you time and potential headaches later.

System Requirements

• Windows 10 (version 1809 or later) or Windows 11 installed
• PowerShell 5.1 or later available (PowerShell 7+ recommended)
• Administrator privileges (you know your password or have access to an admin account)
• At least 10 GB free disk space available on your system drive
• Stable internet connection active and working
• No critical work in progress (in case a restart is needed after installing certain packages)

Preparation Steps

• Create a system restore point before running scripts for the first time. Open System Properties (type "restore point" in the Start menu), click "Create," and give it a descriptive name like "Before Chocolatey Scripts." This gives you a way to roll back if anything goes wrong.
• Close important applications to avoid conflicts during installation. Some apps may need to be restarted if they are updated, and having open files could prevent updates from completing.
• Review config.example.json to understand what will be configured. Check each setting and make sure you understand what it controls before copying it to config.json.
• Copy config.example.json to config.json and customize the settings for your environment. At minimum, update the wifiNetwork setting if you plan to use automatic updates.
• Run validate-setup.ps1 to check your environment. This script verifies all prerequisites without making any changes and tells you if anything needs to be fixed first.
• Have your password ready for the User Account Control (UAC) prompt that appears when you run PowerShell as Administrator.

Network Considerations

• Connected to a reliable network with good throughput (wired is ideal for initial setup)
• Sufficient bandwidth for potentially large downloads (the full app suite can exceed 2 GB)
• Not on a metered connection if data usage is a concern
• Firewall allows connections to chocolatey.org and community.chocolatey.org
• If behind a corporate proxy, Chocolatey may need proxy configuration (see Chocolatey proxy documentation)

Best Practices for Usage

Following these best practices will help you get the most out of Chocolatey Scripts while minimizing the chance of running into issues. These recommendations come from real-world experience and represent the safest, most effective way to use system automation tools on Windows.

1. Start with Validation

Before running any installation or update script, always run the validation and health check scripts first. They verify that your environment is properly configured and identify any issues that should be resolved before proceeding.

# Always run these first
.\validate-setup.ps1
.\health-check.ps1

The validation script checks your configuration file, environment, and prerequisites. The health check examines the state of your Chocolatey installation and reports on outdated packages, disk usage, and scheduled tasks. Together, they give you a complete picture of your system's readiness.

2. Install in the Right Order

The scripts are designed to be run in a specific order. Following this order ensures that each script's prerequisites are met by the scripts that came before it.

# Step 1: Install the package manager first
.\install-chocolatey.ps1

# Step 2: Then install applications
.\install-essential-apps.ps1

# Step 3: Verify everything is working
.\health-check.ps1

# Step 4 (optional): Set up automation
.\setup-scheduled-tasks.ps1

Trying to run the essential apps script before installing Chocolatey will fail, because the choco command does not exist yet. The scripts include checks for this, but following the intended order avoids unnecessary error messages and retries.

3. Review Logs Regularly

After each script run, take a moment to review the log file. Look for warnings and errors that might indicate issues requiring your attention. This is especially important for automated update runs where you do not see the console output directly.

# Check what happened during the last run
Get-Content "$env:USERPROFILE\Logs\ChocolateyInstall.log" -Tail 30

# Search for errors specifically
Get-ChildItem "$env:USERPROFILE\Logs\Chocolatey*.log" |
    ForEach-Object { Select-String "ERROR" $_ }

# View recent errors with their timestamps
Get-Content "$env:USERPROFILE\Logs\*.log" |
    Select-String "ERROR" |
    Select-Object -Last 20

4. Back Up Before Major Changes

Before running updates or making significant changes to your installed packages, create a backup of your current package configuration. This gives you a restore point that can be used to recreate your exact setup on a new machine or recover from a problem.

# Export your current package list before changes
.\backup-packages.ps1 -Action Backup

# Restore on a new machine or after a problem
.\backup-packages.ps1 -Action Restore -BackupFile "path\to\backup.json"

5. Keep Configuration Under Control

Your config.json file is git-ignored because it contains personal settings like your WiFi network name and email address. However, you should still keep a backup somewhere safe in case you need to set up again on a new machine. Consider storing it in a secure cloud location or an encrypted backup.

6. Review Scripts Before Running

Every script in this project is open source and extensively commented. You are encouraged to read and understand the code before running it. This is an educational project, and understanding what each script does is part of the learning experience.

# Read any script before executing it
Get-Content .\script-name.ps1 | more

# Or open it in your preferred editor
notepad .\script-name.ps1
code .\script-name.ps1

Emergency Procedures

Even with all the safety measures in place, things can occasionally go wrong. This section describes what to do if you encounter problems during or after running the scripts. The most important thing is to stay calm — nearly every issue is recoverable.

If Something Goes Wrong

1. Do not panic. Most issues are recoverable, and the scripts are designed to fail safely without leaving your system in a broken state.
2. Check the logs. Open the log files at $env:USERPROFILE\Logs\ and look for ERROR entries near the bottom. The log will usually tell you exactly what went wrong and may suggest a fix.
3. Stop the script if it is still running by pressing Ctrl+C. PowerShell will terminate the script and return you to the command prompt.
4. Note what happened. Document which script you were running, what step it was on, and what error messages appeared. This information is invaluable for troubleshooting.

Recovery: Chocolatey Installation Issues

If Chocolatey itself is not working correctly or the installation was interrupted, you can check its status and attempt repairs.

# Check if Chocolatey is accessible
choco --version

# If not found, refresh environment variables
refreshenv

# If still not found, the installation may be incomplete
# Check the execution policy first
Get-ExecutionPolicy
# If "Restricted", fix it:
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

# Try running the installation script again (it's idempotent)
.\install-chocolatey.ps1

Since the installation script is idempotent, running it again will detect whatever state Chocolatey is in and take the appropriate action — whether that means completing a partial installation, reconfiguring an existing one, or simply confirming that everything is already working.

Recovery: Package Installation Failures

If a specific application fails to install or is not working correctly after installation, you can remove it through Chocolatey and try again, or clear the download cache to force a fresh download.

# Remove a problem package
choco uninstall problematic-package -y

# Clear Chocolatey's download cache
Remove-Item "$env:TEMP\chocolatey" -Recurse -Force -ErrorAction SilentlyContinue

# Try installing again with verbose output for debugging
choco install problematic-package -y -v

# If the package doesn't exist, search for the correct name
choco search package-name

Recovery: Scheduled Task Not Running

If automated updates are not running as expected, check the scheduled task status and recreate it if necessary.

# Check if the task exists and its current status
Get-ScheduledTask | Where-Object { $_.TaskName -like "*Chocolatey*" }

# View the last run time and result
Get-ScheduledTask -TaskName "Chocolatey*" |
    Get-ScheduledTaskInfo

# Re-create the scheduled tasks
.\setup-scheduled-tasks.ps1

Recovery: System Restore

If you created a system restore point before running the scripts (as recommended in the Pre-Installation Checklist), you can use it to roll back your entire system to its previous state.

# Open System Restore from PowerShell
rstrui.exe

System Restore will undo all software installations, configuration changes, and registry modifications made since the restore point was created. It does not affect your personal files, but it will remove any applications that were installed after the restore point.

Security Considerations

Security is a fundamental concern when running any automation script with administrator privileges. Chocolatey Scripts is designed with security in mind, but understanding the security model helps you make informed decisions about how and when to use the scripts.

Script Security

• Read before running — Understand what a script does before executing it. Every script in this project is fully open source and extensively commented. Use Get-Content .\script.ps1 | more to review any script before running it.
• Trusted sources only — Only run scripts from sources you trust. The official Chocolatey Scripts repository is hosted on GitHub at github.com/DJCastle/chocolateyScripts, and you should always download from this URL.
• Admin awareness — Know that elevated scripts can change anything on your system. Only run PowerShell as Administrator when a script requires it, and close the elevated session when you are done.
• Keep scripts updated — Pull the latest version from the repository periodically to get security fixes and improvements. If you cloned with Git, run git pull to update.

Application Security

• Official sources — Chocolatey packages come from the community repository, which is maintained by the Chocolatey community. Packages are reviewed by moderators before being published.
• Checksum verification — Chocolatey automatically verifies package checksums before installation. If a package's checksum does not match the expected value, the installation is refused. This protects against tampered or corrupted downloads.
• Keep apps updated — Running choco upgrade all regularly (or using the auto-update script) ensures your installed software receives security patches promptly. Outdated software is one of the most common attack vectors.
• Verify before installing — Use choco info package-name to review package details, including the maintainer, download count, and last update date, before installing unfamiliar packages.

Network Security

• HTTPS connections — All downloads use encrypted HTTPS connections. No package data is transmitted in plain text, protecting against eavesdropping and tampering during transit.
• No credential storage — These scripts do not store your Windows password, tokens, or other credentials. The SMTP password for email notifications is the only credential-like value, and it is stored in a separate, git-ignored file that you control.
• Logged activity — All network operations are recorded in log files, creating an audit trail that you can review to understand exactly what was downloaded and from where.
• WiFi-aware updates — The auto-update script can be configured to only run when connected to a specific WiFi network, preventing large downloads on untrusted or metered networks.

Customization Guidelines

One of the strengths of Chocolatey Scripts is that it is designed to be customized. Whether you are adjusting the configuration to match your preferences or modifying the scripts themselves to add new functionality, these guidelines will help you do so safely and effectively.

Safe Modifications

These are changes that carry minimal risk and are fully supported by the scripts' design:

• Configuration changes — Modify config.json to change your WiFi network, notification preferences, backup paths, and scheduling options. The configuration file is designed to be the primary customization point.
• Application lists — Edit the $apps array in install-essential-apps.ps1 to add or remove applications. Use choco search to find the correct package names for applications you want to add.
• Scheduled task timing — Adjust when automatic updates and cleanup run to fit your schedule. The setup wizard makes this easy, or you can modify the task directly through Windows Task Scheduler.
• Notification preferences — Enable or disable email notifications, toast notifications, or both. Configure which events trigger notifications (success, error, warning) to match your monitoring preferences.

Advanced Modifications

These changes require some PowerShell knowledge and should be tested thoroughly before deploying:

• Function additions — Add new helper functions to extend the scripts' capabilities. Follow the existing function patterns (parameter blocks, error handling, dual-output logging) for consistency.
• Validation rules — Enhance the validate-setup.ps1 script to check for additional requirements specific to your environment.
• Error handling — Improve error recovery mechanisms for scenarios specific to your setup, such as proxy authentication or VPN connectivity.
• Logging enhancements — Add more detailed logging for operations you want to monitor closely, or implement log rotation to manage file sizes.

Testing Your Changes

After making any modifications to the scripts, always validate your changes before running them for real. Here is a quick testing process:

# Step 1: Check PowerShell syntax without running the script
powershell -Command "& { Get-Content .\your-script.ps1 | Out-Null }"

# Step 2: Use PSScriptAnalyzer for deeper best practice analysis
# (Install first if needed: Install-Module PSScriptAnalyzer)
Invoke-ScriptAnalyzer -Path .\your-script.ps1

# Step 3: Test the validation script to catch config issues
.\validate-setup.ps1

# Step 4: Test individual functions in an interactive session
# before running the full script
. .\your-script.ps1  # dot-source to load functions
Test-Prerequisites     # test individual functions