QUICK-CICD Generator - Complete Documentation

Table of Contents

1. Overview & Getting Started
2. System Requirements
3. Supported Project Types
4. Frontend Projects
5. Backend Projects
6. Python Projects
7. Step-by-Step Usage Guide
8. Support & Contact

1. Overview & Getting Started

🚀 What is QUICK-CICD Generator?

The QUICK-CICD Generator is a powerful Node.js CLI tool that automatically generates Docker configurations, CI/CD pipelines, and deployment scripts for various project types.

📋 Quick Start

Command to run:

npx quick-cicd

Full Documentation: https://nazmulhaque.netlify.app/quick-cicd/

👨‍💻 Developer Contact

• Name: Nazmul Haque
• Email: [email protected]
• LinkedIn: https://www.linkedin.com/in/nazzmulhq/
• Portfolio: https://nazmulhaque.netlify.app/

2. System Requirements

🔍 Pre-Installation Check

The tool automatically checks these requirements when you run it:

✅ Required Dependencies

• Node.js: Version 16.0.0 or higher
• Git: Required for version control
• npm/yarn/pnpm: Package manager

⚠️ Optional Dependencies

• Docker: For local testing (recommended)
• Docker Compose: For multi-service applications

🖥️ System Check Output

When you run npx quick-cicd, you'll see:

✓ Checking system requirements...
   Node.js v18.17.0 ✓, Git ✓, Docker ✓

🛠️ Platform-Specific Installation

Windows

# Install Node.js from nodejs.org or using Chocolatey
choco install nodejs git docker-desktop

# Verify installation
node --version
git --version
docker --version

macOS

# Install using Homebrew
brew install node git
brew install --cask docker

# Verify installation
node --version
git --version
docker --version

Linux (Ubuntu/Debian)

# Install Node.js
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs git

# Install Docker
sudo apt-get update
sudo apt-get install docker.io docker-compose

# Verify installation
node --version
git --version
docker --version

3. Supported Project Types

📦 Available Project Templates

The QUICK-CICD Generator supports the following project types:

1. ⚛️ React with Vite - Frontend SPA
2. 🔼 Next.js - Full-stack React Framework
3. 🟢 Node.js Backend - Express/NestJS API
4. 🐘 PHP Laravel - Backend Framework
5. 🐍 Python Django - Full-stack Python Framework
6. ⚡ Python FastAPI - API Framework
7. 🔹 Simple Python - Python with Nginx

🎯 What Gets Generated

For each project type, the tool generates:

• Dockerfile - Container configuration
• docker-compose.yml - Service orchestration
• ecosystem.config.js - PM2 process manager config
• deploy.sh - Deployment automation script
• .env.example - Environment variables template

4. Frontend Projects

4.1 React with Vite (Frontend SPA)

Pre-Requirements

# Must have these files in your project root:
├── package.json           # Required - Contains Vite & React dependencies
├── vite.config.js         # Vite configuration
├── src/                   # Source code directory
│   ├── main.jsx          # Entry point
│   └── App.jsx           # Main component
└── index.html            # HTML template

Create New Project

npm create vite@latest my-react-app -- --template react
cd my-react-app
npm install

Dependencies Check

• vite in dependencies or devDependencies
• react in dependencies
• react-dom in dependencies

Generated Files Structure

project-root/
├── Dockerfile              # Multi-stage build for React + Vite
├── docker-compose.yml      # Container orchestration
├── ecosystem.config.js     # PM2 process manager configuration
├── deploy.sh              # Deployment automation script
├── .env.example           # Environment variables template
├── package.json           # Your existing file
├── vite.config.js         # Your existing file
└── src/                   # Your existing source code
    ├── main.jsx
    └── App.jsx

Enhanced vite.config.js

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  server: {
    host: '0.0.0.0',
    port: 3000,
  },
  build: {
    outDir: 'dist',
    sourcemap: false,
  },
});

4.2 Next.js (Full-stack React Framework)

Pre-Requirements

