# Windows WSL Guide

> Windows-specific guide for using WSL to run Temp-Number deployment scripts and Linux-based tooling.


This guide helps Windows users run the deployment scripts using Windows Subsystem for Linux (WSL).

---

## 🪟 Why WSL?

The deployment scripts are written in bash for Linux/macOS. WSL allows you to run them natively on Windows without rewriting everything in PowerShell.

---

## 📋 Prerequisites

- Windows 10 version 2004+ or Windows 11
- Administrator access

---

## 🚀 Setup Steps

### 1. Install WSL

Open **PowerShell as Administrator** and run:

```powershell
wsl --install
```

This installs:

- WSL 2
- Ubuntu (default Linux distribution)

**Restart your computer** when prompted.

### 2. Set Up Ubuntu

After restart, Ubuntu will open automatically:

1. Create a username (lowercase, no spaces)
2. Create a password (you won't see it as you type)
3. Wait for setup to complete

### 3. Update Ubuntu

```bash
sudo apt update && sudo apt upgrade -y
```

### 4. Install Required Tools

**Docker (if using Docker Compose):**

```bash
# Install Docker Desktop for Windows with WSL 2 backend
# Download from: https://www.docker.com/products/docker-desktop
# Enable WSL 2 integration in Docker Desktop settings
```

⚠️ **Important:** Make sure to install Docker Desktop with WSL 2 backend, not the Linux Docker package inside WSL.

**Google Cloud SDK:**

```bash
# Add Cloud SDK repository
echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" | sudo tee -a /etc/apt/sources.list.d/google-cloud-sdk.list

# Install dependencies
sudo apt-get install -y apt-transport-https ca-certificates gnupg

# Add Google Cloud public key
curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key --keyring /usr/share/keyrings/cloud.google.gpg add -

# Install gcloud CLI
sudo apt-get update && sudo apt-get install -y google-cloud-cli

# Verify installation
gcloud version

# Authenticate
gcloud auth login

# If browser doesn't open automatically, copy printed URL and open it in your browser manually
# or run:
# gcloud auth login --no-launch-browser
```

⚠️ **Important:** Make sure to install Google Cloud SDK inside WSL, not on Windows. Use `gcloud` version for **Linux 64-bit**, if installing manually.

### 5. Access Your Project Files

**Option A: Store project in WSL filesystem (Recommended)**

```bash
# Navigate to your home directory
cd ~

# Clone or copy your project here
git clone <your-repo-url>
cd temp-number-deploy
```

**Option B: Access Windows filesystem from WSL**

Your Windows drives are mounted at `/mnt/`:

```bash
# Access C:\Users\YourName\Projects\temp-number-deploy
cd /mnt/c/Users/YourName/Projects/temp-number-deploy
```

⚠️ **Performance note:** Storing files in WSL filesystem (`~/`) is faster than accessing Windows filesystem (`/mnt/c/`).

---

## 🎯 Using the Deployment Scripts

In powershell, open Ubuntu (WSL) and navigate to your project directory:

```shell
wsl.exe -d Ubuntu
cd ~/temp-number-deploy # Navigate to your project directory
./setup-wizard.sh
```

⚠️ **Fix script permissions :** Make sure your scripts are executable:

```bash
cd ~/temp-number-deploy
find . -name "*.sh" -type f -exec chmod +x {} \;
```

---

## 🔧 Common Tasks

### Opening WSL

**Method 1: Windows Terminal (Recommended)**

- Install from Microsoft Store
- Open and select "Ubuntu" tab

**Method 2: Ubuntu App**

- Search "Ubuntu" in Start Menu

**Method 3: From Command Prompt/PowerShell**

```cmd
wsl.exe -d Ubuntu
```

### Editing Files

**Option A: VS Code with WSL Extension**

```bash
# From WSL, open VS Code in current directory
code .
```

**Option B: Windows text editors**

- Use Windows Explorer to navigate to `\\wsl$\Ubuntu\home\yourusername\`
- Edit files with any Windows editor

**Option C: Linux text editor**

```bash
nano config/env/backend.env
```

### Copy Files Between Windows and WSL

**From Windows to WSL:**

```bash
# In WSL terminal
cp /mnt/c/Users/YourName/Downloads/firebase-key.json ~/temp-number-deploy/config/secrets/
```

**From WSL to Windows:**

```bash
# In WSL terminal
cp ~/temp-number-deploy/logs/deployment.log /mnt/c/Users/YourName/Documents/
```

### Checking Docker

```bash
# Verify Docker is accessible from WSL
docker --version
docker ps
```

If Docker isn't found:

1. Make sure Docker Desktop is running on Windows
2. Open Docker Desktop → Settings → Resources → WSL Integration
3. Enable integration with your Ubuntu distribution

---

## 🐛 Troubleshooting

### "Permission denied" when running scripts

```bash
# Make scripts executable
find . -name "*.sh" -type f -exec chmod +x {} \;
```

### Line ending issues (CRLF vs LF)

If you cloned on Windows, scripts may have Windows line endings:

```bash
# Install dos2unix
sudo apt install dos2unix -y

# Convert all shell scripts
find . -name "*.sh" -type f -exec dos2unix {} \;
```

Or configure git to handle line endings:

```bash
# In your project directory
git config core.autocrlf input
git rm --cached -r .
git reset --hard
```

### WSL is slow

- Store project files in WSL filesystem (`~/`), not Windows filesystem (`/mnt/c/`)
- Use WSL 2 (not WSL 1): `wsl --set-version Ubuntu 2`

### Can't access localhost from Windows browser

If you start services in WSL but can't access them from Windows:

```bash
# Check if port is listening
netstat -tuln | grep 8080

# Make sure services bind to 0.0.0.0, not 127.0.0.1
```

WSL 2 should automatically forward ports to Windows. If not working:

- Restart WSL: `wsl --shutdown` (in PowerShell), then reopen Ubuntu
- Update Windows to latest version

---

## 📚 Additional Resources

- [WSL Documentation](https://docs.microsoft.com/en-us/windows/wsl/)

- [Docker Desktop WSL 2 Backend](https://docs.docker.com/desktop/windows/wsl/)

- [VS Code with WSL](https://code.visualstudio.com/docs/remote/wsl)

- [Google Cloud SDK Installation](https://cloud.google.com/sdk/docs/install)


---

## 💡 Pro Tips

1. **Use Windows Terminal** - Better experience than default Ubuntu terminal
2. **Install VS Code Remote - WSL extension** - Edit files seamlessly
3. **Use `explorer.exe .`** - Open current WSL directory in Windows Explorer
4. **Use `code .`** - Open current directory in VS Code
5. **Bookmark `\\wsl$\Ubuntu`** - Quick access to WSL files from Windows

---

## 🆘 Need Help?

If you encounter issues:

1. Check this troubleshooting section
2. Search WSL documentation
3. Open an issue in the repository with your error message
4. Contact support at <support@platfone.com>