QwickServ 🚀

Quickly spin up a local PHP web server environment using Docker.

QwickServ is an interactive CLI tool designed to generate tailored docker-compose.yml configurations, web server configs (Nginx or Apache), SSL certificates, and database/tooling setups for PHP projects in seconds.

✨ Features

• ⚡ Zero-Config or Highly Customized: Interactive wizard prompts for project settings with smart defaults inferred from your current workspace.
• 🐘 Multiple PHP Versions: Supports PHP 8.3, 8.2, 8.1, 8.0, and 7.4.
• 🌐 Web Server Selection:
  • Nginx + PHP-FPM (Reverse proxy with clean routing and separation of concerns).
  • Apache with mod_php / php-apache (Classic all-in-one web server).
  • Support for default generated configurations or your own custom config files.
• 🗄️ Database Support:
  • MySQL (standalone or paired with phpMyAdmin).
  • PostgreSQL.
  • Microsoft SQL Server (standalone or paired with CloudBeaver).
  • SQLite (file-based setup with guidance).
• 📧 Email Testing: Built-in Mailpit integration for local SMTP testing and webmail inspection.
• 🔒 HTTP / HTTPS: HTTP is always enabled; enabling HTTPS adds an HTTPS listener with automatic HTTP redirect support.
• 🔐 HTTPS / SSL Ready: Generates local self-signed SSL certificates automatically when HTTPS is selected.
• 🔄 Smart Port Conflict Checking: Validates both host system ports and running Docker container published ports to prevent collisions.
• 📁 Public Directory & Asset Migration: Option to automatically move web files into your chosen public web root (e.g., public/, src/, www/).
• 💾 Resume & Repeat: Saves previous configuration (_qwickserv/data.json) for quick setup resumption while securely stripping passwords.
• 🔐 Environment-based settings: Stores database settings in the single local .env file and keeps editable web-server variables in _qwickserv/data.json; generated Compose configuration receives those web variables directly.
• 🛡️ Production MySQL hardening: Locks the MySQL root account and removes remote root access after first database initialization; the configured application user remains available.
• 🧹 Generated File Cleanup: Removes generated files inside _qwickserv/ while keeping data.json by default; you can choose to remove the saved data too.
• 🧹 Container Management: Detects existing project containers and offers cleanup on startup or post-generation.

📋 Prerequisites

Make sure the following tools are installed and available in your PATH:

• Node.js (v16.0.0 or later)
• Docker (Docker Desktop or Docker Engine running)
• Docker Compose (v2 plugin)

🚀 Installation & Usage

Running via npx (or global link)

You can run QwickServ directly in your project root:

# installed globally using Node
npm install -g qwickserv

# then run
qwickserv

# or run directly with npx (no install required)
npx qwickserv

Options

| Option / Flag | Description | | :--- | :--- | | -f, --force, /force | Force overwrite of an existing docker-compose.yml without confirmation |

🛠️ Step-by-Step CLI Walkthrough

1. Dependency Check: Verifies Docker CLI, Docker Compose v2, and engine status.
2. Cleanup Stale Containers: Detects any active containers from the current project prefix and offers to clean them up.
3. Load Saved Session: If a previous run was detected (_qwickserv/data.json), choose to resume, keep the saved data exactly as-is and generate immediately, or start fresh.
4. Configuration Prompts:
   • Project name: Container naming prefix (Docker-safe characters).
   • PHP Version: Select from 8.3 down to 7.4.
   • Web Server: Choose between Nginx or Apache, with options to supply custom .conf files.

• Database: Select MySQL (+ phpMyAdmin), PostgreSQL, MS SQL Server (+ CloudBeaver), SQLite (file-based, no database container), or None.
• Email: Select Mailpit or None.
• Public Directory: Web root path relative to project root (e.g., public, web, dist).
• Environment: Development (live bind mount for instant edits) or Production (volume-copied files).
• Web Variables: Review, edit, or add web-server environment variables saved in _qwickserv/data.json.
• HTTPS / SSL: Self-signed SSL certificate generation with a custom hostname; enabling HTTPS adds an HTTPS listener and HTTP redirect.
• Port Configuration: Interactive, conflict-free port selection.

5. File Migration: Option to select files/folders in your project root to migrate into your chosen public directory.
6. File Generation: Generates docker-compose.yml, web server configs, SSL certificates, and persistent metadata in _qwickserv/.
7. Next Actions:
   • ▶️ Run now (docker compose up -d)

• 🗑️ Remove project containers (then optionally delete Docker volumes and docker-compose.yml; both are kept by default)
• 🧹 Clean generated _qwickserv files (keeps data.json by default)
• 📋 Copy run command to clipboard
• 🔄 Restart QwickServ wizard
• 🚪 Exit (the final menu remains open until this is selected)

📁 Generated File Structure

After running QwickServ, your project workspace will include:

your-project/
├── .env                         # Local database settings (ignored by Git)
├── _qwickserv/
│   ├── mysql/init/disable-root.sql # Production MySQL hardening script
│   ├── data.json                  # Saved configuration and web variables (database passwords omitted)
│   ├── php/Dockerfile              # PHP image with selected database drivers
│   ├── nginx/nginx.conf           # Default Nginx config (if Nginx chosen)
│   ├── apache/000-default.conf    # Default Apache vhost config (if Apache chosen)
│   └── ssl/                       # Generated self-signed SSL cert & private key
│       ├── cert.pem
│       └── key.pem
├── public/                        # Configured web root directory
│   └── index.php
└── docker-compose.yml             # Composed stack configuration

🔌 Connection Reference

When running your stack, services are accessible via the following internal hostnames within Docker networks:

| Service | Internal Hostname | Internal Port | Host Port (Default) | Web UI / Tool | | :--- | :--- | :--- | :--- | :--- | | PHP-FPM | <project>-php | 9000 | — | — | | Nginx / Apache | <project>-nginx / <project>-apache | 80 / 443 | 80 / 443 | Web browser | | MySQL | <project>-mysql | 3306 | 3306 | phpMyAdmin (8081) | | PostgreSQL | <project>-postgres | 5432 | 5432 | Host DB tools | | MS SQL Server | <project>-mssql | 1433 | 1433 | CloudBeaver (8978) | | Mailpit | <project>-mailpit | 1025 (SMTP) / 8025 (HTTP) | 1025 / 8025 | Mailpit Web UI (8025) |

📜 License

This project is licensed under the MIT License.