🎉 WSL Web‑Dev Environment Scripts 🐧⭐️

Transform a clean WSL 2 Ubuntu install into a full-featured, secure web‑development environment in just minutes. Whether you’re building PHP, Node, or static sites, these scripts handle installation, configuration, and SSL for you—so you can focus on coding.

---

🚀 Table of Contents

1. 📝 Overview
2. 🛠️ Installation
   • 🖥️ Installing WSL 2
   • 🎨 MesloLGS Nerd Font
3. ⚡️ Quick Start
4. 🧰 Usage
   • ➕➖ Add or Remove Projects
   • 🔄 Regenerate SSL & vhosts
   • 📚 Laravel Project Example
5. 🔒 Trusting SSL Certificates
6. 🛠️ Other Stuff
   • ⚙️ Configure Git
   • 🚚 Import Laragon Projects
   • 🔑 SSH Keys
   • 🖥️ Keep WSL2 Alive (GUI) by IvoMiranda
7. 🤝 Contributing
8. ⚖️ License
9. 🙏 Acknowledgments

---

📝 Overview

This repository provides a set of Bash scripts to automate every step of provisioning a web‑development environment on Windows 10/11 via WSL 2:

• Core services: Nginx with HTTP/2, MySQL (MariaDB fallback), Redis for caching, and Node LTS for JavaScript workloads.
• PHP ecosystem: Parallel PHP 8.2, 8.3, and 8.4 installations, PHP-FPM pools, Composer installer, and an intelligent wrapper to pick the right PHP version per project.
• Developer tooling: Zsh with Oh My Zsh, Powerlevel10k theme, autosuggestions, and syntax highlighting for a blazing-fast shell experience.
• HTTPS everywhere: Locally‑trusted *.test SSL certificates, automated Nginx virtual host generation, and hosts file updates on Windows.
• Resilience: Quiet, resumable installer with progress bars and state checkpoints—won’t leave your system half‑configured.

With these scripts, setting up a fresh WSL 2 instance becomes a single-command task, saving hours of manual work.

---

🛠️ Installation

🚧 Prerequisites

1. Windows Version: Windows 10 (2004+) or Windows 11 with WSL 2 support.
2. Virtualization: Enabled in BIOS/UEFI.
3. Admin Rights: Required for enabling features and updating hosts file.

🚧 Always Run as Administrator

Note: Many steps require elevated privileges. Launch Windows Terminal or PowerShell as Administrator to avoid permission errors.

🖥️ Installing WSL 2

1. Open an elevated PowerShell and enable required features:

   dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
   dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

2. Reboot your machine.
3. Install the WSL 2 Linux kernel from Microsoft:
   • Download from: https://aka.ms/wsl2kernel
4. Set your default distro version to WSL 2:

   wsl --set-default-version 2

5. Install Ubuntu 22.04 LTS (or another supported distro) from the Microsoft Store.
6. Launch the distro once (via your Admin Terminal) to finalize installation.

🎨 MesloLGS Nerd Font

Why? Powerlevel10k uses special glyphs for icons and powerline symbols.

1. Download the four MesloLGS NF font files (Regular, Bold, Italic, Bold Italic) from: https://github.com/romkatv/powerlevel10k-media
2. Install each font by right-click → Install for all users.
3. In Windows Terminal settings, set the font face to MesloLGS NF.
4. Verify inside WSL:

   ls /mnt/c/Windows/Fonts | grep 'MesloLGS NF'

---

⚡️ Quick Start inside WSL

