RepDev 🚀

Reproducible Development Environments Made Simple

A lightweight CLI tool that makes setting up development environments as easy as running a single command. No more "it works on my machine" - RepDev ensures consistent environments across your entire team using Docker containers with intelligent orchestration.

• 🎯 One Command Setup - repdev up starts your entire stack
• 📦 Pre-built Presets - MERN, Django, Next.js, and more
• 🎨 Interactive CLI - Guided setup with smart prompts
• 🔄 Lifecycle Hooks - Run scripts before/after container events
• ⏱️ Readiness Checks - Wait for services to be truly ready
• 🔐 Environment Files - Secure .env file support
• 🌐 Network Control - Host, bridge, and custom networks
• 🛠️ DX Commands - logs, exec, restart without leaving RepDev
• 🏥 Health Checks - repdev doctor diagnoses issues
• 📊 State Tracking - Know what's running and when

npm install -g repdev

# List available presets
repdev init --list

# Initialize with a preset (interactive prompts)
repdev init -p mern

# Start your environment
repdev up

# Check status
repdev status

# View logs
repdev logs backend -f

# Stop everything
repdev down

• Why RepDev?
• Installation
• Quick Start
• Available Presets
• CLI Commands
• Template Structure
• Advanced Features
• Customization
• Troubleshooting
• Contributing
• License

Setting up development environments is painful:

• ❌ Complex Docker Compose files
• ❌ Manual dependency installation
• ❌ Different environments across team members
• ❌ "Works on my machine" syndrome
• ❌ No standardized onboarding process

RepDev provides:

• ✅ Simple YAML templates
• ✅ Interactive setup wizards
• ✅ Consistent environments everywhere
• ✅ Automated health checks
• ✅ New developers productive in minutes

• Node.js 18+ (Download)
• Docker Desktop (Download)

# Global installation
npm install -g repdev

# Verify installation
repdev --version

# Check system health
repdev doctor

RepDev comes with battle-tested presets for popular stacks:

repdev init -p mern

• Frontend: React (Vite)
• Backend: Node.js + Express
• Database: MongoDB Atlas
• Features: Hot reload, auto-install deps, interactive network configuration

repdev init -p django

• Framework: Django
• Database: PostgreSQL
• Features: Auto migrations, static files, custom network support

repdev init -p django-drf

• Backend: Django REST Framework
• Frontend: React
• Database: PostgreSQL
• Features: Full API setup, network isolation options

repdev init -p network-demo

• Purpose: Multi-tier network architecture demonstration
• Services: 7 containers with 3 isolated networks
• Features: Shows microservices, host mode, static IPs, sidecars

Create a new repdev.yml template.

# Interactive mode
repdev init

# Use a preset
repdev init -p mern

# List available presets
repdev init --list

# Force overwrite existing file
repdev init -p django --force

Start your development environment.

# Start all services
repdev up

# Use specific template
repdev up -t custom-template.yml

# Use preset
repdev up -p mern

# Force recreate containers
repdev up --force

# Skip readiness checks
repdev up --no-wait

# Start specific services
repdev up -s backend,db

Stop and remove containers.

# Stop all services
repdev down

# Stop specific services
repdev down -s frontend

# Force removal
repdev down --force

Check environment status.

repdev status

Output:

📊 RepDev Status

Template: /path/to/repdev.yml
Preset: mern

Containers: 2 total, 2 running, 0 stopped
Last Up: 10/20/2025, 2:30:15 PM

📦 Containers:

🟢 backend (mern_backend)
   Image: node:20
   Status: running
   Ports: 3000:3000

🟢 frontend (mern_frontend)
   Image: node:20
   Status: running
   Ports: 5173:5173

View container logs.

# View logs
repdev logs backend

# Follow logs (like tail -f)
repdev logs backend -f

# Show last 50 lines
repdev logs backend --tail 50

Execute commands in containers.

# Interactive shell
repdev exec backend bash

# Run a command
repdev exec backend npm run test

# Database access
repdev exec db psql -U postgres mydb

Restart containers.

# Restart a service
repdev restart backend

# Restart all services
repdev restart --all

Validate template syntax.

# Validate local repdev.yml
repdev validate

# Validate specific file
repdev validate -t custom.yml

# Validate preset
repdev validate -p mern

Run system health checks.

# Basic health check
repdev doctor

# Include port availability
repdev doctor --ports

Output:

🏥 RepDev System Health Check

🟢 Node.js
   Status: ✅ OK
   Version: v20.10.0

🐳 Docker
   Status: ✅ OK
   Version: 24.0.6

📄 Template (repdev.yml)
   Status: ✅ OK

💾 Disk Space
   Status: ✅ OK

📦 RepDev Containers
   Status: ✅ OK
   Total: 2 (2 running, 0 stopped)

✨ All systems operational!

version: '1.0'

metadata:
  name: my-app
  description: My awesome application
  author: Your Name

services:
  app:
    image: node:20-alpine
    container_name: my_app
    working_dir: /app
    volumes:
      - ./app:/app
    ports:
      - "3000:3000"
    environment:
      NODE_ENV: development
      PORT: 3000
    command:
      - sh
      - -c
      - |
        npm install
        npm run dev

version: '1.0'

metadata:
  name: advanced-app

hooks:
  preUp:
    - echo "🚀 Starting environment..."
  postUp:
    - echo "✅ Environment ready!"
    - 'echo "🌐 Visit: http://localhost:3000"'
  preDown:
    - echo "🧹 Cleaning up..."
  postDown:
    - echo "✅ Cleanup complete"

