WSL Full-Stack Deployment and Troubleshooting Guide

WSL Practical Guide: Deploying Full-Stack Apps and Troubleshooting

This guide walks you through deploying a complete full-stack application in WSL (Windows Subsystem for Linux) and building your personal troubleshooting knowledge base. Following a hands-on project approach will help consolidate WSL skills and best practices.

🛠️ I. Hands-On Project: Full-Stack Technical Blog

#

Goal: Build a technical blog backend and frontend environment using WSL.

1️⃣ Step 1: Create Project Structure

#

Tip: Always create projects inside the Linux file system (e.g., ~/projects) for better performance and compatibility with WSL filesystem calls.

# Create directories
mkdir -p ~/projects/blog-app/{app,tests,static,templates}
cd ~/projects/blog-app

# Set up Python virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install backend dependencies
pip install fastapi uvicorn sqlalchemy psycopg2-binary redis pydantic python-multipart

# Freeze requirements
pip freeze > requirements.txt

2️⃣ Step 2: Configure the Database (PostgreSQL)

#

Install PostgreSQL in WSL:

sudo apt update
sudo apt install postgresql postgresql-contrib -y
sudo service postgresql start

Create a database and user:

sudo -u postgres createuser blog_user -P
sudo -u postgres createdb blog_db -O blog_user

Verify the connection:

psql -U blog_user -d blog_db -h localhost

3️⃣ Step 3: Redis Setup for Caching

#

Install Redis in WSL:

sudo apt install redis-server -y
sudo service redis-server start

Test the Redis server:

redis-cli ping
# Should return PONG

Integrate caching into FastAPI using aioredis or redis-py.

4️⃣ Step 4: Backend Development with FastAPI

#

Create a minimal app/main.py:

from fastapi import FastAPI
app = FastAPI()

@app.get("/")
async def root():
    return {"message": "Hello, WSL Full-Stack!"}

Run the server:

uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Test in the browser at http://localhost:8000.

5️⃣ Step 5: Frontend Setup (Optional Vue 3 + Vite)

#

npm create vite@latest frontend -- --template vue
cd frontend
npm install
npm run dev

You can configure the frontend to communicate with the FastAPI backend on port 8000.

6️⃣ Step 6: Containerization with Docker Compose

#

Install Docker Desktop (WSL2 backend enabled) and create docker-compose.yml:

version: '3.9'
services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_USER: blog_user
      POSTGRES_PASSWORD: password
      POSTGRES_DB: blog_db
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data

  redis:
    image: redis:7
    ports:
      - "6379:6379"

volumes:
  pgdata:

Launch services:

docker-compose up -d

7️⃣ Step 7: Troubleshooting Tips

#

Common WSL Issues:

1. Slow filesystem performance: Ensure projects are on the Linux filesystem (~/) instead of /mnt/c/.
2. Port conflicts: Use netstat -tulnp or lsof -i :PORT to check active ports.
3. Docker networking: WSL2 requires the backend integration; check docker info for WSL2 context.
4. Environment isolation: Always activate your .venv before running Python scripts.
5. Service startup: sudo service postgresql start and sudo service redis-server start for manual launches.

✅ Summary

#

This WSL guide combines practical full-stack deployment steps with essential troubleshooting knowledge. By completing the project, you will gain:

• FastAPI backend and PostgreSQL integration
• Redis caching in WSL
• Frontend connection using Vue 3 / Vite
• Docker Compose orchestration
• Effective troubleshooting workflows in WSL2

Building a personal knowledge base during this process ensures faster resolution of future issues and a deeper understanding of Windows + Linux interoperability.