# Must have these files in your project root:
├── package.json           # Required - Contains Next.js dependencies
├── next.config.js         # Next.js configuration (optional)
├── pages/                 # Pages directory OR
├── app/                   # App directory (Next.js 13+)
│   ├── layout.js         # Root layout
│   └── page.js           # Home page
└── public/               # Static assets

Create New Project

npx create-next-app@latest my-nextjs-app
cd my-nextjs-app

Dependencies Check

• next in dependencies
• react in dependencies
• react-dom in dependencies

Generated Files Structure

project-root/
├── Dockerfile              # Optimized for Next.js (build + runtime)
├── docker-compose.yml      # Container with Next.js optimizations
├── ecosystem.config.js     # PM2 configuration for Next.js
├── deploy.sh              # Next.js specific deployment
├── .env.example           # Next.js environment variables
├── package.json           # Your existing file
├── next.config.js         # Your existing file
├── pages/                 # Your existing pages
└── public/                # Your existing static assets

Enhanced next.config.js

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'standalone',
  experimental: {
    outputFileTracingRoot: path.join(__dirname, '../../'),
  },
};

module.exports = nextConfig;

Environment Variables (.env.example)

NODE_ENV=production
PORT=3000
NEXTAUTH_SECRET=your-secret-key
NEXTAUTH_URL=http://localhost:3000

5. Backend Projects

5.1 Node.js Backend (Express/NestJS API)

Pre-Requirements

# Must have these files in your project root:
├── package.json           # Required - Contains Express/NestJS dependencies
├── src/                   # Source code directory OR
├── index.js              # Entry point OR
├── app.js                # Main application file
└── routes/               # Routes directory (optional)

Create New Project

Express.js:

mkdir my-node-backend && cd my-node-backend
npm init -y
npm install express cors helmet morgan dotenv

NestJS:

npm i -g @nestjs/cli
nest new my-nest-project

Dependencies Check

• express OR @nestjs/core in dependencies
• Valid Node.js backend structure

Generated Files Structure

project-root/
├── Dockerfile              # Backend-optimized container
├── docker-compose.yml      # Multi-service (App + MySQL + Redis)
├── ecosystem.config.js     # PM2 configuration for backend
├── deploy.sh              # Backend deployment with database
├── .env.example           # Database and service configurations
├── package.json           # Your existing file
├── src/                   # Your existing source code
│   ├── index.js
│   ├── routes/
│   └── controllers/
└── node_modules/          # Your existing dependencies

Sample Express Server (src/index.js)

const express = require('express');
const cors = require('cors');
const helmet = require('helmet');
const morgan = require('morgan');
require('dotenv').config();

const app = express();
const PORT = process.env.PORT || 3000;

// Middleware
app.use(helmet());
app.use(cors());
app.use(morgan('combined'));
app.use(express.json());

// Routes
app.get('/', (req, res) => {
  res.json({ message: 'Node.js API is running!' });
});

app.get('/health', (req, res) => {
  res.json({ status: 'healthy', timestamp: new Date().toISOString() });
});

app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

Docker Services

services:
  app: # Your Node.js application
  mysql: # MySQL 8.0 database
  redis: # Redis cache

Environment Variables (.env.example)

NODE_ENV=production
PORT=3000
DB_HOST=mysql
DB_PORT=3306
DB_USER=root
DB_PASSWORD=rootpassword
DB_NAME=your_database
REDIS_HOST=redis
REDIS_PORT=6379
JWT_SECRET=your-jwt-secret

5.2 PHP Laravel (Backend Framework)

Pre-Requirements

# Must have these files in your project root:
├── composer.json          # Required - Contains Laravel dependencies
├── artisan               # Laravel CLI tool
├── app/                  # Application code
│   ├── Http/
│   └── Models/
├── config/               # Configuration files
├── database/             # Database files
│   ├── migrations/
│   └── seeders/
├── routes/               # Route definitions
│   ├── web.php
│   └── api.php
└── storage/              # Storage directory
    ├── app/
    ├── framework/
    └── logs/

Create New Project

composer create-project laravel/laravel my-laravel-app
cd my-laravel-app
php artisan key:generate

Dependencies Check