1. Clone the repo and make scripts executable

   git clone https://github.com/pedr0cazz/wsl-scripts.git ~/.wsl_scripts
   chmod +x ~/.wsl_scripts/*.sh

2. Run the installer

   ~/.wsl_scripts/wsl-setup.sh

   • The script will prompt for your project root (~/www by default), SSL directory (~/ssl), and helper-scripts path.
   • Progress indicators and automatic rollback on errors ensure a reliable run.
3. Open a new shell or reload Zsh

   source ~/.zshrc

4. If you dont like the choosen settings you can rerun the p10k command

   p10k configure

Result: You now have Nginx, PHP-FPM, MySQL, Redis, Node, and Composer configured, plus a fancy Zsh prompt ready to go.

---

🧰 Usage

➕➖ Add or Remove Projects

• Project root: Defined during installation ($WEB_ROOT, default ~/www).
• Add a project: Create a directory under your root. Example:

  mkdir -p "$WEB_ROOT/my-app"

  On your next new shell (or manual run of ssl-manager.sh), a vhost my-app.test and SSL cert will be generated.
• Remove a project: Delete the directory:

  rm -rf "$WEB_ROOT/my-app"

  The script will detect the missing folder and clean up its Nginx configuration and Windows hosts entry.

🔄 Regenerate SSL & vhosts

Run the SSL manager at any time to sync your project directories with Nginx configs and certificates:

~/.wsl_scripts/ssl-manager.sh

No shell restart needed.

📚 Laravel Project Example

1. Install and scaffold a new Laravel project using the Laravel installer:

   # Install the Laravel installer globally
   composer global require laravel/installer
   
   # Scaffold a new project named "blog"
   cd "$WEB_ROOT"
   laravel new blog
   
   

2. Open a new shell to auto-generate OR manually run the SSL manager:

   ~/.wsl_scripts/ssl-manager.sh

   • Nginx vhost blog.test
   • Self-signed SSL cert trusted by your Windows host
3. Access your site securely:

   https://blog.test

4. If permissions issues arise, set correct ownership and mode:

   sudo chown -R "$USER":"$USER" blog
   chmod -R 775 blog/storage blog/bootstrap/cache
   cd ~/blog
   sudo chown -R $USER:www-data storage bootstrap/cache
   sudo chmod -R 775 storage bootstrap/cache

---

🔒 Trusting SSL Certificates

By default the installer generates a custom CA and issues all *.test certs.

1. Copy the root CA to Windows and rename to .crt:

   cp ~/ssl/ca/rootCA.pem /mnt/c/Users/<YourUser>/Desktop/rootCA.crt

2. On Windows double-click rootCA.crt → Install Certificate.
3. In the Certificate Import Wizard:
   • Choose Local Machine
   • Select Place all certificates in the following store → Browse → Trusted Root Certification Authorities
   • Click Next → Finish.
4. Restart your browser.

Now any *.test site issued by your CA will load without warnings.

---

🛠️ Other Stuff

⚙️ Configure Git

Set your name and email for commits:

# Replace with your identity
git config --global user.name "Your Name"
git config --global user.email "you@example.com"

🚚 Import Laragon Projects

Already have projects in Laragon? Copy them into WSL:

cp -r /mnt/c/laragon/www/* "$WEB_ROOT/"

Then run ssl-manager.sh to auto-generate vhosts and certs.

🔑 SSH Keys

Reuse existing Windows SSH keys:

mkdir -p ~/.ssh
cp /mnt/c/Users/<YourWindowsUser>/.ssh/id_rsa* ~/.ssh/
chmod 600 ~/.ssh/id_rsa
chmod 644 ~/.ssh/id_rsa.pub
ssh-add ~/.ssh/id_rsa

This enables passwordless Git over SSH inside WSL.

PHP Install another versions command

Replace 8.4 with the desired version:

sudo apt install php8.4 php8.4-fpm php8.4-mysql php8.4-redis php8.4-curl php8.4-zip php8.4-gd php8.4-mbstring php8.4-bcmath php8.4-xml php8.4-soap php8.4-intl

---

🔄 Keep WSL2 Alive (GUI)

Contributed by IvoMiranda, the wsl_nginx_gui.py script provides a lightweight graphical interface for Windows to prevent WSL2 from shutting down due to inactivity by periodically checking the Nginx service status.

⚙️ How it works:

• Runs a periodic status check of Nginx in WSL2 every few seconds (customizable).
• Keeps WSL2 active as long as the application window remains open.
• Displays a timer showing the time since the last check.

🚀 Quick Usage:

1. Ensure Python is installed on your Windows host.
2. Run the script from Windows:

   python wsl_nginx_gui.py

3. Adjust the interval by modifying the CHECK_INTERVAL_MS variable at the top of the script.

🤝 Contributing

Contributions, issues, and feature requests are welcome!

1. Fork the repo.
2. Create a feature branch (git checkout -b feature-name).
3. Commit your changes (git commit -m 'Add new feature').
4. Push to the branch (git push origin feature-name).
5. Open a Pull Request.

Please follow the Contributor Covenant guidelines.

---

⚖️ License

This project is licensed under the MIT License. See LICENSE for details.

---

🙏 Acknowledgments

• Powerlevel10k for the Zsh theme
• Ubuntu, Nginx, MySQL, Redis, PHP, Node.js, Composer, Oh My Zsh for the underlying technologies
• Open‑source community contributors and maintainers

Happy coding—and enjoy your new WSL 2 web‑dev environment! 🚀