Environment Setup Guide

Overview

Help developers set up complete development environments from scratch. This skill provides step-by-step guidance for installing tools, configuring dependencies, setting up environment variables, and verifying the setup works correctly.

When to Use This Skill

• Use when starting a new project and need to set up the development environment

• Use when onboarding new team members to a project

• Use when switching to a new machine or operating system

• Use when troubleshooting environment-related issues

• Use when documenting setup instructions for a project

• Use when creating development environment documentation

How It Works

Step 1: Identify Requirements

I'll help you determine what needs to be installed:

• Programming language and version (Node.js, Python, Go, etc.)

• Package managers (npm, pip, cargo, etc.)

• Database systems (PostgreSQL, MongoDB, Redis, etc.)

• Development tools (Git, Docker, IDE extensions, etc.)

• Environment variables and configuration files

Step 2: Check Current Setup

Before installing anything, I'll help you check what's already installed:

Check versions of installed tools

node --version python --version git --version docker --version

Step 3: Provide Installation Instructions

I'll give platform-specific installation commands:

• macOS: Using Homebrew

• Linux: Using apt, yum, or package manager

• Windows: Using Chocolatey, Scoop, or direct installers

Step 4: Configure the Environment

Help set up:

• Environment variables (.env files)

• Configuration files (.gitconfig, .npmrc, etc.)

• IDE settings (VS Code, IntelliJ, etc.)

• Shell configuration (.bashrc, .zshrc, etc.)

Step 5: Verify Installation

Provide verification steps to ensure everything works:

• Run version checks

• Test basic commands

• Verify database connections

• Check environment variables are loaded

Examples

Example 1: Node.js Project Setup

Setting Up Node.js Development Environment

Prerequisites

• macOS, Linux, or Windows
• Terminal/Command Prompt access
• Internet connection

Step 1: Install Node.js

macOS (using Homebrew): ```bash

Install Homebrew if not installed

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Install Node.js

brew install node ```

Linux (Ubuntu/Debian): ```bash

Update package list

sudo apt update

Install Node.js and npm

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejs ```

Windows (using Chocolatey): ```powershell

Install Chocolatey if not installed

Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

Install Node.js

choco install nodejs ```

Step 2: Verify Installation

```bash node --version # Should show v20.x.x or higher npm --version # Should show 10.x.x or higher ```

Step 3: Install Project Dependencies

```bash

Clone the repository

git clone https://github.com/your-repo/project.git cd project

Install dependencies

npm install ```

Step 4: Set Up Environment Variables

Create a `.env` file: ```bash

Copy example environment file

cp .env.example .env

Edit with your values

nano .env ```

Example `.env` content: ``` NODE_ENV=development PORT=3000 DATABASE_URL=postgresql://localhost:5432/mydb API_KEY=your-api-key-here ```

Step 5: Run the Project

```bash

Start development server

npm run dev

Should see: Server running on http://localhost:3000

```

Troubleshooting

Problem: "node: command not found" Solution: Restart your terminal or run `source ~/.bashrc` (Linux) or `source ~/.zshrc` (macOS)

Problem: "Permission denied" errors Solution: Don't use sudo with npm. Fix permissions: ```bash mkdir /.npm-global npm config set prefix '/.npm-global' echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc source ~/.bashrc ```

Example 2: Python Project Setup

Setting Up Python Development Environment

Step 1: Install Python

macOS: ```bash brew install python@3.11 ```

Linux: ```bash sudo apt update sudo apt install python3.11 python3.11-venv python3-pip ```

Windows: ```powershell choco install python --version=3.11 ```

Step 2: Verify Installation

```bash python3 --version # Should show Python 3.11.x pip3 --version # Should show pip 23.x.x ```

Step 3: Create Virtual Environment

```bash

Navigate to project directory

cd my-project

Create virtual environment

python3 -m venv venv

Activate virtual environment

macOS/Linux:

source venv/bin/activate

Windows:

venv\Scripts\activate ```

Step 4: Install Dependencies

```bash

Install from requirements.txt

pip install -r requirements.txt

Or install packages individually

pip install flask sqlalchemy python-dotenv ```

Step 5: Set Up Environment Variables

Create `.env` file: ``` FLASK_APP=app.py FLASK_ENV=development DATABASE_URL=sqlite:///app.db SECRET_KEY=your-secret-key-here ```

Step 6: Run the Application

```bash

Run Flask app

flask run

Should see: Running on http://127.0.0.1:5000

```

Example 3: Docker Development Environment

Setting Up Docker Development Environment

Step 1: Install Docker

macOS: ```bash brew install --cask docker

Or download Docker Desktop from docker.com

```