• laravel/framework in composer.json
• PHP version compatibility
• Valid Laravel project structure

Generated Files Structure

project-root/
├── Dockerfile              # PHP-FPM with Nginx
├── docker-compose.yml      # Laravel + MariaDB setup
├── deploy.sh              # Laravel-specific deployment
├── .env.example           # Laravel environment template
├── composer.json          # Your existing file
├── artisan               # Your existing Laravel CLI
├── app/                  # Your existing application code
├── config/               # Your existing configuration
├── database/             # Your existing database files
├── routes/               # Your existing routes
├── storage/              # Your existing storage
└── vendor/               # Composer dependencies

Docker Services

services:
  app: # Laravel application (PHP-FPM + Nginx)
  mariadb: # MariaDB 10.6 database

Environment Variables (.env.example)

APP_NAME=YourLaravelApp
APP_ENV=production
APP_KEY=base64:your-app-key
APP_DEBUG=false
APP_URL=http://localhost

DB_CONNECTION=mysql
DB_HOST=mariadb
DB_PORT=3306
DB_DATABASE=laravel_db
DB_USERNAME=laravel_user
DB_PASSWORD=laravel_password

6. Python Projects

6.1 Python Django (Full-stack Python Framework)

Pre-Requirements

# Recommended project structure (optional - will be created if missing):
├── manage.py             # Django management script (indicates Django project)
├── requirements.txt      # Python dependencies (optional)
├── myproject/            # Project directory
│   ├── __init__.py
│   ├── settings.py
│   ├── urls.py
│   └── wsgi.py
└── myapp/                # Application directory (optional)
    ├── __init__.py
    ├── models.py
    ├── views.py
    └── urls.py

Create New Project

# Create virtual environment
python -m venv django_env
source django_env/bin/activate  # Linux/Mac
# django_env\Scripts\activate   # Windows

# Install Django
pip install django

# Create project
django-admin startproject myproject .
python manage.py startapp myapp
pip freeze > requirements.txt

Dependencies Check

• Python installation
• Optional: Django project structure
• Optional: requirements.txt file

Generated Files Structure

project-root/
├── Dockerfile              # Python Django container
├── docker-compose.yml      # Django + MySQL + Nginx setup
├── nginx/
│   └── conf.d/
│       └── default.conf    # Nginx configuration for Django
├── deploy.sh              # Django deployment script
├── .env.example           # Django environment variables
├── requirements.txt       # Sample Python dependencies (generated if missing)
├── manage.py              # Your existing Django management script
├── myproject/             # Your existing Django project
│   ├── settings.py
│   ├── urls.py
│   └── wsgi.py
└── static/                # Static files directory

Docker Services

services:
  web: # Django application
  nginx: # Nginx reverse proxy
  mysql: # MySQL 8.0 database

Generated requirements.txt (if missing)

Django>=4.2.0
mysqlclient>=2.1.0
gunicorn>=20.1.0
python-decouple>=3.6
Pillow>=9.5.0

Environment Variables (.env.example)

DEBUG=False
SECRET_KEY=your-django-secret-key
DATABASE_URL=mysql://django_user:django_password@mysql:3306/django_db
ALLOWED_HOSTS=localhost,127.0.0.1

6.2 Python FastAPI (API Framework)

Pre-Requirements

# Recommended project structure (optional):
├── main.py               # FastAPI application entry point
├── requirements.txt      # Python dependencies (optional)
├── app/                  # Application directory (optional)
│   ├── __init__.py
│   ├── routers/
│   ├── models/
│   └── database.py
└── tests/                # Tests directory (optional)

Create New Project

# Create virtual environment
python -m venv fastapi_env
source fastapi_env/bin/activate  # Linux/Mac

# Install FastAPI
pip install fastapi uvicorn sqlalchemy pymysql
pip freeze > requirements.txt

# Create basic structure
mkdir app
touch main.py app/__init__.py

Dependencies Check

• Python installation
• Optional: FastAPI project structure
• Optional: requirements.txt file

Generated Files Structure

