kdeploy 1.1.9 → 1.2.0

data/README.md

@@ -1,4 +1,5 @@
 # Kdeploy
+
 ```
           _            _
   /\ /\__| | ___ _ __ | | ___  _   _
@@ -9,29 +10,72 @@
 
 ⚡ Lightweight Agentless Deployment Tool
 🚀 Deploy with confidence, scale with ease
-
 ```
 
-A lightweight agentless deployment automation tool written in Ruby.
+A lightweight, agentless deployment automation tool written in Ruby. Kdeploy enables you to deploy applications, manage configurations, and execute tasks across multiple servers using SSH, without requiring any agents or daemons on target machines.
 
 [![Gem Version](https://img.shields.io/gem/v/kdeploy)](https://rubygems.org/gems/kdeploy)
 [![Ruby](https://github.com/kevin197011/kdeploy/actions/workflows/gem-push.yml/badge.svg)](https://github.com/kevin197011/kdeploy/actions/workflows/gem-push.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Table of Contents
+
+- [Features](#-features)
+- [Installation](#-installation)
+- [Quick Start](#-quick-start)
+- [Usage Guide](#-usage-guide)
+- [Configuration](#-configuration)
+- [Advanced Usage](#-advanced-usage)
+- [Error Handling](#-error-handling)
+- [Best Practices](#-best-practices)
+- [Troubleshooting](#-troubleshooting)
+- [Architecture](#-architecture)
+- [Development](#-development)
+- [Contributing](#-contributing)
+- [License](#-license)
 
 ## 🌟 Features
 
-- 🔑 **Agentless Remote Deployment**: Uses SSH for secure remote execution
-- 📝 **Elegant Ruby DSL**: Simple and expressive task definition
-- 🚀 **Concurrent Execution**: Efficient parallel task processing
-- 📤 **File Upload Support**: Easy file and template deployment
-- 📊 **Task Status Tracking**: Real-time execution monitoring
-- 🔄 **ERB Template Support**: Dynamic configuration generation
-- 🎯 **Role-based Deployment**: Target specific server roles
-- 🔍 **Dry Run Mode**: Preview tasks before execution
-- 🎨 **Color-coded Output**: Green for success, Red for errors, Yellow for warnings
+### Core Features
+
+- 🔑 **Agentless Remote Deployment**: Uses SSH for secure remote execution, no agents required
+- 📝 **Elegant Ruby DSL**: Simple and expressive task definition syntax
+- 🚀 **Concurrent Execution**: Efficient parallel task processing across multiple hosts
+- 📤 **File Upload Support**: Easy file and template deployment via SCP
+- 📊 **Task Status Tracking**: Real-time execution monitoring with detailed output
+- 🔄 **ERB Template Support**: Dynamic configuration generation with variable substitution
+- 🎯 **Role-based Deployment**: Target specific server roles for organized deployments
+- 🔍 **Dry Run Mode**: Preview tasks before execution without making changes
+- 🎨 **Color-coded Output**: Intuitive color scheme (Green: success, Red: errors, Yellow: warnings)
+- ⚙️ **Flexible Host Targeting**: Execute tasks on specific hosts, roles, or all hosts
+- 🔐 **Multiple Authentication Methods**: Support for SSH keys and password authentication
+- 📈 **Execution Time Tracking**: Monitor task execution duration for performance analysis
+
+### Technical Features
+
+- **Thread-safe Execution**: Built on `concurrent-ruby` for reliable parallel processing
+- **Custom Error Handling**: Detailed error types for better debugging
+- **Configuration Management**: Centralized configuration with sensible defaults
+- **Extensible Architecture**: Modular design for easy extension
+- **Shell Completion**: Auto-completion support for Bash and Zsh
 
 ## 📦 Installation
 
-Add this line to your application's Gemfile:
+### Requirements
+
+- Ruby >= 2.7.0
+- SSH access to target servers
+- SSH keys or password authentication configured
+
+### Install via RubyGems
+
+```bash
+gem install kdeploy
+```
+
+### Install via Bundler
+
+Add this line to your application's `Gemfile`:
 
 ```ruby
 gem 'kdeploy'
@@ -43,22 +87,24 @@ And then execute:
 bundle install
 ```
 
-Or install it yourself as:
+### Verify Installation
 
 ```bash
-gem install kdeploy
+kdeploy version
 ```
 
+You should see the version information and banner.
+
 ### Shell Completion
 
-To enable command completion, add the following to your shell config:
+Kdeploy automatically configures shell completion during installation. If needed, manually add to your shell config:
 
-For Bash (`~/.bashrc`):
+**For Bash** (`~/.bashrc`):
 ```bash
 source "$(gem contents kdeploy | grep kdeploy.bash)"
 ```
 
-For Zsh (`~/.zshrc`):
+**For Zsh** (`~/.zshrc`):
 ```bash
 source "$(gem contents kdeploy | grep kdeploy.zsh)"
 autoload -Uz compinit && compinit
@@ -75,17 +121,22 @@ Now you can use Tab completion for:
 
 ## 🚀 Quick Start
 
-1. Initialize a new project:
+### 1. Initialize a New Project
 
 ```bash
 kdeploy init my-deployment
 ```
 
-2. Edit the deployment configuration:
+This creates a new directory with:
+- `deploy.rb` - Main deployment configuration file
+- `config/` - Directory for configuration files and templates
+- `README.md` - Project documentation
 
-```ruby
-# deploy.rb
+### 2. Configure Hosts and Tasks
+
+Edit `deploy.rb`:
 
+```ruby
 # Define hosts
 host "web01", user: "ubuntu", ip: "10.0.0.1", key: "~/.ssh/id_rsa"
 host "web02", user: "ubuntu", ip: "10.0.0.2", key: "~/.ssh/id_rsa"
@@ -93,160 +144,886 @@ host "web02", user: "ubuntu", ip: "10.0.0.2", key: "~/.ssh/id_rsa"
 # Define roles
 role :web, %w[web01 web02]
 
-# Define tasks
-# 推荐多行命令用 heredoc（run <<~SHELL）
+# Define deployment task
 task :deploy, roles: :web do
   run <<~SHELL
     sudo systemctl stop nginx
-    echo "Deploying..."
-    sudo systemctl start nginx
+    echo "Deploying application..."
   SHELL
+
   upload_template "./config/nginx.conf.erb", "/etc/nginx/nginx.conf",
     domain_name: "example.com",
     port: 3000
+
+  run "sudo systemctl start nginx"
 end
 ```
 
-3. Run the deployment:
+### 3. Run Deployment
 
 ```bash
-kdeploy execute deploy.rb
+kdeploy execute deploy.rb deploy
 ```
 
-4. Demo:
+## 📖 Usage Guide
+
+### Command Reference
+
+#### `kdeploy init [DIR]`
+
+Initialize a new deployment project.
 
 ```bash
-https://github.com/kevin197011/kdeploy-app
+# Initialize in current directory
+kdeploy init .
+
+# Initialize in named directory
+kdeploy init my-deployment
 ```
 
-## 📖 Usage Guide
+#### `kdeploy execute TASK_FILE [TASK]`
 
-### Task Execution
+Execute deployment tasks from a configuration file.
 
+**Basic Usage:**
 ```bash
 # Execute all tasks in the file
 kdeploy execute deploy.rb
 
 # Execute a specific task
 kdeploy execute deploy.rb deploy_web
+```
+
+**Options:**
+- `--limit HOSTS`: Limit execution to specific hosts (comma-separated)
+- `--parallel NUM`: Number of parallel executions (default: 10)
+- `--dry-run`: Preview mode - show what would be done without executing
+
+**Examples:**
+```bash
+# Preview deployment without executing
+kdeploy execute deploy.rb deploy_web --dry-run
+
+# Execute on specific hosts only
+kdeploy execute deploy.rb deploy_web --limit web01,web02
 
-# Execute with dry run (preview mode)
-kdeploy execute deploy.rb --dry-run
+# Use custom parallel count
+kdeploy execute deploy.rb deploy_web --parallel 5
 
-# Execute on specific hosts
-kdeploy execute deploy.rb --limit web01,web02
+# Combine options
+kdeploy execute deploy.rb deploy_web --limit web01 --parallel 3 --dry-run
+```
+
+#### `kdeploy version`
+
+Show version information.
+
+```bash
+kdeploy version
+```
+
+#### `kdeploy help [COMMAND]`
+
+Show help information.
+
+```bash
+# Show general help
+kdeploy help
 
-# Execute with custom parallel count (default: 10)
-kdeploy execute deploy.rb --parallel 10
+# Show help for specific command
+kdeploy help execute
 ```
 
 ### Host Definition
 
+#### Basic Host Configuration
+
 ```ruby
-# Single host
+# Single host with SSH key
 host "web01",
   user: "ubuntu",
   ip: "10.0.0.1",
   key: "~/.ssh/id_rsa"
 
-# Multiple hosts
+# Host with password authentication
+host "web02",
+  user: "admin",
+  ip: "10.0.0.2",
+  password: "your-password"
+
+# Host with custom SSH port
+host "web03",
+  user: "ubuntu",
+  ip: "10.0.0.3",
+  key: "~/.ssh/id_rsa",
+  port: 2222
+```
+
+#### Host Configuration Options
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `user` | String | Yes | SSH username |
+| `ip` | String | Yes | Server IP address or hostname |
+| `key` | String | No* | Path to SSH private key file |
+| `password` | String | No* | SSH password |
+| `port` | Integer | No | SSH port (default: 22) |
+
+\* Either `key` or `password` is required for authentication.
+
+#### Dynamic Host Definition
+
+```ruby
+# Define multiple hosts programmatically
 %w[web01 web02 web03].each do |name|
   host name,
     user: "ubuntu",
     ip: "10.0.0.#{name[-1]}",
     key: "~/.ssh/id_rsa"
 end
+
+# Define hosts from external source
+require 'yaml'
+hosts_config = YAML.load_file('hosts.yml')
+hosts_config.each do |name, config|
+  host name, **config
+end
 ```
 
 ### Role Management
 
+Roles allow you to group hosts and target them collectively in tasks.
+
 ```ruby
 # Define roles
-role :web, %w[web01 web02]
+role :web, %w[web01 web02 web03]
 role :db, %w[db01 db02]
-role :all, %w[web01 web02 db01 db02]
+role :cache, %w[cache01]
+role :all, %w[web01 web02 web03 db01 db02 cache01]
 
 # Use roles in tasks
 task :deploy_web, roles: :web do
-  # Tasks for web servers
+  # Executes on all web servers
 end
 
 task :backup_db, roles: :db do
-  # Tasks for database servers
+  # Executes on all database servers
+end
+
+# Multiple roles
+task :deploy_all, roles: [:web, :cache] do
+  # Executes on web and cache servers
 end
 ```
 
 ### Task Definition
 
+#### Basic Task
+
 ```ruby
-# Basic task
-task :simple do
+task :hello do
   run "echo 'Hello, World!'"
 end
+```
 
-# Role-based task
-task :deploy, roles: :web do
+#### Role-based Task
+
+```ruby
+task :deploy_web, roles: :web do
+  run "sudo systemctl restart nginx"
+end
+```
+
+#### Host-specific Task
+
+```ruby
+task :maintenance, on: %w[web01] do
   run <<~SHELL
     sudo systemctl stop nginx
+    sudo apt-get update && sudo apt-get upgrade -y
     sudo systemctl start nginx
   SHELL
-  upload "./config/nginx.conf", "/etc/nginx/nginx.conf"
 end
+```
 
-# Host-specific task
-task :maintenance, on: %w[web01] do
-  run <<~SHELL
-    sudo apt-get update
-    sudo apt-get upgrade -y
-  SHELL
+#### Task with Multiple Commands
+
+```ruby
+task :deploy, roles: :web do
+  # Stop service
+  run "sudo systemctl stop nginx"
+
+  # Upload configuration
+  upload "./config/nginx.conf", "/etc/nginx/nginx.conf"
+
+  # Start service
+  run "sudo systemctl start nginx"
+
+  # Verify status
+  run "sudo systemctl status nginx"
 end
 ```
 
+#### Task Options
+
+| Option | Type | Description |
+|-------|------|-------------|
+| `roles` | Symbol/Array | Execute on hosts with specified role(s) |
+| `on` | Array | Execute on specific host(s) |
+
+**Note**: If neither `roles` nor `on` is specified, the task executes on all defined hosts.
+
+### Command Types
+
+#### `run` - Execute Shell Commands
+
+Execute commands on remote servers.
+
+```ruby
+# Single line command
+run "sudo systemctl restart nginx"
+
+# Multi-line command (recommended for complex commands)
+run <<~SHELL
+  cd /var/www/app
+  git pull origin main
+  bundle install
+  sudo systemctl restart puma
+SHELL
+```
+
+**Best Practice**: Use heredoc (`<<~SHELL`) for multi-line commands to improve readability.
+
+#### `upload` - Upload Files
+
+Upload files to remote servers.
+
+```ruby
+upload "./config/nginx.conf", "/etc/nginx/nginx.conf"
+upload "./scripts/deploy.sh", "/tmp/deploy.sh"
+```
+
+**Parameters:**
+- `source`: Local file path
+- `destination`: Remote file path
+
+#### `upload_template` - Upload ERB Templates
+
+Upload and render ERB templates with variable substitution.
+
+```ruby
+upload_template "./config/nginx.conf.erb", "/etc/nginx/nginx.conf",
+  domain_name: "example.com",
+  port: 3000,
+  worker_processes: 4
+```
+
+**Parameters:**
+- `source`: Local ERB template file path
+- `destination`: Remote file path
+- `variables`: Hash of variables for template rendering
+
 ### Template Support
 
-Create an ERB template (`config/nginx.conf.erb`):
+Kdeploy supports ERB (Embedded Ruby) templates for dynamic configuration generation.
+
+#### Creating Templates
+
+Create an ERB template file (e.g., `config/nginx.conf.erb`):
 
 ```erb
-server {
-    listen 80;
-    server_name <%= domain_name %>;
-
-    location / {
-        proxy_pass http://localhost:<%= port %>;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
+user nginx;
+worker_processes <%= worker_processes %>;
+error_log /var/log/nginx/error.log;
+pid /run/nginx.pid;
+
+events {
+    worker_connections <%= worker_connections %>;
+}
+
+http {
+    include /etc/nginx/mime.types;
+    default_type application/octet-stream;
+
+    upstream app_servers {
+        server 127.0.0.1:<%= port %>;
+    }
+
+    server {
+        listen 80;
+        server_name <%= domain_name %>;
+
+        location / {
+            proxy_pass http://app_servers;
+            proxy_http_version 1.1;
+            proxy_set_header Upgrade $http_upgrade;
+            proxy_set_header Connection 'upgrade';
+            proxy_set_header Host $host;
+            proxy_cache_bypass $http_upgrade;
+        }
     }
 }
 ```
 
-Use the template in your task:
+#### Using Templates
 
 ```ruby
 task :deploy_config do
-  upload_template "./config/nginx.conf.erb", "/etc/nginx/sites-available/myapp.conf",
+  upload_template "./config/nginx.conf.erb", "/etc/nginx/nginx.conf",
     domain_name: "example.com",
-    port: 3000
+    port: 3000,
+    worker_processes: 4,
+    worker_connections: 2048
+end
+```
+
+#### Template Features
+
+- Full ERB syntax support
+- Variable substitution
+- Conditional logic
+- Loops and iterations
+- Ruby code execution
+
+### Inventory Block
+
+Use the `inventory` block to organize host definitions:
+
+```ruby
+inventory do
+  host 'web01', user: 'ubuntu', ip: '10.0.0.1', key: '~/.ssh/id_rsa'
+  host 'web02', user: 'ubuntu', ip: '10.0.0.2', key: '~/.ssh/id_rsa'
+  host 'db01', user: 'root', ip: '10.0.0.3', key: '~/.ssh/id_rsa'
+end
+```
+
+## ⚙️ Configuration
+
+### Default Configuration
+
+Kdeploy uses sensible defaults that can be customized:
+
+- **Default Parallel Count**: 10 concurrent executions
+- **SSH Timeout**: 30 seconds
+- **Host Key Verification**: Disabled (for convenience, enable in production)
+
+### Environment Variables
+
+You can override defaults using environment variables:
+
+```bash
+export KDEPLOY_PARALLEL=5
+export KDEPLOY_SSH_TIMEOUT=60
+```
+
+### Configuration File
+
+For project-specific configuration, create a `.kdeploy.yml`:
+
+```yaml
+parallel: 5
+ssh_timeout: 60
+verify_host_key: true
+```
+
+## 🔧 Advanced Usage
+
+### Conditional Execution
+
+Use Ruby conditionals in your deployment files:
+
+```ruby
+task :deploy do
+  if ENV['ENVIRONMENT'] == 'production'
+    run "sudo systemctl stop nginx"
+  end
+
+  upload "./config/nginx.conf", "/etc/nginx/nginx.conf"
+
+  if ENV['ENVIRONMENT'] == 'production'
+    run "sudo systemctl start nginx"
+  end
+end
+```
+
+### Looping Over Hosts
+
+```ruby
+# Execute different commands based on host
+task :custom_setup do
+  @hosts.each do |name, config|
+    if name.start_with?('web')
+      run "echo 'Web server: #{name}'"
+    elsif name.start_with?('db')
+      run "echo 'Database server: #{name}'"
+    end
+  end
+end
+```
+
+### Error Handling in Tasks
+
+```ruby
+task :deploy do
+  run "sudo systemctl stop nginx" || raise "Failed to stop nginx"
+  upload "./config/nginx.conf", "/etc/nginx/nginx.conf"
+  run "sudo systemctl start nginx" || raise "Failed to start nginx"
+end
+```
+
+### Using External Libraries
+
+```ruby
+require 'yaml'
+require 'json'
+
+# Load configuration from external files
+config = YAML.load_file('config.yml')
+
+task :deploy do
+  config['commands'].each do |cmd|
+    run cmd
+  end
 end
 ```
 
+### Task Dependencies
+
+While Kdeploy doesn't have built-in task dependencies, you can achieve this with Ruby:
+
+```ruby
+task :setup do
+  run "echo 'Setting up...'"
+end
+
+task :deploy do
+  # Manually call setup task
+  self.class.kdeploy_tasks[:setup][:block].call.each do |cmd|
+    case cmd[:type]
+    when :run
+      run cmd[:command]
+    when :upload
+      upload cmd[:source], cmd[:destination]
+    end
+  end
+
+  run "echo 'Deploying...'"
+end
+```
+
+## 🚨 Error Handling
+
+### Error Types
+
+Kdeploy provides specific error types for better debugging:
+
+- `Kdeploy::TaskNotFoundError` - Task not found
+- `Kdeploy::HostNotFoundError` - Host not found
+- `Kdeploy::SSHError` - SSH operation failed
+- `Kdeploy::SCPError` - SCP upload failed
+- `Kdeploy::TemplateError` - Template rendering failed
+- `Kdeploy::ConfigurationError` - Configuration error
+- `Kdeploy::FileNotFoundError` - File not found
+
+### Error Output
+
+Errors are displayed with:
+- Red color coding
+- Detailed error messages
+- Host information
+- Original error context
+
+### Handling Errors
+
+```ruby
+# In your deployment file
+begin
+  task :deploy do
+    run "risky-command"
+  end
+rescue Kdeploy::SSHError => e
+  puts "SSH Error: #{e.message}"
+  # Handle error
+end
+```
+
+## 💡 Best Practices
+
+### 1. Use Heredoc for Multi-line Commands
+
+```ruby
+# ✅ Good
+run <<~SHELL
+  cd /var/www/app
+  git pull origin main
+  bundle install
+SHELL
+
+# ❌ Avoid
+run "cd /var/www/app && git pull origin main && bundle install"
+```
+
+### 2. Organize with Roles
+
+```ruby
+# ✅ Good - Use roles for organization
+role :web, %w[web01 web02]
+role :db, %w[db01 db02]
+
+task :deploy_web, roles: :web do
+  # ...
+end
+
+# ❌ Avoid - Hardcoding host names
+task :deploy do
+  # Hard to maintain
+end
+```
+
+### 3. Use Templates for Dynamic Configuration
+
+```ruby
+# ✅ Good - Use templates
+upload_template "./config/nginx.conf.erb", "/etc/nginx/nginx.conf",
+  domain_name: "example.com",
+  port: 3000
+
+# ❌ Avoid - Hardcoding values
+run "echo 'server_name example.com;' > /etc/nginx/nginx.conf"
+```
+
+### 4. Validate Before Deployment
+
+```ruby
+task :deploy do
+  # Validate configuration
+  run "nginx -t" || raise "Nginx configuration is invalid"
+
+  # Deploy
+  upload "./config/nginx.conf", "/etc/nginx/nginx.conf"
+  run "sudo systemctl reload nginx"
+end
+```
+
+### 5. Use Dry Run for Testing
+
+Always test with `--dry-run` before actual deployment:
+
+```bash
+kdeploy execute deploy.rb deploy_web --dry-run
+```
+
+### 6. Organize Files Properly
+
+```
+project/
+├── deploy.rb              # Main deployment file
+├── config/                # Configuration files
+│   ├── nginx.conf.erb     # Templates
+│   └── app.conf           # Static configs
+└── scripts/               # Helper scripts
+    └── deploy.sh
+```
+
+### 7. Version Control
+
+- Commit `deploy.rb` and templates
+- Use `.gitignore` for sensitive files
+- Store secrets in environment variables
+
+### 8. Parallel Execution
+
+Adjust parallel count based on your infrastructure:
+
+```bash
+# For many hosts, increase parallel count
+kdeploy execute deploy.rb deploy --parallel 20
+
+# For limited resources, decrease
+kdeploy execute deploy.rb deploy --parallel 3
+```
+
+## 🔍 Troubleshooting
+
+### Common Issues
+
+#### SSH Authentication Failed
+
+**Problem**: `SSH authentication failed`
+
+**Solutions**:
+1. Verify SSH key path is correct
+2. Check key permissions: `chmod 600 ~/.ssh/id_rsa`
+3. Test SSH connection manually: `ssh user@host`
+4. Verify username and IP address
+
+#### Host Not Found
+
+**Problem**: `No hosts found for task`
+
+**Solutions**:
+1. Verify host names in task match defined hosts
+2. Check role definitions
+3. Verify `--limit` option if used
+
+#### Command Execution Failed
+
+**Problem**: Commands fail on remote server
+
+**Solutions**:
+1. Test commands manually on target server
+2. Check user permissions (may need sudo)
+3. Verify command syntax
+4. Check server logs
+
+#### Template Rendering Error
+
+**Problem**: Template upload fails
+
+**Solutions**:
+1. Verify ERB syntax in template
+2. Check all required variables are provided
+3. Validate template file exists
+4. Test template rendering locally
+
+#### Connection Timeout
+
+**Problem**: SSH connection times out
+
+**Solutions**:
+1. Check network connectivity
+2. Verify firewall rules
+3. Increase timeout in configuration
+4. Check SSH service on target server
+
+### Debug Mode
+
+Enable verbose output by checking the execution output. Kdeploy provides detailed information about:
+- Task execution status
+- Command output
+- Error messages
+- Execution duration
+
+### Getting Help
+
+- Check [GitHub Issues](https://github.com/kevin197011/kdeploy/issues)
+- Review example projects
+- Read the documentation
+- Ask in discussions
+
+## 🏗️ Architecture
+
+### Core Components
+
+- **CLI** (`cli.rb`): Command-line interface using Thor
+- **DSL** (`dsl.rb`): Domain-specific language for task definition
+- **Executor** (`executor.rb`): SSH/SCP execution engine
+- **Runner** (`runner.rb`): Concurrent task execution coordinator
+- **CommandExecutor** (`command_executor.rb`): Individual command execution
+- **CommandGrouper** (`command_grouper.rb`): Command grouping logic
+- **Template** (`template.rb`): ERB template rendering
+- **Output** (`output.rb`): Output formatting and display
+- **Configuration** (`configuration.rb`): Configuration management
+- **Errors** (`errors.rb`): Custom error types
+
+### Execution Flow
+
+1. **Parse Configuration**: Load and parse `deploy.rb`
+2. **Resolve Hosts**: Determine target hosts based on task definition
+3. **Group Commands**: Group commands by type for efficient execution
+4. **Execute Concurrently**: Run tasks in parallel across hosts
+5. **Collect Results**: Gather execution results and status
+6. **Display Output**: Format and display results to user
+
+### Concurrency Model
+
+Kdeploy uses `concurrent-ruby` with a fixed thread pool:
+- Default: 10 concurrent executions
+- Configurable via `--parallel` option
+- Thread-safe result collection
+- Automatic resource cleanup
+
 ## 🔧 Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+### Setup Development Environment
+
+```bash
+# Clone repository
+git clone https://github.com/kevin197011/kdeploy.git
+cd kdeploy
+
+# Install dependencies
+bundle install
+
+# Run tests
+bundle exec rspec
+
+# Run console
+bin/console
+```
+
+### Project Structure
 
-To install this gem onto your local machine, run `bundle exec rake install`.
+```
+kdeploy/
+├── lib/
+│   └── kdeploy/
+│       ├── cli.rb              # CLI interface
+│       ├── dsl.rb              # DSL definition
+│       ├── executor.rb         # SSH/SCP executor
+│       ├── runner.rb           # Task runner
+│       ├── command_executor.rb # Command executor
+│       ├── command_grouper.rb  # Command grouper
+│       ├── template.rb         # Template handler
+│       ├── output.rb           # Output interface
+│       ├── configuration.rb    # Configuration
+│       ├── errors.rb           # Error types
+│       └── ...
+├── spec/                       # Tests
+├── exe/                        # Executables
+├── sample/                     # Example projects
+└── README.md                   # This file
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+bundle exec rspec
+
+# Run specific test file
+bundle exec rspec spec/kdeploy_spec.rb
+
+# Run with coverage
+COVERAGE=true bundle exec rspec
+```
+
+### Building the Gem
+
+```bash
+# Build gem
+gem build kdeploy.gemspec
+
+# Install locally
+gem install ./kdeploy-*.gem
+```
+
+### Code Style
+
+The project uses RuboCop for code style:
+
+```bash
+# Check style
+bundle exec rubocop
+
+# Auto-fix issues
+bundle exec rubocop -a
+```
 
 ## 🤝 Contributing
 
-1. Fork it
-2. Create your feature branch (`git checkout -b feature/my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin feature/my-new-feature`)
-5. Create a new Pull Request
+Contributions are welcome! Please follow these steps:
+
+1. **Fork the repository**
+2. **Create a feature branch**: `git checkout -b feature/my-new-feature`
+3. **Make your changes**: Follow the code style and add tests
+4. **Commit your changes**: Use conventional commit messages
+5. **Push to the branch**: `git push origin feature/my-new-feature`
+6. **Create a Pull Request**: Provide a clear description of changes
+
+### Contribution Guidelines
+
+- Follow existing code style
+- Add tests for new features
+- Update documentation
+- Ensure all tests pass
+- Follow conventional commit format
+
+### Commit Message Format
+
+Follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
+
+## 📚 Examples
+
+### Example Projects
+
+Check out the [example project](https://github.com/kevin197011/kdeploy-app) for a complete deployment setup.
+
+### Common Deployment Scenarios
+
+#### Web Application Deployment
+
+```ruby
+host "web01", user: "deploy", ip: "10.0.0.1", key: "~/.ssh/id_rsa"
+role :web, %w[web01]
+
+task :deploy_app, roles: :web do
+  run <<~SHELL
+    cd /var/www/app
+    git pull origin main
+    bundle install
+    rake db:migrate
+    sudo systemctl restart puma
+  SHELL
+end
+```
+
+#### Database Backup
+
+```ruby
+host "db01", user: "postgres", ip: "10.0.0.10", key: "~/.ssh/id_rsa"
+role :db, %w[db01]
+
+task :backup, roles: :db do
+  run <<~SHELL
+    pg_dump mydb > /tmp/backup_$(date +%Y%m%d).sql
+    gzip /tmp/backup_*.sql
+    aws s3 cp /tmp/backup_*.sql.gz s3://backups/
+    rm /tmp/backup_*.sql.gz
+  SHELL
+end
+```
+
+#### Configuration Management
+
+```ruby
+task :update_config, roles: :web do
+  upload_template "./config/app.yml.erb", "/etc/app/config.yml",
+    environment: "production",
+    database_url: ENV['DATABASE_URL'],
+    redis_url: ENV['REDIS_URL']
+
+  run "sudo systemctl reload app"
+end
+```
 
 ## 📝 License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
-## 🔍 Code of Conduct
+## 🔗 Links
+
+- **GitHub**: https://github.com/kevin197011/kdeploy
+- **RubyGems**: https://rubygems.org/gems/kdeploy
+- **Issues**: https://github.com/kevin197011/kdeploy/issues
+- **Example Project**: https://github.com/kevin197011/kdeploy-app
+
+## 🙏 Acknowledgments
+
+- Built with [Thor](https://github.com/rails/thor) for CLI
+- Uses [net-ssh](https://github.com/net-ssh/net-ssh) for SSH operations
+- Powered by [concurrent-ruby](https://github.com/ruby-concurrency/concurrent-ruby) for concurrency
+
+---
 
-Everyone interacting in the Kdeploy project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/kdeploy/blob/main/CODE_OF_CONDUCT.md).
+**Made with ❤️ for the DevOps community**