Environment Setup Guide

1---
2name: environment-setup-guide
3description: "Guide developers through setting up development environments with proper tools, dependencies, and configurations"
4---
5 
6# Environment Setup Guide
7 
8## Overview
9 
10Help 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.
11 
12## When to Use This Skill
13 
14- Use when starting a new project and need to set up the development environment
15- Use when onboarding new team members to a project
16- Use when switching to a new machine or operating system
17- Use when troubleshooting environment-related issues
18- Use when documenting setup instructions for a project
19- Use when creating development environment documentation
20 
21## How It Works
22 
23### Step 1: Identify Requirements
24 
25I'll help you determine what needs to be installed:
26- Programming language and version (Node.js, Python, Go, etc.)
27- Package managers (npm, pip, cargo, etc.)
28- Database systems (PostgreSQL, MongoDB, Redis, etc.)
29- Development tools (Git, Docker, IDE extensions, etc.)
30- Environment variables and configuration files
31 
32### Step 2: Check Current Setup
33 
34Before installing anything, I'll help you check what's already installed:
35```bash
36# Check versions of installed tools
37node --version
38python --version
39git --version
40docker --version
41```
42 
43### Step 3: Provide Installation Instructions
44 
45I'll give platform-specific installation commands:
46- **macOS:** Using Homebrew
47- **Linux:** Using apt, yum, or package manager
48- **Windows:** Using Chocolatey, Scoop, or direct installers
49 
50### Step 4: Configure the Environment
51 
52Help set up:
53- Environment variables (.env files)
54- Configuration files (.gitconfig, .npmrc, etc.)
55- IDE settings (VS Code, IntelliJ, etc.)
56- Shell configuration (.bashrc, .zshrc, etc.)
57 
58### Step 5: Verify Installation
59 
60Provide verification steps to ensure everything works:
61- Run version checks
62- Test basic commands
63- Verify database connections
64- Check environment variables are loaded
65 
66## Examples
67 
68### Example 1: Node.js Project Setup
69 
70```markdown
71## Setting Up Node.js Development Environment
72 
73### Prerequisites
74- macOS, Linux, or Windows
75- Terminal/Command Prompt access
76- Internet connection
77 
78### Step 1: Install Node.js
79 
80**macOS (using Homebrew):**
81\`\`\`bash
82# Install Homebrew if not installed
83/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
84 
85# Install Node.js
86brew install node
87\`\`\`
88 
89**Linux (Ubuntu/Debian):**
90\`\`\`bash
91# Update package list
92sudo apt update
93 
94# Install Node.js and npm
95curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
96sudo apt install -y nodejs
97\`\`\`
98 
99**Windows (using Chocolatey):**
100\`\`\`powershell
101# Install Chocolatey if not installed
102Set-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'))
103 
104# Install Node.js
105choco install nodejs
106\`\`\`
107 
108### Step 2: Verify Installation
109 
110\`\`\`bash
111node --version  # Should show v20.x.x or higher
112npm --version   # Should show 10.x.x or higher
113\`\`\`
114 
115### Step 3: Install Project Dependencies
116 
117\`\`\`bash
118# Clone the repository
119git clone https://github.com/your-repo/project.git
120cd project
121 
122# Install dependencies
123npm install
124\`\`\`
125 
126### Step 4: Set Up Environment Variables
127 
128Create a \`.env\` file:
129\`\`\`bash
130# Copy example environment file
131cp .env.example .env
132 
133# Edit with your values
134nano .env
135\`\`\`
136 
137Example \`.env\` content:
138\`\`\`
139NODE_ENV=development
140PORT=3000
141DATABASE_URL=postgresql://localhost:5432/mydb
142API_KEY=your-api-key-here
143\`\`\`
144 
145### Step 5: Run the Project
146 
147\`\`\`bash
148# Start development server
149npm run dev
150 
151# Should see: Server running on http://localhost:3000
152\`\`\`
153 
154### Troubleshooting
155 
156**Problem:** "node: command not found"
157**Solution:** Restart your terminal or run \`source ~/.bashrc\` (Linux) or \`source ~/.zshrc\` (macOS)
158 
159**Problem:** "Permission denied" errors
160**Solution:** Don't use sudo with npm. Fix permissions:
161\`\`\`bash
162mkdir ~/.npm-global
163npm config set prefix '~/.npm-global'
164echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
165source ~/.bashrc
166\`\`\`
167```
168 
169### Example 2: Python Project Setup
170 
171```markdown
172## Setting Up Python Development Environment
173 
174### Step 1: Install Python
175 
176**macOS:**
177\`\`\`bash
178brew install python@3.11
179\`\`\`
180 
181**Linux:**
182\`\`\`bash
183sudo apt update
184sudo apt install python3.11 python3.11-venv python3-pip
185\`\`\`
186 
187**Windows:**
188\`\`\`powershell
189choco install python --version=3.11
190\`\`\`
191 
192### Step 2: Verify Installation
193 
194\`\`\`bash
195python3 --version  # Should show Python 3.11.x
196pip3 --version     # Should show pip 23.x.x
197\`\`\`
198 
199### Step 3: Create Virtual Environment
200 
201\`\`\`bash
202# Navigate to project directory
203cd my-project
204 
205# Create virtual environment
206python3 -m venv venv
207 
208# Activate virtual environment
209# macOS/Linux:
210source venv/bin/activate
211 
212# Windows:
213venv\Scripts\activate
214\`\`\`
215 
216### Step 4: Install Dependencies
217 
218\`\`\`bash
219# Install from requirements.txt
220pip install -r requirements.txt
221 
222# Or install packages individually
223pip install flask sqlalchemy python-dotenv
224\`\`\`
225 
226### Step 5: Set Up Environment Variables
227 
228Create \`.env\` file:
229\`\`\`
230FLASK_APP=app.py
231FLASK_ENV=development
232DATABASE_URL=sqlite:///app.db
233SECRET_KEY=your-secret-key-here
234\`\`\`
235 
236### Step 6: Run the Application
237 
238\`\`\`bash
239# Run Flask app
240flask run
241 
242# Should see: Running on http://127.0.0.1:5000
243\`\`\`
244```
245 
246### Example 3: Docker Development Environment
247 
248```markdown
249## Setting Up Docker Development Environment
250 
251### Step 1: Install Docker
252 
253**macOS:**
254\`\`\`bash
255brew install --cask docker
256# Or download Docker Desktop from docker.com
257\`\`\`
258 
259**Linux:**
260\`\`\`bash
261# Install Docker
262curl -fsSL https://get.docker.com -o get-docker.sh
263sudo sh get-docker.sh
264 
265# Add user to docker group
266sudo usermod -aG docker $USER
267newgrp docker
268\`\`\`
269 
270**Windows:**
271Download Docker Desktop from docker.com
272 
273### Step 2: Verify Installation
274 
275\`\`\`bash
276docker --version        # Should show Docker version 24.x.x
277docker-compose --version # Should show Docker Compose version 2.x.x
278\`\`\`
279 
280### Step 3: Create docker-compose.yml
281 
282\`\`\`yaml
283version: '3.8'
284 
285services:
286  app:
287    build: .
288    ports:
289      - "3000:3000"
290    environment:
291      - NODE_ENV=development
292      - DATABASE_URL=postgresql://postgres:password@db:5432/mydb
293    volumes:
294      - .:/app
295      - /app/node_modules
296    depends_on:
297      - db
298 
299  db:
300    image: postgres:15
301    environment:
302      - POSTGRES_USER=postgres
303      - POSTGRES_PASSWORD=password
304      - POSTGRES_DB=mydb
305    ports:
306      - "5432:5432"
307    volumes:
308      - postgres_data:/var/lib/postgresql/data
309 
310volumes:
311  postgres_data:
312\`\`\`
313 
314### Step 4: Start Services
315 
316\`\`\`bash
317# Build and start containers
318docker-compose up -d
319 
320# View logs
321docker-compose logs -f
322 
323# Stop services
324docker-compose down
325\`\`\`
326 
327### Step 5: Verify Services
328 
329\`\`\`bash
330# Check running containers
331docker ps
332 
333# Test database connection
334docker-compose exec db psql -U postgres -d mydb
335\`\`\`
336```
337 
338## Best Practices
339 
340### ✅ Do This
341 
342- **Document Everything** - Write clear setup instructions
343- **Use Version Managers** - nvm for Node, pyenv for Python
344- **Create .env.example** - Show required environment variables
345- **Test on Clean System** - Verify instructions work from scratch
346- **Include Troubleshooting** - Document common issues and solutions
347- **Use Docker** - For consistent environments across machines
348- **Pin Versions** - Specify exact versions in package files
349- **Automate Setup** - Create setup scripts when possible
350- **Check Prerequisites** - List required tools before starting
351- **Provide Verification Steps** - Help users confirm setup works
352 
353### ❌ Don't Do This
354 
355- **Don't Assume Tools Installed** - Always check and provide install instructions
356- **Don't Skip Environment Variables** - Document all required variables
357- **Don't Use Sudo with npm** - Fix permissions instead
358- **Don't Forget Platform Differences** - Provide OS-specific instructions
359- **Don't Leave Out Verification** - Always include test steps
360- **Don't Use Global Installs** - Prefer local/virtual environments
361- **Don't Ignore Errors** - Document how to handle common errors
362- **Don't Skip Database Setup** - Include database initialization steps
363 
364## Common Pitfalls
365 
366### Problem: "Command not found" after installation
367**Symptoms:** Installed tool but terminal doesn't recognize it
368**Solution:**
369- Restart terminal or source shell config
370- Check PATH environment variable
371- Verify installation location
372```bash
373# Check PATH
374echo $PATH
375 
376# Add to PATH (example)
377export PATH="/usr/local/bin:$PATH"
378```
379 
380### Problem: Permission errors with npm/pip
381**Symptoms:** "EACCES" or "Permission denied" errors
382**Solution:**
383- Don't use sudo
384- Fix npm permissions or use nvm
385- Use virtual environments for Python
386```bash
387# Fix npm permissions
388mkdir ~/.npm-global
389npm config set prefix '~/.npm-global'
390echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
391```
392 
393### Problem: Port already in use
394**Symptoms:** "Port 3000 is already in use"
395**Solution:**
396- Find and kill process using the port
397- Use a different port
398```bash
399# Find process on port 3000
400lsof -i :3000
401 
402# Kill process
403kill -9 <PID>
404 
405# Or use different port
406PORT=3001 npm start
407```
408 
409### Problem: Database connection fails
410**Symptoms:** "Connection refused" or "Authentication failed"
411**Solution:**
412- Verify database is running
413- Check connection string
414- Verify credentials
415```bash
416# Check if PostgreSQL is running
417sudo systemctl status postgresql
418 
419# Test connection
420psql -h localhost -U postgres -d mydb
421```
422 
423## Setup Script Template
424 
425Create a `setup.sh` script to automate setup:
426 
427```bash
428#!/bin/bash
429 
430echo "🚀 Setting up development environment..."
431 
432# Check prerequisites
433command -v node >/dev/null 2>&1 || { echo "❌ Node.js not installed"; exit 1; }
434command -v git >/dev/null 2>&1 || { echo "❌ Git not installed"; exit 1; }
435 
436echo "✅ Prerequisites check passed"
437 
438# Install dependencies
439echo "📦 Installing dependencies..."
440npm install
441 
442# Copy environment file
443if [ ! -f .env ]; then
444    echo "📝 Creating .env file..."
445    cp .env.example .env
446    echo "⚠️  Please edit .env with your configuration"
447fi
448 
449# Run database migrations
450echo "🗄️  Running database migrations..."
451npm run migrate
452 
453# Verify setup
454echo "🔍 Verifying setup..."
455npm run test:setup
456 
457echo "✅ Setup complete! Run 'npm run dev' to start"
458```
459 
460## Related Skills
461 
462- `@brainstorming` - Plan environment requirements before setup
463- `@systematic-debugging` - Debug environment issues
464- `@doc-coauthoring` - Create setup documentation
465- `@git-pushing` - Set up Git configuration
466 
467## Additional Resources
468 
469- [Node.js Installation Guide](https://nodejs.org/en/download/)
470- [Python Virtual Environments](https://docs.python.org/3/tutorial/venv.html)
471- [Docker Documentation](https://docs.docker.com/get-started/)
472- [Homebrew (macOS)](https://brew.sh/)
473- [Chocolatey (Windows)](https://chocolatey.org/)
474- [nvm (Node Version Manager)](https://github.com/nvm-sh/nvm)
475- [pyenv (Python Version Manager)](https://github.com/pyenv/pyenv)
476 
477---
478 
479**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!
480