WDI Development Stack Setup Guide

Welcome to the WDI Development Stack setup guide! This repository contains everything you need to get started with WDI development infrastructure and request access to our projects.

📋 Table of Contents

1. Prerequisites
2. Environment Setup
3. GitHub Setup
4. Requesting Project Access
5. Development Workflow
6. Troubleshooting

Prerequisites

Before you begin, ensure you have the following installed:

Required Software

• Node.js (v20.11.1 or later) - Download
• pnpm (v8.15.4 or later) - Install via npm: npm install -g pnpm@8.15.4
• Docker Desktop - Download
• Git (v2.30 or later) - Download

Optional (Recommended)

• Volta - Node.js version manager - Install
• VS Code - Our recommended IDE - Download

Environment Setup

1. Install Node.js and pnpm

Option A: Using Volta (Recommended)

# Install Volta
curl https://get.volta.sh | bash

# Install Node.js and pnpm
volta install node@20.11.1
volta install pnpm@8.15.4

# Verify installations
node --version  # Should show v20.11.1
pnpm --version  # Should show 8.15.4

Option B: Manual Installation

# Install Node.js from nodejs.org, then:
npm install -g pnpm@8.15.4

2. Install Docker Desktop

1. Download Docker Desktop from docker.com
2. Install and start Docker Desktop
3. Verify installation:

   docker --version
   docker-compose --version

3. Verify Your Setup

Run these commands to verify everything is installed correctly:

node --version    # Should be >= 20.11.1
pnpm --version    # Should be >= 8.15.4
docker --version  # Should show Docker version
git --version     # Should be >= 2.30

GitHub Setup

1. Create a GitHub Account

If you don't have one, create an account at github.com

2. Set Up SSH Keys

SSH keys allow you to securely connect to GitHub without entering your password each time.

Generate SSH Key

# Generate a new SSH key (replace with your email)
ssh-keygen -t ed25519 -C "your_email@example.com"

# Press Enter to accept default file location
# Optionally set a passphrase for extra security

Add SSH Key to GitHub

1. Copy your public key:

   cat ~/.ssh/id_ed25519.pub

2. Go to GitHub Settings:

   • Visit https://github.com/settings/keys
   • Click "New SSH key"
   • Paste your key
   • Give it a descriptive title (e.g., "MacBook Pro")
   • Click "Add SSH key"

Test SSH Connection

ssh -T git@github.com
# You should see: "Hi [username]! You've successfully authenticated..."

3. Configure Git

Set up your Git identity:

git config --global user.name "Your Name"
git config --global user.email "your_email@example.com"

4. Set Up GitHub CLI (Optional but Recommended)

The GitHub CLI (gh) makes managing repositories easier:

# macOS
brew install gh

# Or download from: https://cli.github.com/

# Authenticate
gh auth login

Requesting Project Access

Once your environment is set up, you can request access to WDI projects.

How to Request Access

1. Contact the Project Administrator

   • Send an email to the project lead or administrator
   • Include your GitHub username
   • Specify which project(s) you need access to

2. Wait for Invitation

   • You'll receive a GitHub invitation via email
   • Accept the invitation from the email or GitHub notifications

3. Clone the Repository

   # Once invited, clone the repository
   git clone git@github.com:WDIMcKenzie/[project-name].git
   cd [project-name]

Available Projects

Access to specific projects is granted by invitation. Contact your project administrator for details.

Development Workflow

Initial Project Setup

Once you have access to a project repository:

# Clone the repository
git clone git@github.com:WDIMcKenzie/[project-name].git
cd [project-name]

# Install dependencies
pnpm install

# Start development server
pnpm dev

Working with Projects

1. Create a Feature Branch

   git checkout -b feature/your-feature-name

2. Make Your Changes

   • Write code
   • Test locally
   • Commit changes

3. Push and Create Pull Request

   git push origin feature/your-feature-name
   # Then create PR on GitHub

Git Workflow Best Practices

• Always work in feature branches, never directly on main or develop
• Write clear, descriptive commit messages
• Keep branches focused on a single feature or fix
• Test your changes before submitting PRs

See Development Workflow Guide for detailed guidelines.

Project Structure

When you clone a WDI project, you'll typically see:

project-name/
├── apps/           # Frontend applications
├── services/       # Backend services/APIs
├── packages/       # Shared packages
├── docker-compose.yml  # Docker configuration
├── package.json    # Root package.json
└── README.md       # Project-specific documentation

Troubleshooting

Common Issues

"Command not found" errors

Problem: Node.js or pnpm not found in PATH

Solution:

# Verify installations
which node
which pnpm

# If missing, reinstall or add to PATH
export PATH="$PATH:$(pnpm bin)"

Docker won't start

Problem: Docker Desktop not running or permissions issue

Solution:

• Ensure Docker Desktop is running
• On macOS/Linux, you may need to add your user to the docker group:

  sudo usermod -aG docker $USER
  # Log out and back in

SSH Key Authentication Fails

Problem: "Permission denied (publickey)" when cloning

Solution:

# Test SSH connection
ssh -T git@github.com

# If it fails, verify your SSH key is added to GitHub
cat ~/.ssh/id_ed25519.pub
# Copy and add to GitHub Settings > SSH Keys

pnpm Install Fails

Problem: Dependency installation errors

Solution:

# Clear pnpm cache
pnpm store prune

# Try installing again
rm -rf node_modules pnpm-lock.yaml
pnpm install

Getting Help

If you encounter issues not covered here:

1. Check the project-specific README
2. Review the Detailed Guides
3. Contact your project administrator
4. Check GitHub Issues in the project repository

Additional Resources

• Environment Setup Guide - Detailed environment setup
• GitHub Setup Guide - Comprehensive GitHub configuration
• SSH Keys Guide - SSH key management
• Development Workflow - Development best practices
• Requesting Access - How to get project access

License

This setup guide is provided as-is for developers working with WDI projects.

---

Questions? Contact your project administrator or refer to the detailed guides in the docs/ directory.