Platfone Docs

Windows Subsystem for Linux (WSL) Guide

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:

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

sudo apt update && sudo apt upgrade -y

4. Install Required Tools

Docker (if using Docker Compose):

# 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:

# 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)

# 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/:

# 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:

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:

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

wsl.exe -d Ubuntu

Editing Files

Option A: VS Code with WSL Extension

# 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

nano config/env/backend.env

Copy Files Between Windows and WSL

From Windows to WSL:

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

From WSL to Windows:

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

Checking Docker

# 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

# 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:

# 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:

# 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:

# 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

💡 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
Prev
Google Cloud Deployment