Linux: ```bash

Install Docker

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

Add user to docker group

sudo usermod -aG docker $USER newgrp docker ```

Windows: Download Docker Desktop from docker.com

Step 2: Verify Installation

```bash docker --version # Should show Docker version 24.x.x docker-compose --version # Should show Docker Compose version 2.x.x ```

Step 3: Create docker-compose.yml

```yaml version: '3.8'

services: app: build: . ports: - "3000:3000" environment: - NODE_ENV=development - DATABASE_URL=postgresql://postgres:password@db:5432/mydb volumes: - .:/app - /app/node_modules depends_on: - db

db: image: postgres:15 environment: - POSTGRES_USER=postgres - POSTGRES_PASSWORD=password - POSTGRES_DB=mydb ports: - "5432:5432" volumes: - postgres_data:/var/lib/postgresql/data

volumes: postgres_data: ```

Step 4: Start Services

```bash

Build and start containers

docker-compose up -d

View logs

docker-compose logs -f

Stop services

docker-compose down ```

Step 5: Verify Services

```bash

Check running containers

docker ps

Test database connection

docker-compose exec db psql -U postgres -d mydb ```

Best Practices

✅ Do This

• Document Everything - Write clear setup instructions

• Use Version Managers - nvm for Node, pyenv for Python

• Create .env.example - Show required environment variables

• Test on Clean System - Verify instructions work from scratch

• Include Troubleshooting - Document common issues and solutions

• Use Docker - For consistent environments across machines

• Pin Versions - Specify exact versions in package files

• Automate Setup - Create setup scripts when possible

• Check Prerequisites - List required tools before starting

• Provide Verification Steps - Help users confirm setup works

❌ Don't Do This

• Don't Assume Tools Installed - Always check and provide install instructions

• Don't Skip Environment Variables - Document all required variables

• Don't Use Sudo with npm - Fix permissions instead

• Don't Forget Platform Differences - Provide OS-specific instructions

• Don't Leave Out Verification - Always include test steps

• Don't Use Global Installs - Prefer local/virtual environments

• Don't Ignore Errors - Document how to handle common errors

• Don't Skip Database Setup - Include database initialization steps

Common Pitfalls

Problem: "Command not found" after installation

Symptoms: Installed tool but terminal doesn't recognize it Solution:

• Restart terminal or source shell config

• Check PATH environment variable

• Verify installation location

Check PATH

echo $PATH

Add to PATH (example)

export PATH="/usr/local/bin:$PATH"

Problem: Permission errors with npm/pip

Symptoms: "EACCES" or "Permission denied" errors Solution:

• Don't use sudo

• Fix npm permissions or use nvm

• Use virtual environments for Python

Fix npm permissions

mkdir /.npm-global npm config set prefix '/.npm-global' echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc

Problem: Port already in use

Symptoms: "Port 3000 is already in use" Solution:

• Find and kill process using the port

• Use a different port

Find process on port 3000

lsof -i :3000

Kill process

kill -9 <PID>

Or use different port

PORT=3001 npm start

Problem: Database connection fails

Symptoms: "Connection refused" or "Authentication failed" Solution:

• Verify database is running

• Check connection string

• Verify credentials

Check if PostgreSQL is running

sudo systemctl status postgresql

Test connection

psql -h localhost -U postgres -d mydb

Setup Script Template

Create a setup.sh script to automate setup:

#!/bin/bash

echo "🚀 Setting up development environment..."

Check prerequisites

command -v node >/dev/null 2>&1 || { echo "❌ Node.js not installed"; exit 1; } command -v git >/dev/null 2>&1 || { echo "❌ Git not installed"; exit 1; }

echo "✅ Prerequisites check passed"

Install dependencies

echo "📦 Installing dependencies..." npm install

Copy environment file

if [ ! -f .env ]; then echo "📝 Creating .env file..." cp .env.example .env echo "⚠️ Please edit .env with your configuration" fi

Run database migrations

echo "🗄️ Running database migrations..." npm run migrate

Verify setup

echo "🔍 Verifying setup..." npm run test:setup

echo "✅ Setup complete! Run 'npm run dev' to start"

Related Skills

• @brainstorming

• Plan environment requirements before setup

• @systematic-debugging

• Debug environment issues

• @doc-coauthoring

• Create setup documentation

• @git-pushing

• Set up Git configuration

Additional Resources

• Node.js Installation Guide

• Python Virtual Environments

• Docker Documentation

• Homebrew (macOS)

• Chocolatey (Windows)

• nvm (Node Version Manager)

• pyenv (Python Version Manager)

Pro Tip: Create a setup.sh or setup.ps1 script to automate the entire setup process. Test it on a clean system to ensure it works!