README

An advanced, professional CLI tool to create Laravel microservices from the laravel-microservice-template repository.

Similar to Laravel/Symfony CLI with interactive wizards, dry-run mode, system diagnostics, and service management features.

Features

Core Features (V1)

✅ PSR-4 Compliant - Clean, professional code structure
✅ Single Command - Create a complete microservice instantly
✅ Automatic Configuration - Updates all service-specific files
✅ Docker Ready - Configures docker-compose.yml with unique ports
✅ JWT Keys - Generates RSA key pairs automatically
✅ No Temp Folders - Creates services in your current directory
✅ Clean Architecture - Small, focused classes with single responsibilities

Advanced Features (V2)

✨ Interactive Mode - Smart wizard when service name is omitted
✨ Verbose Mode - Detailed output with -v flag
✨ Dry Run - Preview changes before creating files
✨ Auto Port Detection - Automatically finds available ports
✨ User Config - Personal preferences in ~/.microservice-config
✨ Doctor Command - System health checks and diagnostics
✨ List Services - View all services with status and ports
✨ Open Service - Quick access via VSCode or file explorer
✨ Update Command - Self-update the installer
✨ Version Tracking - .service-version file for each service
✨ Colorful UI - Enhanced console output with tables

Requirements

PHP 8.2 or higher
Composer
Git
Docker (optional, for running services)
OpenSSL (for JWT key generation)

Installation

Global Installation (Recommended)

Install globally via Composer:

composer global require ahmedessam/microservice-installer

Make sure your global Composer bin directory is in your system's PATH:

# Add to ~/.bashrc or ~/.zshrc (Linux/Mac)
export PATH="$HOME/.composer/vendor/bin:$PATH"

# Or add to your environment variables (Windows)

Local Installation

Or install locally in your project:

composer require ahmedessam/microservice-installer --dev

Then use it with:

./vendor/bin/microservice new service-name

Usage

Quick Start

# Check system requirements
microservice doctor

# Create a new microservice (basic)
microservice new auth-service

# Create with custom port
microservice new payment-service --port=8200

# Create with verbose output
microservice new order-service -v

# Preview without creating files
microservice new test-service --dry-run

# Auto-detect next available port
microservice new user-service --auto-port

# Skip JWT key generation
microservice new api-gateway --no-keys

Interactive Mode

Omit the service name to enter interactive wizard:

microservice new
? Enter service name: auth-service
? Enter port number (8100): 8100

Dry Run Mode

Preview all changes before creating files:

microservice new test-service --dry-run --port=9000

Output:

┌─────────────────────────────────────────────────────────┐
│            DRY RUN - NO FILES WILL BE CREATED           │
└─────────────────────────────────────────────────────────┘

Service Configuration:
  • Service Name     : test-service
  • Port             : 9000
  • Template         : https://github.com/...
  • Generate JWT Keys: Yes

Operations to be performed:
  1. Clone template from GitHub
  2. Replace service name in templates
  ...

Available Commands

`microservice new [name]`

Create a new microservice.

Options:

-p, --port: Port number (default: 8100)
-v, --verbose: Show detailed output
--dry-run: Preview changes without creating files
--auto-port: Auto-detect next available port
--no-keys: Skip JWT key generation

Examples:

microservice new auth-service
microservice new payment-service -p 8200 -v
microservice new test-service --dry-run
microservice new api-service --auto-port

`microservice doctor`

Check system requirements and configuration.

microservice doctor

Output shows:

PHP version (>= 8.2)
Required PHP extensions
Composer, Git, Docker availability
Docker daemon status
OpenSSL availability
Write permissions
Template repository accessibility

`microservice list`

List all microservices in current directory.

microservice list

Shows table with:

Service name
Port number
Docker status (Running/Stopped)
Full path

`microservice open <service>`

Open a service in VSCode or file explorer.

microservice open auth-service

`microservice update`

Update the installer to the latest version.

microservice update

Configuration File

Create ~/.microservice-config to customize defaults:

default_port_start: 8100
jwt_auto_generate: true
template_repository: https://github.com/aahmedessam30/laravel-microservice-template
auto_detect_port: false
verbose_mode: false
editor_command: code
custom_replacements: []

Complete Workflow Example

# 1. Check system health
microservice doctor

# 2. Create services
microservice new auth-service -p 8100
microservice new user-service --auto-port
microservice new payment-service -p 8102 -v

# 3. List all services
microservice list

# 4. Open a service
microservice open auth-service

# 5. Start a service
microservice new user-service --port=8000

