ndev

ndev

Universal, Zero-Config Local PHP & Web Development Stack for Windows and Linux.

---

ndev is an all-in-one developer environment manager that isolates, orchestrates, and runs multi-version PHP runtimes, Nginx web server, MariaDB / MySQL, Redis in-memory store, phpMyAdmin, Mailpit email sandbox, local SSL certificates (mkcert), and public HTTP tunnels (ngrok) on Windows 10/11 and Linux (Debian/Ubuntu).

---

Key Features

• Multi-Version PHP Environment:
  • Windows: Zero-compilation prebuilt official binaries from windows.php.net (PHP 5.6 – 8.5, Thread-Safe & Non-Thread-Safe, x64/x86).
  • Linux: Sandboxed, unprivileged source compilation with bubblewrap and self-healing multiarch library paths.
• Process Orchestration & FastCGI / FPM:
  • Windows: Multi-process php-cgi.exe FastCGI worker pools load-balanced through Nginx upstream blocks.
  • Linux: Native php-fpm worker daemons over isolated Unix sockets (~/.ndev/run/php<ver>.sock).
• Interactive Asynchronous TUI Dashboard (ndev ui):
  • Full-screen real-time terminal UI built with Textual for live monitoring, batch start/stop/restart, on-the-fly CLI PHP version switching, folder-picker virtual host creator, and live log tailing.
• Automated Nginx Virtual Hosts (ndev vhost):
  • Generates Nginx server blocks with custom FastCGI upstreams, HTTP $\rightarrow$ HTTPS redirects, trusted local SSL certificates, and hosts file mappings.
• In-Memory Store (ndev redis):
  • Native background Redis server management (6379) with interactive redis-cli terminal integration.