services:
  backend:
    image: node:20
    container_name: app_backend
    working_dir: /app
    volumes:
      - ./backend:/app
    ports:
      - "3000:3000"
    env_file:
      - ./backend/.env
    environment:
      NODE_ENV: development
    hooks:
      beforeStart:
        - echo "Installing backend dependencies..."
      afterStart:
        - echo "Backend started!"
    wait_for:
      type: http
      url: http://localhost:3000/health
      timeout: 60000
      retries: 30
      interval: 2000
    command:
      - sh
      - -c
      - |
        npm install
        npm run dev
    depends_on:
      - db

  db:
    image: postgres:15-alpine
    container_name: app_db
    environment:
      POSTGRES_USER: devuser
      POSTGRES_PASSWORD: devpass
      POSTGRES_DB: devdb
    ports:
      - "5432:5432"
    volumes:
      - ./data/postgres:/var/lib/postgresql/data
    wait_for:
      type: tcp
      host: localhost
      port: 5432

Execute scripts at specific points in the container lifecycle:

hooks:
  preUp: ["echo Starting..."]
  postUp: ["echo Ready!"]
  preDown: ["echo Stopping..."]
  postDown: ["echo Stopped"]

services:
  app:
    hooks:
      beforeStart: ["npm install"]
      afterStart: ["npm run migrate"]

Wait for services to be truly ready:

services:
  api:
    wait_for:
      type: http
      url: http://localhost:3000/health
      timeout: 60000
      retries: 30
      interval: 2000

  db:
    wait_for:
      type: tcp
      host: localhost
      port: 5432

  container:
    wait_for:
      type: container_healthy

Keep secrets out of version control:

services:
  app:
    env_file:
      - .env              # Base config
      - .env.local        # Local overrides
    environment:
      NODE_ENV: development  # Overrides .env

Priority: inline environment > env_file

Control container networking for isolation, performance, and multi-tier architectures:

Network Modes:

services:
  app:
    network_mode: host    # High performance, uses host network
    # network_mode: bridge  # Default, isolated networking
    # network_mode: none    # No networking

Custom Networks (recommended for complex apps):

networks:
  frontend:
  backend:
  database:

services:
  web:
    networks: [frontend]
  api:
    networks: [frontend, backend]
  db:
    networks: [database]  # Fully isolated

Advanced Network Config:

networks:
  app_net:
    driver: bridge
    ipam:
      config:
        - subnet: 172.25.0.0/16

services:
  api:
    networks:
      app_net:
        ipv4_address: 172.25.0.10
        aliases: [api-server, backend]

📖 Full Guide: docs/NETWORK_CONFIGURATION.md

See CUSTOMIZATION.md for detailed customization guide.

Change directories:

volumes:
  - ./backend:/app  # Change to ./server:/app

Change ports:

ports:
  - "3000:3000"  # Change to "4000:4000"

Change package manager:

command:
  - npm install   # Change to 'yarn install' or 'pnpm install'

Use environment files:

env_file:
  - .env

Error: Cannot connect to the Docker daemon

Solutions:

1. Start Docker Desktop
2. Check if Docker daemon is running: docker ps
3. On Linux: sudo systemctl start docker

Error: EADDRINUSE: address already in use

Solutions:

1. Find the process: netstat -ano | findstr :<port> (Windows)
2. Stop conflicting containers: repdev down
3. Change the port in repdev.yml
4. Kill the process or use a different port

Error: container name already in use

Solutions:

1. Use --force flag: repdev up --force
2. Stop existing containers: repdev down
3. Remove conflicting container: docker rm -f <name>

Error: pull access denied or not found

Solutions:

1. Check image name spelling in repdev.yml
2. Verify image exists on Docker Hub
3. Try pulling manually: docker pull <image>
4. Login if needed: docker login

Error: no such file or directory: repdev.yml

Solutions:

1. Run repdev init to create a template
2. Use -t flag: repdev up -t /path/to/template.yml
3. Use a preset: repdev up -p mern

Error: permission denied

Solutions:

1. On Linux: sudo usermod -aG docker $USER
2. On Windows: Run as Administrator
3. Check file/directory permissions

Run diagnostic checks:

repdev doctor

This checks:

• ✅ Node.js version
• ✅ Docker connectivity
• ✅ Template validity
• ✅ Disk space
• ✅ Container status

With port check:

repdev doctor --ports

repdev/
├── src/
│   ├── cli/
│   │   └── commands/      # CLI command implementations
│   ├── core/
│   │   ├── dockerManager.js    # Docker orchestration
│   │   ├── TemplateManager.js  # Template loading
│   │   ├── HooksRunner.js      # Lifecycle hooks
│   │   └── logger.js           # Logging
│   ├── utils/
│   │   ├── envFileLoader.js    # .env file parsing
│   │   ├── errorHandler.js     # Error handling
│   │   └── stateManager.js     # State tracking
│   └── templates/
│       └── presets/       # Pre-built templates
└── docs/                  # Documentation

We welcome contributions! See CONTRIBUTING.md for guidelines.

# Clone the repo
git clone https://github.com/el-noir/repdev.git
cd repdev

# Install dependencies
npm install

# Test locally
node src/index.js --help

# Run tests
npm test

MIT © el-noir

Built with:

• Docker - Container platform
• Commander.js - CLI framework
• Inquirer.js - Interactive prompts
• Dockerode - Docker API client

• Documentation: Full Docs
• Customization Guide: CUSTOMIZATION.md
• Issue Tracker: GitHub Issues
• Discussions: GitHub Discussions

If RepDev helped you, please give it a ⭐ on GitHub!