# Navigate to the service directory
cd user-service

# Install dependencies
composer install

# Generate Laravel application key
php artisan key:generate

# Start Docker containers
docker-compose up -d

# Run migrations
docker-compose exec php-fpm php artisan migrate

# Access the service
curl http://localhost:8000/api/health

What Gets Configured

The installer automatically configures the following:

1. Service Identity

Updates config/service.php with service name and version
Sets SERVICE_NAME in .env and .env.example

2. Application Settings

Updates APP_NAME in .env
Sets unique APP_PORT for the service
Updates APP_URL with the correct port

3. Database Configuration

Creates unique database name: {service-name}_db
Updates DB_DATABASE in .env

4. Cache & Queue

Sets unique CACHE_PREFIX to prevent collisions
Configures Redis with service-specific prefixes

5. Docker Setup

Updates all container names: {service-name}-php, {service-name}-nginx, etc.
Configures unique port mapping
Updates volume names for isolation

6. Composer Package

Updates composer.json name: ahmedessam/{service-name}
Sets appropriate description

7. JWT Keys

Generates RSA key pair (2048-bit)
Creates keys/private.pem and keys/public.pem
Adds keys/ to .gitignore

Service Naming Rules

Service names must:

Contain only lowercase letters, numbers, and hyphens
Not start or end with a hyphen
Be descriptive and meaningful (e.g., auth-service, payment-gateway)

✅ Valid names:

auth-service
user-management
payment-gateway
notification-service

❌ Invalid names:

Auth-Service (uppercase)
-auth-service (starts with hyphen)
auth_service (underscores not allowed)
auth service (spaces not allowed)

Port Management

Recommended port allocation strategy:

Service	Port
Auth Service	8000
User Service	8001
Payment Service	8002
Order Service	8003
Notification Service	8004
...	...

Or use incremental base (e.g., 8100, 8101, 8102...)

Architecture

The installer follows clean architecture principles:

laravel-microservice-installer/
├── bin/
│   └── microservice              # Executable entry point
├── src/
│   ├── Commands/
│   │   └── NewServiceCommand.php # Main command logic
│   ├── Services/
│   │   ├── TemplateCloner.php    # Clones the template repo
│   │   ├── NameReplacer.php      # Replaces placeholders
│   │   ├── DockerConfigurator.php # Updates docker-compose.yml
│   │   ├── EnvConfigurator.php   # Configures .env files
│   │   ├── KeyGenerator.php      # Generates JWT keys
│   │   └── ComposerUpdater.php   # Updates composer.json
│   ├── Support/
│   │   ├── Filesystem.php        # File operations
│   │   └── ConsolePrinter.php    # Console output
│   └── MicroserviceInstaller.php # Application bootstrap
├── composer.json
└── README.md

Design Principles

Single Responsibility: Each class has one focused purpose
Dependency Injection: All dependencies injected via constructor
Strict Typing: All parameters and returns are type-hinted
PSR-4 Autoloading: Proper namespacing and autoloading
Testable: Small, focused methods that are easy to test

Troubleshooting

"Failed to clone template repository"

Ensure you have:

Git installed and in your PATH
Internet connection
Access to GitHub

"Failed to generate private key"

Ensure:

OpenSSL extension is enabled in PHP
You have write permissions in the current directory

"Port must be between 1024 and 65535"

Use a valid port number:

microservice new service-name --port=8000

"Directory already exists"

The service directory already exists. Choose a different name or remove the existing directory:

rm -rf service-name
microservice new service-name

Next Steps After Creation

Install Dependencies
```
cd service-name
composer install
```
Generate Application Key
```
php artisan key:generate
```
Start Docker Containers
```
docker-compose up -d
```

Run Migrations

docker-compose exec php-fpm php artisan migrate

Access API Documentation
```
http://localhost:{port}/api/docs
```
Check Health Endpoint
```
curl http://localhost:{port}/api/health
```

Template Repository

This installer uses the official template:

Repository: aahmedessam30/laravel-microservice-template
Features: Laravel 12, Clean Architecture, Docker, JWT Auth, OpenAPI
Architecture: Action/DTO/Service/Repository pattern

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This installer is open-source software licensed under the MIT license.

Credits

Author: Ahmed Essam
Template: laravel-microservice-template
Inspired by: Laravel Installer

Support

For issues, questions, or contributions:

GitHub Issues: Create an issue
Email: aahmedessam30@gmail.com

Made with ❤️ for Laravel Microservices

ahmedessam / microservice-installer

Maintainers

Details