project-root/
├── Dockerfile              # FastAPI optimized container
├── docker-compose.yml      # FastAPI + MySQL setup
├── deploy.sh              # FastAPI deployment script
├── .env.example           # API environment variables
├── requirements.txt       # FastAPI dependencies (generated if missing)
├── main.py                # Your existing FastAPI app (or create new)
├── app/                   # Your existing application code
│   ├── routers/
│   ├── models/
│   └── database.py
└── tests/                 # Your existing tests

Sample FastAPI main.py

from fastapi import FastAPI
from fastapi.responses import JSONResponse

app = FastAPI(
    title="My FastAPI App",
    description="A FastAPI application with CI/CD",
    version="1.0.0"
)

@app.get("/")
async def root():
    return {"message": "Hello from FastAPI!"}

@app.get("/health")
async def health_check():
    return JSONResponse(content={"status": "healthy"})

@app.get("/items/{item_id}")
async def read_item(item_id: int, q: str = None):
    return {"item_id": item_id, "q": q}

Docker Services

services:
  web: # FastAPI application
  mysql: # MySQL 8.0 database

Generated requirements.txt (if missing)

fastapi>=0.100.0
uvicorn[standard]>=0.22.0
sqlalchemy>=2.0.0
pymysql>=1.0.3
pydantic>=2.0.0
python-multipart>=0.0.6

Environment Variables (.env.example)

DATABASE_URL=mysql+pymysql://fastapi_user:fastapi_password@mysql:3306/fastapi_db
SECRET_KEY=your-fastapi-secret-key
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30

6.3 Simple Python (Python with Nginx)

Pre-Requirements

# Minimal requirements (all files will be created if missing):
├── *.py                  # Any Python files (optional)
├── requirements.txt      # Python dependencies (optional)
└── static/               # Static files directory (optional)

Create New Project

# Create project directory
mkdir my-python-app && cd my-python-app

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Linux/Mac

# Install Flask
pip install flask
pip freeze > requirements.txt

Dependencies Check

• Python installation
• Project directory exists

Generated Files Structure

project-root/
├── Dockerfile              # Python with Flask/WSGI container
├── docker-compose.yml      # Python + Nginx setup
├── nginx/
│   └── conf.d/
│       └── default.conf    # Nginx configuration for Python
├── deploy.sh              # Python deployment script
├── .env.example           # Basic environment variables
├── requirements.txt       # Python web dependencies (generated)
├── app.py                 # Sample Flask application (generated)
├── wsgi.py                # WSGI entry point (generated)
└── static/                # Static files directory

Docker Services

services:
  web: # Python Flask application
  nginx: # Nginx reverse proxy

Generated app.py

from flask import Flask, jsonify, render_template_string

app = Flask(__name__)

@app.route('/')
def hello_world():
    return render_template_string('''
    <!DOCTYPE html>
    <html>
    <head><title>Python Flask App</title></head>
    <body>
        <h1>Hello from Python Flask!</h1>
        <p>Your Flask application is running successfully.</p>
        <a href="/api">Check API</a>
    </body>
    </html>
    ''')

@app.route('/api')
def api():
    return jsonify({"message": "Hello from Python Flask API!"})

@app.route('/health')
def health_check():
    return jsonify({"status": "healthy"})

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000, debug=False)

Generated wsgi.py

from app import app

if __name__ == "__main__":
    app.run()

Generated requirements.txt

Flask>=2.3.0
gunicorn>=20.1.0
python-dotenv>=1.0.0

7. Step-by-Step Usage Guide

Phase 1: Create Your Application

Step 1: Choose Your Technology

Select from the supported project types and create your application using the commands provided in the respective chapters above.

Step 2: Verify Your Setup

# For Node.js projects
npm run dev  # or npm start

# For Python projects
python app.py  # or python manage.py runserver

# For PHP Laravel
php artisan serve

# For Next.js
npm run dev

Phase 2: Generate CI/CD Configuration

Step 1: Navigate to Your Project

cd your-project-directory

Step 2: Run the Generator

npx quick-cicd

Step 3: System Requirements Check

The tool will automatically check:

