Skip to content
environment-setup-guide logo

Environment Setup Guide

environment-setup-guide

Guide developers through setting up development environments with proper tools, dependencies, and configurations

SKILL.md

Full skill instructions

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 [email protected]
\`\`\`

**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


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!

More skills from Dicklesworthstone

exa-policy-guardrails logo
Dicklesworthstone/pi_agent_rust

exa-policy-guardrails

Implement Exa lint rules, policy enforcement, and automated guardrails. Use when setting up code quality rules for Exa integrations, implementing pre-commit hooks, or configuring CI policy checks for Exa best practices. Trigger with phrases like "exa policy", "exa lint", "exa guardrails", "exa be...

1.8K 0
View
documenso-ci-integration logo
Dicklesworthstone/pi_agent_rust

documenso-ci-integration

Configure CI/CD pipelines for Documenso integrations. Use when setting up automated testing, deployment pipelines, or continuous integration for Documenso projects. Trigger with phrases like "documenso CI", "documenso GitHub Actions", "documenso pipeline", "documenso automated testing".

1.8K 0
View
openrouter-model-availability logo
Dicklesworthstone/pi_agent_rust

openrouter-model-availability

Build check model availability and implement fallback chains. Use when building resilient systems or handling model outages. Trigger with phrases like 'openrouter availability', 'openrouter fallback', 'openrouter model down', 'openrouter health check'.

1.8K 0
View
langfuse-enterprise-rbac logo
Dicklesworthstone/pi_agent_rust

langfuse-enterprise-rbac

Configure Langfuse enterprise organization management and access control. Use when implementing team access controls, configuring organization settings, or setting up role-based permissions for Langfuse projects. Trigger with phrases like "langfuse RBAC", "langfuse teams", "langfuse organization"...

1.8K 0
View
cursor-compliance-audit logo
Dicklesworthstone/pi_agent_rust

cursor-compliance-audit

Execute compliance and security auditing for Cursor usage. Triggers on "cursor compliance", "cursor audit", "cursor security review", "cursor soc2", "cursor gdpr". Use when analyzing or auditing cursor compliance audit. Trigger with phrases like "cursor compliance audit", "cursor audit", "cursor".

1.8K 0
View
apollo-ci-integration logo
Dicklesworthstone/pi_agent_rust

apollo-ci-integration

Configure Apollo.io CI/CD integration. Use when setting up automated testing, continuous integration, or deployment pipelines for Apollo integrations. Trigger with phrases like "apollo ci", "apollo github actions", "apollo pipeline", "apollo ci/cd", "apollo automated tests".

1.8K 0
View
python-script logo
Dicklesworthstone/pi_agent_rust

python-script

Create robust Python automation with full logging and safety checks. Use when tasks need complex data processing, authenticated API work, conditional file operations, or error handling beyond simple shell commands.

1.8K 0
View
posthog-multi-env-setup logo
Dicklesworthstone/pi_agent_rust

posthog-multi-env-setup

Configure PostHog across development, staging, and production environments. Use when setting up multi-environment deployments, configuring per-environment secrets, or implementing environment-specific PostHog configurations. Trigger with phrases like "posthog environments", "posthog staging", "po...

1.8K 0
View
ai-agents-architect logo
Dicklesworthstone/pi_agent_rust

ai-agents-architect

Expert in designing and building autonomous AI agents. Masters tool use, memory systems, planning strategies, and multi-agent orchestration. Use when: build agent, AI agent, autonomous agent, tool use, function calling.

1.8K 0
View
insecure-deserialization-checker logo
Dicklesworthstone/pi_agent_rust

insecure-deserialization-checker

Validate insecure deserialization checker operations. Auto-activating skill for Security Fundamentals. Triggers on: insecure deserialization checker, insecure deserialization checker Part of the Security Fundamentals skill category. Use when working with insecure deserialization checker functiona...

1.8K 0
View
path-traversal-finder logo
Dicklesworthstone/pi_agent_rust

path-traversal-finder

Manage path traversal finder operations. Auto-activating skill for Security Fundamentals. Triggers on: path traversal finder, path traversal finder Part of the Security Fundamentals skill category. Use when working with path traversal finder functionality. Trigger with phrases like "path traversa...

1.8K 0
View
scientific-critical-thinking logo
Dicklesworthstone/pi_agent_rust

scientific-critical-thinking

Evaluate research rigor. Assess methodology, experimental design, statistical validity, biases, confounding, evidence quality (GRADE, Cochrane ROB), for critical analysis of scientific claims.

1.8K 0
View

Popular AI tools

Kaiber logo
Video

Kaiber

Generate, edit, and beat-sync AI video with leading models in one workspace.

Paid
View
Vimcal logo
Productivity

Vimcal

The world's fastest calendar for remote work

Free
View

Transform Your Design with AI Designer by ImgCreator.ai

Freemium
View
Akool AI logo
Content & writing

Akool AI

Revolutionizing Video Production with AI-Powered Creativity

Paid
View

Extend an image past the frame and let AI fill the new aspect ratio.

Freemium
View
StarByFace logo
Security

StarByFace

Discover your celebrity doppelgänger with StarByFace!

Free
View
C

ChainClarity explains 700+ crypto whitepapers in plain English, with layered summaries, comparisons, research tools, alerts, and a $4.99 Pro plan.

Freemium
View
Opus Clip logo
Coding & apps

Opus Clip

Opus.ai: Revolutionize Your Web Experience

Free
View