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.

✨ Features

🎯 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

🚀 Quick Start

Installation

npm install -g repdev

Create Your First Project

# 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?

The Problem

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

The Solution

RepDev provides:

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

Comparison

Feature	Docker Compose	RepDev
Syntax	Verbose YAML	Simple YAML
Setup	Manual	Interactive prompts
Hooks	Limited	Full lifecycle
Readiness	Depends on	Built-in wait_for
Presets	None	MERN, Django, etc.
Port Checks	No	Automatic
Error Help	Generic	Actionable suggestions
State Tracking	No	Yes

📥 Installation

Prerequisites

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

Install RepDev

# Global installation
npm install -g repdev

# Verify installation
repdev --version

# Check system health
repdev doctor

🎯 Available Presets

RepDev comes with battle-tested presets for popular stacks:

🟢 MERN Stack

repdev init -p mern

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

🐍 Django

repdev init -p django

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

🔥 Django REST + React

repdev init -p django-drf

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

🌐 Network Demo

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

🖥️ CLI Commands

Core Commands

`repdev init`

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

`repdev up`

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

`repdev down`

Stop and remove containers.

# Stop all services
repdev down

# Stop specific services
repdev down -s frontend

# Force removal
repdev down --force

`repdev status`

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

DX Commands

`repdev logs <service>`

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

`repdev exec <service> [command...]`

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

`repdev restart [service]`

Restart containers.

# Restart a service
repdev restart backend

# Restart all services
repdev restart --all

Utility Commands

`repdev validate`

Validate template syntax.

# Validate local repdev.yml
repdev validate

# Validate specific file
repdev validate -t custom.yml

# Validate preset
repdev validate -p mern

`repdev doctor`

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!

📝 Template Structure

Basic Template

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

Advanced Template

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

🔧 Advanced Features

Lifecycle Hooks

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"]

Readiness Checks

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

Environment Files

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

Network Configuration

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

🎨 Customization

See CUSTOMIZATION.md for detailed customization guide.

Quick Tips

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

🐛 Troubleshooting

Docker Not Running

Error: Cannot connect to the Docker daemon

Solutions:

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

Port Already in Use

Error: EADDRINUSE: address already in use

Solutions:

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

Container Name Conflict

Error: container name already in use

Solutions:

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

Image Not Found

Error: pull access denied or not found

Solutions:

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

Template Not Found

Error: no such file or directory: repdev.yml

Solutions:

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

Permission Denied

Error: permission denied

Solutions:

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

🏥 Health Checks

Run diagnostic checks:

repdev doctor

This checks:

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

With port check:

repdev doctor --ports

🏗️ Architecture

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

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Quick Start for Contributors

# 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

📜 License

MIT © el-noir

🙏 Acknowledgments

Built with:

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

📚 Resources

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

⭐ Star History

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

Made with ❤️ by developers, for developers

Report Bug · Request Feature · Documentation

Name		Name	Last commit message	Last commit date
docs		docs
src		src
test		test
.env.example		.env.example
.gitignore		.gitignore
ACCOMPLISHMENTS.md		ACCOMPLISHMENTS.md
CONTRIBUTING.md		CONTRIBUTING.md
CUSTOMIZATION.md		CUSTOMIZATION.md
README.md		README.md
RELEASE_NOTES_v1.1.0.md		RELEASE_NOTES_v1.1.0.md
TESTING.md		TESTING.md
docker-compose.yml		docker-compose.yml
goal.txt		goal.txt
package-lock.json		package-lock.json
package.json		package.json

Latest commit

History

Folders and files

Repository files navigation

RepDev 🚀

✨ Features

🚀 Quick Start

Installation

Create Your First Project

📋 Table of Contents

💡 Why RepDev?

The Problem

The Solution

Comparison

📥 Installation

Prerequisites

Install RepDev

🎯 Available Presets

🟢 MERN Stack

🐍 Django

🔥 Django REST + React

🌐 Network Demo

🖥️ CLI Commands

Core Commands

repdev init

repdev up

repdev down

repdev status

DX Commands

repdev logs <service>

repdev exec <service> [command...]

repdev restart [service]

Utility Commands

repdev validate

repdev doctor

📝 Template Structure

Basic Template

Advanced Template

🔧 Advanced Features

Lifecycle Hooks

Readiness Checks

Environment Files

Network Configuration

🎨 Customization

Quick Tips

🐛 Troubleshooting

Docker Not Running

Port Already in Use

Container Name Conflict

Image Not Found

Template Not Found

Permission Denied

🏥 Health Checks

🏗️ Architecture

🤝 Contributing

Quick Start for Contributors

📜 License

🙏 Acknowledgments

📚 Resources

⭐ Star History

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`repdev init`

`repdev up`

`repdev down`

`repdev status`

`repdev logs <service>`

`repdev exec <service> [command...]`

`repdev restart [service]`

`repdev validate`

`repdev doctor`