✓ Checking system requirements...
   Node.js v18.17.0 ✓, Git ✓, Docker ✓

Step 4: Select Project Type

Choose from the interactive menu:

📦 Select your project type:
❯ ⚛️  React with Vite (Frontend SPA)
  🔼 Next.js (Full-stack React Framework)
  🟢 Node.js Backend (Express/NestJS API)
  🐘 PHP Laravel (Backend Framework)
  --- Python Projects ---
  🐍 Python Django (Full-stack Python Framework with MySQL)
  ⚡ Python FastAPI (API Framework with MySQL)
  🔹 Simple Python (Python file with Nginx)

Step 5: Project Validation

The tool validates your project structure:

✓ Validating project configuration...
✓ Project configuration validated successfully

Step 6: Handle Existing Files

If CI/CD files exist, choose an action:

⚠️  Existing files found:
   • Dockerfile (Docker container configuration)
   • docker-compose.yml (Docker Compose orchestration)

How would you like to proceed?
❯ 🔄 Overwrite existing files
  📁 Create with different names (.new extension)
  ❌ Cancel operation

Step 7: File Generation

Watch the progress:

✓ Generating CI/CD files...
   Generating Dockerfile... (1/5)
   Generating docker-compose.yml... (2/5)
   Generating deploy.sh... (3/5)
   Generating .env.example... (4/5)
   Generating ecosystem.config.js... (5/5)

Step 8: Review Generated Files

📁 Generated Files:
─────────────────────────────────────────────────
   ✓ Dockerfile (Docker container configuration)
   ✓ docker-compose.yml (Docker Compose orchestration)
   ✓ ecosystem.config.js (PM2 process manager config)
   ✓ deploy.sh (Deployment automation script)
   ✓ .env.example (Environment variables template)

Step 9: Next Steps

Follow the completion guide:

🎉 SUCCESS!
Your CI/CD configuration has been generated successfully!

📝 Next steps:
──────────────────────────────────────────────────
   1. Review and customize the generated files
   2. Configure environment variables in .env.example
   3. Set up your deployment server
   4. Test locally with Docker: docker-compose up
   5. Build your project: npm run build

Phase 3: Testing and Deployment

Local Testing

# Test with Docker
docker-compose up

# Test individual services
docker-compose up web
docker-compose up mysql

Production Deployment

# Make deploy script executable
chmod +x deploy.sh

# Run deployment
./deploy.sh

Common Issues and Solutions

1. Node.js Version Issues

# Check Node.js version
node --version

# Update Node.js
npm install -g n
n latest

2. Docker Not Running

# Start Docker service
sudo systemctl start docker  # Linux
# Or start Docker Desktop on Windows/Mac

# Check Docker status
docker --version
docker-compose --version

3. Permission Issues (Linux)

# Add user to docker group
sudo usermod -aG docker $USER
# Logout and login again

4. Port Conflicts

# Check what's using the port
lsof -i :3000

# Stop conflicting services
sudo systemctl stop service-name

8. Support & Contact

👨‍💻 Developer Information

• Name: Nazmul Haque
• Email: [email protected]
• LinkedIn: https://www.linkedin.com/in/nazzmulhq/
• Portfolio: https://nazmulhaque.netlify.app/

🆘 Getting Help

1. Check Documentation: Review this documentation first
2. Test Locally: Review generated files for configuration issues
3. Validate Setup: Test locally before deploying
4. Contact Support: Contact developer for specific issues

📚 Additional Resources

• Full Documentation: https://nazmulhaque.netlify.app/quick-cicd/
• GitHub Issues: Report bugs and request features
• Community Support: Join our community for help

🎯 Quick Reference

Essential Commands

# Generate CI/CD files
npx quick-cicd

# Test locally
docker-compose up

# Deploy to production
./deploy.sh

# Check logs
docker-compose logs

File Locations

• Dockerfile: Container configuration
• docker-compose.yml: Service orchestration
• deploy.sh: Deployment script
• .env.example: Environment template
• ecosystem.config.js: PM2 configuration

Run npx quick-cicd to get started with automated CI/CD setup for your project!