• Local Email Sandbox (ndev mailpit):
  • Embedded zero-dependency SMTP email catcher (127.0.0.1:1025) and web inbox (http://127.0.0.1:8025).
• Database & Web Administration (ndev db & ndev pma):
  • Portable MariaDB server (3306) with user/database management CLI tools and local phpMyAdmin (http://127.0.0.1:8080).
• Single-Command Stack Upgrader (ndev upgrade):
  • Automated version scanning and non-destructive upgrading for Nginx, MariaDB, Redis, Mailpit, phpMyAdmin, mkcert, and Composer.

---

Architecture & Platform Mapping

ndev/
├── main.py                 # Cross-platform dispatcher & runtime detector
├── common/                 # Shared utilities, configs, logger, GitHub API
├── win/                    # Windows native subsystem (FastCGI, Shims, Click CLI, TUI)
│   ├── core/               # php, services, fcgi, vhost, db, redis_core, mailpit, pma, upgrade
│   └── templates/          # Nginx virtual host configuration templates
└── linux/                  # Linux native subsystem (PHP-FPM, Typer CLI, TUI, Chroot)
    ├── php/                # Source resolver, downloader, extensions, builder
    ├── chroot/             # Bubblewrap sandbox manager
    └── runtime/            # FPM, PMA, Mailpit, and systemd daemons

Subsystem	Windows 10/11 (ndev-win)	Linux Debian/Ubuntu (ndev-linux)
PHP Distribution	Precompiled binaries from windows.php.net	Compiles from official source via bubblewrap sandbox
Process Model	Multi-worker php-cgi.exe pools via Nginx upstream	Native php-fpm daemons over Unix domain sockets
CLI & PATH	Global batch shims in %USERPROFILE%\.ndev\shims\	Symlinks in ~/.local/bin/
Privilege Elevation	Win32 ShellExecuteExW (runas) only for hosts	sudo for Nginx and /etc/hosts
Web Server	Portable Nginx in %USERPROFILE%\.ndev\nginx\	System Nginx via apt install nginx
Database	Portable MariaDB in %USERPROFILE%\.ndev\mariadb\	System MariaDB via apt install mariadb-server
In-Memory Cache	Portable Redis in %USERPROFILE%\.ndev\redis\	System Redis via apt install redis-server
Email Sandbox	Standalone prebuilt Mailpit binary	Standalone prebuilt Mailpit binary
phpMyAdmin	Served via PHP CLI server (http://127.0.0.1:8080)	Served via PHP CLI server (http://127.0.0.1:8080)
Local SSL	Standalone mkcert.exe in shims\	System mkcert package via apt
TUI Dashboard	Asynchronous Textual TUI (ndev ui)	Asynchronous Textual TUI (ndev ui)

---

Directory Structure & Layout

Windows Layout (%USERPROFILE%\.ndev)

%USERPROFILE%\.ndev\
├── certs\                  # Local SSL certificates and cacert.pem CA bundle
├── downloads\              # Cached zip downloads
├── mariadb\                # Portable MariaDB installation & data directory
│   ├── bin\                # mysqld.exe, mysql.exe, mysqldump.exe
│   └── data\               # Database storage
├── nginx\                  # Portable Nginx installation
│   ├── conf\
│   │   ├── nginx.conf      # Main Nginx config (includes ndev-vhosts/*.conf)
│   │   └── ndev-vhosts\    # Virtual host configurations (*.conf)
│   ├── logs\               # Nginx access/error logs per virtual host
│   └── temp\               # FastCGI and proxy client temporary body storage
├── php\
│   └── <version>\          # Extracted PHP binaries (php.exe, php-cgi.exe, php.ini, ext/)
├── pma\                    # Standalone phpMyAdmin installation & config.inc.php
├── redis\                  # Portable Redis server and redis-cli binaries
├── run\                    # Active PID and FastCGI worker state files (JSON)
├── shims\                  # Global batch shims for PATH (php, composer, mysql, redis-cli, mailpit, ndev, etc.)
├── mailpit.db              # Persistent message database for Mailpit
└── config.json             # Global configuration (ports, worker counts)

Linux Layout (~/.ndev)

~/.ndev/
├── bin/                    # Standalone binaries (mailpit)
├── builds/                 # Source tarballs and compilation build directories
├── cache/                  # Download and build cache
├── certs/                  # Local SSL certificates and mkcert root CA
├── chroot/                 # Sandboxed development packages and build root
├── downloads/              # Downloaded source archives
├── logs/                   # Service and daemon logs (pma.log, mailpit.log, etc.)
├── php/
│   └── <version>/          # Compiled PHP installations (bin/, sbin/, etc/php.ini, etc/php-fpm.d/)
├── phpmyadmin/             # Standalone phpMyAdmin installation & config.inc.php
├── run/                    # Active PID and Unix domain socket files (*.sock, *.pid)
├── current                 # Symlink pointing to the currently active PHP version directory
├── mailpit.db              # Persistent message database for Mailpit
└── config.toml             # Global build and runtime configuration

---

Installation

Standard Installation via PyPI

Install ndev-stack using pip or pipx:

# Using pip
pip install ndev-stack

# Or using pipx (isolated application environment)
pipx install ndev-stack

Note: The package is published on PyPI as ndev-stack, which provides the global commands ndev, ndev-win, and ndev-linux.

Development / Source Installation

git clone https://github.com/ankitkaran99/ndev.git
cd ndev
pip install -e .

---

Quick Start Guide

Windows 10 / 11

# 1. Install ndev-stack
pip install ndev-stack

# 2. Download and configure portable stack (Nginx, MariaDB, Redis, mkcert, Mailpit, Composer)
ndev setup

# 3. Add shims to user PATH (one-time setup for global CLI access)
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";$env:USERPROFILE\.ndev\shims", "User")
$env:Path += ";$env:USERPROFILE\.ndev\shims"

# 4. Verify installation & launch interactive dashboard
ndev doctor
ndev ui

Linux (Debian / Ubuntu)

# 1. Install system build dependencies
sudo apt update
sudo apt install -y bubblewrap build-essential pkg-config nginx mkcert redis-server default-mysql-client
mkcert -install

# 2. Install ndev-stack
pip install ndev-stack

# 3. Bootstrap runtime environment and shims
ndev setup
export PATH="$HOME/.local/bin:$PATH"

# 4. Verify installation & launch interactive dashboard
ndev doctor
ndev ui

---

Quick Command Reference

Command	Action
ndev ui	Launch real-time Textual TUI dashboard (aliases: tui, dashboard)
ndev available	List available PHP releases (--archives for legacy versions)
ndev install <ver>	Install / compile a PHP version (8.4, 8.3, 7.4, etc.)
ndev use <ver>	Switch active CLI PHP version on PATH
ndev current	Show active CLI PHP version
ndev list	List installed PHP versions and daemon / worker pool status
ndev start <target>	Start service or pool (all, nginx, mariadb, redis, pma, mailpit, <ver>)
ndev stop <target>	Stop service or pool (all, nginx, mariadb, redis, pma, mailpit, <ver>)
ndev restart <target>	Restart service or pool (all, nginx, mariadb, redis, pma, mailpit, <ver>)
ndev reload nginx	Reload Nginx configuration without downtime
ndev status	View real-time service status dashboard
ndev ctl	Interactive terminal service control menu
ndev vhost	Interactive virtual host creation wizard with local SSL
ndev vhost-list	List all configured virtual hosts
ndev vhost-remove	Remove virtual host and clean up hosts file
ndev db	Interactive SQL database management wizard
ndev redis	Manage Redis server or launch interactive redis-cli
ndev mailpit	Manage local email sandbox (install, start, stop, launch, open)
ndev pma	Manage phpMyAdmin background service (http://127.0.0.1:8080)
ndev ext	Manage PECL extensions (list, install, enable, disable)
ndev grok	Public HTTP tunneling for local virtual hosts via ngrok
ndev postgres	Manage PostgreSQL server (install, start, stop, restart, status)
ndev mongodb	Manage MongoDB server (install, start, stop, restart, status)
ndev module list	List all dynamic modules and status in <userdir>/.ndev/modules/
ndev module <action>	Manage dynamic module lifecycle (install, start, stop, restart, status, open)
ndev module create	Scaffold a new dynamic module with manifest and template code
ndev upgrade	Check for and upgrade stack components (Nginx, MariaDB, Redis, PMA, Mailpit, mkcert, Composer)
ndev upgrade --check	Check component versions against upstream releases without upgrading
ndev shell	Interactive developer subshell pre-loaded with PHP/Composer/MySQL/Redis on PATH
ndev doctor	Run environment diagnostics and health checks
ndev logs	View and tail service and virtual host logs
ndev clean	Clean up downloads cache and stale runtime state

---

Detailed Usage Guide

1. Interactive Terminal UI Dashboard (ndev ui)

Launch the modern, responsive Textual TUI dashboard for real-time monitoring and process control:

ndev ui
# Aliases: ndev tui, ndev dashboard

• Live Status Grid: Monitor real-time status, PIDs, and active ports for Nginx, MariaDB, Redis, PMA, Mailpit, and PHP worker pools.
• One-Click Component Setup & Upgrades: Install uninstalled services (Redis, PMA, Mailpit, Nginx, MariaDB, mkcert, Composer) or upgrade existing components with single-click UI actions.
• Interactive Virtual Host Manager: Create new virtual hosts (＋ Create VHost) with automatic local SSL (mkcert) and an integrated folder-picker dialog.
• PHP Runtime Management: Install any PHP version (＋ Install PHP), uninstall versions (✖ Uninstall Selected), or change the active CLI PHP version via dropdown.
• Batch Actions: One-click Start All, Stop All, Restart All, and Reload Nginx from the persistent sidebar.
• Integrated Log Tail Viewer: Select and inspect live logs for Nginx, MariaDB, Redis, PHP, and Virtual Hosts.

---

2. PHP Version Management

# List available PHP releases (from php.net / windows.php.net)
ndev available
ndev available --archives    # include legacy releases (5.6 - 7.3)

# Install a PHP version (prebuilt on Windows, source-compiled on Linux)
ndev install 8.4

# List locally installed PHP versions and daemon/pool status
ndev list

# Switch globally active CLI PHP version
ndev use 8.4

# Show current active CLI PHP version
ndev current

# Uninstall a PHP version
ndev uninstall 7.4

---

3. Service & Process Management

# Start / Stop / Restart a PHP pool or individual service
ndev start 8.4
ndev stop 8.4
ndev restart 8.4

# Control core services
ndev start nginx
ndev start mariadb
ndev start redis
ndev start pma
ndev start mailpit

# Batch operations
ndev start all
ndev stop all
ndev restart all

# Reload Nginx configuration without downtime
ndev reload nginx

# View service status
ndev status

---

4. Virtual Host Management (vhost)

Create and manage local Nginx sites mapped to 127.0.0.1:

# Interactive wizard (auto-prompts for domain, document root, PHP version, and SSL)
ndev vhost

# Create a standard HTTP virtual host
ndev vhost --domain project.local --root /path/to/project --php 8.4

# Create an HTTPS virtual host with trusted local SSL certificates (mkcert)
ndev vhost --domain project.local --root /path/to/project --php 8.4 --ssl

# List all configured virtual hosts
ndev vhost-list

# Remove a virtual host (removes Nginx conf and cleans hosts file)
ndev vhost-remove --domain project.local

---

5. Redis In-Memory Store (redis)

Manage the local Redis server and launch the interactive redis-cli:

[!TIP] Redis Connection Defaults:

• Host: 127.0.0.1 or localhost
• Port: 6379
• Password: None (default)

# Start Redis server
ndev redis start
ndev start redis

# Check Redis status
ndev redis status
ndev status redis

# Open interactive redis-cli terminal
ndev redis cli

# Stop or restart Redis server
ndev redis stop
ndev redis restart

Laravel / Symfony / WordPress Configuration:

REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

---

6. SQL Database Manager (db) & phpMyAdmin (pma)

Manage MySQL/MariaDB databases, users, and web administration:

[!TIP] Default MariaDB / MySQL Credentials:

• Host: 127.0.0.1 or localhost
• Port: 3306
• Username: root
• Password: root (Windows) / system auth (Linux)
• phpMyAdmin URL: http://127.0.0.1:8080

# Launch interactive database management wizard
ndev db

# Create database and user
ndev db create-db mydb --owner myuser
ndev db create-user myuser --new-password secret --grant-db mydb

# Export & import database dumps
ndev db export-db mydb -o backup.sql
ndev db import-db mydb backup.sql

# Start phpMyAdmin web UI
ndev start pma
ndev pma

---

7. Local Email Sandbox (mailpit)

Catch every outgoing e-mail your local applications send using Mailpit:

[!TIP] SMTP & Web UI Defaults:

• SMTP Server: 127.0.0.1:1025
• Web Inbox: http://127.0.0.1:8025
• No authentication required — all emails are safely intercepted locally.

# Start Mailpit (auto-installs if not present)
ndev mailpit start
ndev start mailpit

# Open Web UI in default browser
ndev mailpit launch
ndev mailpit open

# Stop or restart Mailpit
ndev mailpit stop
ndev mailpit restart

Configuring Mailpit in your Project:

Laravel (.env):

MAIL_MAILER=smtp
MAIL_HOST=127.0.0.1
MAIL_PORT=1025
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_ENCRYPTION=null

PHP (php.ini):

[mail function]
SMTP = 127.0.0.1
smtp_port = 1025

---

8. Stack Upgrade Engine (upgrade)

Scan for and upgrade stack components (Nginx, MariaDB, Redis, PMA, Mailpit, mkcert, Composer) safely against latest upstream releases:

# Check for available updates across all stack components
ndev upgrade --check

# Upgrade all components to latest stable releases
ndev upgrade

# Upgrade a specific component
ndev upgrade redis
ndev upgrade mailpit
ndev upgrade pma

---

9. Diagnostics & Developer Tools

# Run full environment health check
ndev doctor

# Launch pre-configured developer subshell
ndev shell

# Tail live logs for services or virtual hosts
ndev logs
ndev logs 8.4
ndev logs nginx

# Tunnel local virtual host to public web via ngrok
ndev grok

# Clean download cache and temporary files
ndev clean

---

10. Extensible Dynamic Modules (ndev module)

ndev features a modular architecture where core services (nginx, mariadb, php, phpmyadmin, ngrok) are augmented with dynamic modules (mailpit, redis, postgres, mongodb, and custom community modules) located in <userdir>/.ndev/modules/<module_name>/.

Module Commands:

# List all discovered modules and running status
ndev module list

# Manage module lifecycle
ndev module install mailpit
ndev module start redis
ndev module status postgres
ndev module status mongodb
ndev module open mailpit     # Opens web UI if available
ndev module restart redis
ndev module stop redis

# Direct convenience commands also work seamlessly:
ndev start mailpit
ndev stop redis
ndev postgres start
ndev postgres status
ndev mongodb start
ndev mongodb status

# Scaffold a new custom module
ndev module create my-service --display-name "My Custom Service" --category queue --port 9000

Module Structure (~/.ndev/modules/<name>/):

~/.ndev/modules/my-service/
├── manifest.json   # Module metadata, ports, categories, and web UI definitions
└── module.py       # Python lifecycle handler (is_installed, install, start, stop, restart, status, open_ui)

Sample manifest.json:

{
  "name": "my-service",
  "display_name": "My Custom Service",
  "version": "1.0.0",
  "description": "Custom queue worker service",
  "category": "queue",
  "ports": [9000],
  "web_ui": "http://127.0.0.1:9000",
  "platforms": ["windows", "linux"],
  "entrypoint": "module.py"
}

Dynamic modules appear automatically inside the TUI Dashboard (ndev ui), where you can start, stop, restart, and open web interfaces with a single click.

📖 Looking to build your own module? See the full ndev Module Developer Guide (MODULE_DEV_GUIDE.md) for step-by-step instructions, manifest schema, and boilerplate templates.

---

Configuration Files

Windows

• Global Settings: %USERPROFILE%\.ndev\config.json
• PHP Configuration: %USERPROFILE%\.ndev\php\<version>\php.ini
• Nginx Main Config: %USERPROFILE%\.ndev\nginx\conf\nginx.conf
• Virtual Host Configs: %USERPROFILE%\.ndev\nginx\conf\ndev-vhosts\*.conf
• FastCGI Worker Pools: Base port 13000 with 4 workers per PHP version (customizable in config.json).

Linux

• Global Settings: ~/.ndev/config.toml
• PHP Configuration: ~/.ndev/php/<version>/etc/php.ini
• PHP Extensions: ~/.ndev/php/<version>/etc/conf.d/<ext>.ini
• PHP-FPM Pool Config: ~/.ndev/php/<version>/etc/php-fpm.d/www.conf

---

License

MIT License. See LICENSE for more details.