Skip to content

development-setup.md

Latest commit

 

History

History
460 lines (343 loc) · 9.15 KB

development-setup.md

File metadata and controls

460 lines (343 loc) · 9.15 KB
Raw

Development Setup Guide

This guide covers how to set up your local development environment for contributing to Coffee Code Philly projects.

Table of Contents

  1. General Prerequisites
  2. Git Configuration
  3. Python Projects
  4. Node.js Projects
  5. Docker Projects
  6. IDE Configuration
  7. Troubleshooting

General Prerequisites

Required Tools

  1. Git (version control)

    # macOS (using Homebrew)
brew install git

# Ubuntu/Debian
sudo apt-get install git

# Windows
# Download from https://git-scm.com/download/win

  2. GitHub Account

  3. Code Editor

Git Configuration

Basic Configuration

# Set your name and email
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# Set default branch name
git config --global init.defaultBranch main

# Enable color output
git config --global color.ui auto

# Set default editor (optional)
git config --global core.editor "code --wait"  # VS Code
# or
git config --global core.editor "vim"  # Vim

Recommended Aliases

# Useful shortcuts
git config --global alias.st status
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.ci commit
git config --global alias.unstage 'reset HEAD --'
git config --global alias.last 'log -1 HEAD'
git config --global alias.lg "log --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

SSH Keys (Recommended)

# Generate SSH key
ssh-keygen -t ed25519 -C "your.email@example.com"

# Start ssh-agent
eval "$(ssh-agent -s)"

# Add your key
ssh-add ~/.ssh/id_ed25519

# Copy public key to clipboard (macOS)
pbcopy < ~/.ssh/id_ed25519.pub

# Then add to GitHub: Settings → SSH and GPG keys → New SSH key

Python Projects

Install Python

macOS:

# Using Homebrew
brew install python@3.11

# Verify installation
python3 --version

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install python3.11 python3.11-venv python3-pip

Windows:

  • Download from python.org
  • Make sure to check "Add Python to PATH" during installation

Project Setup

  1. Clone the repository:

    git clone https://github.com/YOUR-USERNAME/REPO-NAME.git
cd REPO-NAME

  2. Create virtual environment:

    python3 -m venv venv

  3. Activate virtual environment:

    # macOS/Linux
source venv/bin/activate

# Windows
venv\Scripts\activate

# You should see (venv) in your prompt

  4. Install dependencies:

    # Development dependencies (includes testing tools, linters, etc.)
pip install -r requirements-dev.txt

# Or just production dependencies
pip install -r requirements.txt

# Or if using setup.py
pip install -e ".[dev]"

  5. Verify installation:

    # Run tests
pytest

# Check linting
ruff check .

# Check formatting
black --check .

# Type checking
mypy .

Python Tools

Install recommended development tools:

pip install black ruff mypy pytest pytest-cov
  • black: Code formatter
  • ruff: Fast linter (replaces flake8, isort, etc.)
  • mypy: Static type checker
  • pytest: Testing framework
  • pytest-cov: Coverage reporting

Node.js Projects

Install Node.js

macOS:

# Using Homebrew
brew install node

# Or using nvm (recommended for managing multiple versions)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 20
nvm use 20

Ubuntu/Debian:

# Using NodeSource repository
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

Windows:

Project Setup

  1. Clone the repository:

    git clone https://github.com/YOUR-USERNAME/REPO-NAME.git
cd REPO-NAME

  2. Install dependencies:

    npm install
# or
npm ci  # For clean install from package-lock.json

  3. Verify installation:

    # Run tests
npm test

# Run linter
npm run lint

# Check formatting
npm run format:check

# Type check (if TypeScript)
npm run type-check

# Start development server
npm run dev

Node.js Tools

Recommended global tools:

npm install -g typescript eslint prettier

Docker Projects

Install Docker

macOS/Windows:

Ubuntu/Debian:

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Add your user to docker group
sudo usermod -aG docker $USER

# Log out and back in for changes to take effect

Project Setup

  1. Build images:

    docker-compose build

  2. Start services:

    docker-compose up
# or in detached mode
docker-compose up -d

  3. Run commands in container:

    docker-compose exec web python manage.py migrate
docker-compose exec web pytest

  4. View logs:

    docker-compose logs -f

  5. Stop services:

    docker-compose down

IDE Configuration

VS Code

Recommended Extensions:

{
  "recommendations": [
    "ms-python.python",
    "ms-python.vscode-pylance",
    "charliermarsh.ruff",
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode",
    "eamodio.gitlens",
    "ms-azuretools.vscode-docker"
  ]
}

Settings (.vscode/settings.json):

{
  "editor.formatOnSave": true,
  "editor.rulers": [88, 120],
  "python.linting.enabled": true,
  "python.linting.ruffEnabled": true,
  "python.formatting.provider": "black",
  "python.testing.pytestEnabled": true,
  "eslint.validate": ["javascript", "typescript"],
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  }
}

PyCharm

  1. Set Python interpreter: File → Settings → Project → Python Interpreter
  2. Enable black: Settings → Tools → Black
  3. Configure pytest: Settings → Tools → Python Integrated Tools → Testing → pytest
  4. Enable mypy: Install Mypy plugin

Troubleshooting

Git Issues

Problem: Authentication failed

# Solution: Use SSH instead of HTTPS
git remote set-url origin git@github.com:USERNAME/REPO-NAME.git

Problem: Permission denied (publickey)

# Solution: Check SSH key
ssh -T git@github.com
# If fails, follow SSH setup instructions above

Python Issues

Problem: command not found: python

# Use python3 explicitly or create alias
echo "alias python=python3" >> ~/.bashrc
source ~/.bashrc

Problem: pip install fails with permissions error

# Don't use sudo! Use virtual environment instead
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Problem: Import errors

# Make sure you're in virtual environment
which python  # Should point to venv/bin/python

# Reinstall dependencies
pip install -r requirements.txt

Node.js Issues

Problem: npm install fails

# Clear cache and try again
npm cache clean --force
rm -rf node_modules package-lock.json
npm install

Problem: EACCES permission errors

# Don't use sudo! Fix npm permissions
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Docker Issues

Problem: Permission denied

# Add user to docker group (Linux)
sudo usermod -aG docker $USER
# Log out and back in

Problem: Port already in use

# Find and kill process using port
lsof -ti:8000 | xargs kill -9

# Or change port in docker-compose.yml

Getting Help

If you're stuck:

  1. Check repository README: Project-specific instructions
  2. Search existing issues: Someone may have had the same problem
  3. Ask in community chat: Discord/Slack (see SUPPORT.md)
  4. Create a discussion: GitHub Discussions
  5. Email us: coffeecodephl@gmail.com

Next Steps

Once your environment is set up:

  1. Read Getting Started
  2. Find an issue to work on
  3. Review Contributing Guidelines
  4. Make your first contribution!

Happy coding! ☕️