kamal-easy 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1a04dcf9e1378966de7e532f431dad98804e5e3b9e7c03b71a79c43e8903e5d8
+  data.tar.gz: a57516ce3a7fd5fe6a86fa6768629017eaa9f74f20fecd7f1722a9fabd10c583
+SHA512:
+  metadata.gz: 21aafcdc9097152fde8bc371d02d54cbadec09f57f30b44ba024533f9cd2e9fae66ea4aed103fbb0ed957600d7a8ee511baea6a3236383c5d5f15b3992606e46
+  data.tar.gz: 23c094ba49f1046f04a7ece78e9fd8e3d1e360cba4f5268c92a578c1b7d0afe79a9e3c44888d887fa7cac1fb74247900349baf570a9daebb3bc7d34c5399f761

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/README.md

@@ -0,0 +1,142 @@
+# Kamal Easy
+
+**Unified deployment wrapper for Kamal.**
+Simplifies multi-environment deployments (UAT/Production) and provides unified commands for logs and access to the remote console.
+
+## 🚀 Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'kamal-easy', git: 'https://github.com/overnet/kamal-easy.git'
+# OR locally during development:
+# gem 'kamal-easy', path: '../gems/kamal-easy'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+## ⚙️ Configuration
+
+Run the installer to generate the configuration file:
+
+```bash
+bundle exec kamal-easy install
+```
+
+This will create `config/kamal-easy.yml`. Configure it for your project:
+
+```yaml
+# config/kamal-easy.yml
+environments:
+  uat:
+    env_file: .env.uat
+    credentials_file: config/credentials/uat.yml.enc
+  staging:
+    env_file: .env.staging
+    credentials_file: config/credentials/staging.yml.enc
+  production:
+    env_file: .env.production
+    credentials_file: config/credentials/production.yml.enc
+
+components:
+  backend:
+    path: .
+    kamal_cmd: "bundle exec kamal"
+    container_name_pattern: "your-app-backend-api" # For console access
+    mandatory_files:
+      - config/deploy.yml
+      - Dockerfile
+  frontend:
+    path: ../your-app-frontend
+    kamal_cmd: "kamal"
+    mandatory_files:
+      - config/deploy.yml
+```
+
+### Mandatory Files
+-   **`.env.uat` / `.env.staging` / `.env.production`**: Must exist in the component directory and contain necessary secrets (e.g., `RAILS_MASTER_KEY`).
+-   **`config/deploy.yml`**: Standard Kamal configuration must be present in each component directory.
+-   **`Dockerfile`**: Required for building images.
+
+## 🛠️ Usage
+
+### 1. Deployment (`kamal-easy deploy`)
+Deploy specific components or the entire stack.
+
+**Flags**:
+- `--uat`: Deploy to UAT environment
+- `--staging`: Deploy to Staging environment
+- `--prod`: Deploy to Production environment
+- `--all`: Deploy backend, frontend, and restart DB
+- `--backend`: Deploy only backend
+- `--frontend`: Deploy only frontend
+- `--db`: Restart database accessory
+- `--prune` / `-p`: Prune Docker system (images/containers) before deploy
+
+```bash
+# Deploy EVERYTHING (Backend + Frontend + DB)
+bundle exec kamal-easy deploy --all --prod
+
+# Deploy Specific Component
+bundle exec kamal-easy deploy --backend --uat
+bundle exec kamal-easy deploy --frontend --staging
+bundle exec kamal-easy deploy --db --prod
+```
+
+### 2. Logs (`kamal-easy logs`)
+Stream logs from the remote container.
+
+**Aliases**:
+- `--follow` -> `-f`
+- `--lines` -> `-n`
+- `--grep` -> `-g`
+
+```bash
+# Follow live logs (UAT)
+bundle exec kamal-easy logs --uat -f
+
+# View last 500 lines
+bundle exec kamal-easy logs --prod -n 500
+
+# Grep for errors
+bundle exec kamal-easy logs --prod -g "Error"
+```
+
+### 3. Remote Console (`kamal-easy console`)
+Securely access the remote Rails console.
+
+**Aliases**:
+- `console` -> `c`, `rails_console`
+
+```bash
+# Connect to UAT Console
+bundle exec kamal-easy c --uat
+
+# Connect to Production
+bundle exec kamal-easy rails_console --prod
+```
+
+### 4. Cleanup (`kamal-easy prune`)
+Manage disk usage by removing old versions.
+
+```bash
+# Keep last 3 versions (Default)
+bundle exec kamal-easy prune --uat
+
+# Keep last 5 versions
+bundle exec kamal-easy prune --uat --retain 5
+
+# Hard Cleanup (Aggressive docker system prune)
+# WARNING: Deletes all stopped containers and unused images
+bundle exec kamal-easy prune --uat --hard
+```
+
+## 🏗️ Deployment Architecture (Reference)
+This gem assumes a setup where:
+1.  **Backend & Frontend** are in sibling directories.
+2.  **Zero Downtime** is handled via Kamal Proxy / Traefik (internal port binding).
+3.  **Credentials** are managed via `RAILS_MASTER_KEY`.

data/bin/kamal-easy

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+
+require "kamal_easy"
+require "kamal_easy/cli"
+
+KamalEasy::CLI.start(ARGV)

data/kamal-easy.gemspec

@@ -0,0 +1,27 @@
+
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "kamal_easy/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "kamal-easy"
+  spec.version       = KamalEasy::VERSION
+  spec.authors       = ["Ruslan Vikhor"]
+  spec.email         = ["ruslan@overnet.com"]
+  spec.summary       = "Unified deployment wrapper for Kamal"
+  spec.description   = "Simplifies Kamal deployments with multi-environment support (UAT/Prod) and unified commands for logs and console."
+  spec.homepage      = "https://github.com/overnet/kamal-easy"
+  spec.license       = "MIT"
+  spec.required_ruby_version = ">= 3.3.0"
+
+  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) || f.match(%r{\.gem$}) }
+  end
+  spec.bindir        = "bin"
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "thor", "~> 1.2"
+  # Relaxed dependency to avoid conflicts with Rails apps running dotenv 3.x
+  spec.add_dependency "dotenv", ">= 2.8", "< 4.0"
+end

data/lib/kamal_easy/cli.rb

@@ -0,0 +1,211 @@
+require "thor"
+require "dotenv"
+require "kamal_easy/config"
+
+module KamalEasy
+  class CLI < Thor
+    check_unknown_options!
+
+    class_option :uat, type: :boolean, desc: "Run command in UAT environment", default: false
+    class_option :staging, type: :boolean, desc: "Run command in Staging environment", default: false
+    class_option :prod, type: :boolean, desc: "Run command in Production environment", default: false
+    class_option :production, type: :boolean, desc: "Alias for --prod", default: false
+
+    desc "install", "Generate configuration file"
+    def install
+      config_path = "config/kamal-easy.yml"
+      if File.exist?(config_path)
+        puts "⚠️  #{config_path} already exists."
+      else
+        template = <<~YAML
+          environments:
+            uat:
+              env_file: .env.uat
+              credentials_file: config/credentials/uat.yml.enc
+            staging:
+              env_file: .env.staging
+              credentials_file: config/credentials/staging.yml.enc
+            production:
+              env_file: .env.production
+              credentials_file: config/credentials/production.yml.enc
+
+          components:
+            backend:
+              path: .
+              kamal_cmd: "bundle exec kamal"
+              container_name_pattern: "your-app-backend-api"
+              mandatory_files:
+                - config/deploy.yml
+                - Dockerfile
+            frontend:
+              path: ../your-app-frontend
+              kamal_cmd: "kamal"
+              mandatory_files:
+                - config/deploy.yml
+        YAML
+        File.write(config_path, template)
+        puts "✅ Created #{config_path}"
+      end
+    end
+
+    desc "deploy [COMPONENT]", "Deploy specific component or everything"
+    method_option :all, type: :boolean, desc: "Deploy all components"
+    method_option :backend, type: :boolean, desc: "Deploy backend"
+    method_option :frontend, type: :boolean, desc: "Deploy frontend"
+    method_option :db, type: :boolean, desc: "Restart database"
+    method_option :prune, aliases: "-p", type: :boolean, desc: "Prune Docker before deploy"
+    def deploy
+      config = KamalEasy::Config.load
+      env_key, env_vars = load_environment(config)
+      
+      prune_docker(config, env_vars) if options[:prune]
+
+      if options[:all]
+        deploy_backend(config, env_vars)
+        deploy_frontend(config, env_vars)
+        restart_db(config, env_vars)
+      else
+        deploy_backend(config, env_vars) if options[:backend]
+        deploy_frontend(config, env_vars) if options[:frontend]
+        restart_db(config, env_vars) if options[:db]
+      end
+
+      if !options[:all] && !options[:backend] && !options[:frontend] && !options[:db]
+        help("deploy")
+        exit(1)
+      end
+    end
+
+    desc "logs", "View remote logs"
+    method_option :follow, aliases: "-f", type: :boolean, desc: "Follow logs", default: false
+    method_option :lines, aliases: "-n", type: :numeric, desc: "Number of lines", default: 100
+    method_option :grep, aliases: "-g", type: :string, desc: "Filter pattern"
+    def logs
+      config = KamalEasy::Config.load
+      env_key, env_vars = load_environment(config)
+      
+      backend_config = config.components["backend"]
+      abort "❌ Backend component not configured" unless backend_config
+
+      cmd = "#{backend_config['kamal_cmd']} app logs"
+      cmd += " --lines #{options[:lines]}"
+      cmd += " --follow" if options[:follow]
+      cmd += " --grep '#{options[:grep]}'" if options[:grep]
+
+      puts "📋 Fetching logs from #{env_key.upcase}..."
+      exec_in_dir(backend_config["path"], env_vars, cmd)
+    end
+
+    desc "console", "Access remote Rails console"
+    map ["c", "rails_console"] => :console
+    def console
+      config = KamalEasy::Config.load
+      env_key, env_vars = load_environment(config)
+      
+      backend_config = config.components["backend"]
+      abort "❌ Backend component not configured" unless backend_config
+      
+      container_name = backend_config["container_name_pattern"]
+      
+      cmd = "#{backend_config['kamal_cmd']} server exec -i 'docker exec -it $(docker ps -q -f name=#{container_name} | head -n1) bin/rails console'"
+      
+      puts "🔌 Connecting to #{env_key.upcase} Rails Console..."
+      exec_in_dir(backend_config["path"], env_vars, cmd)
+    end
+
+    desc "prune", "Prune old images and containers"
+    method_option :retain, aliases: "-r", type: :numeric, default: 3, desc: "Number of versions to keep"
+    method_option :hard, type: :boolean, default: false, desc: "Run aggressive docker system prune"
+    def prune
+      config = KamalEasy::Config.load
+      env_key, env_vars = load_environment(config)
+      backend_config = config.components["backend"]
+
+      puts "🧹 Pruning old versions (keeping last #{options[:retain]})..."
+      
+      # Kamal native prune (removes old containers/images managed by Kamal)
+      cmd = "#{backend_config['kamal_cmd']} prune --retain #{options[:retain]}"
+      exec_in_dir(backend_config["path"], env_vars, cmd)
+
+      if options[:hard]
+        puts "🧹 Running hard Docker cleanup..."
+        exec_in_dir(backend_config["path"], env_vars, "#{backend_config['kamal_cmd']} server exec 'docker system prune -a -f --volumes'")
+      end
+    end
+
+    private
+
+    def load_environment(config)
+      is_prod = options[:prod] || options[:production]
+      is_uat = options[:uat]
+      is_staging = options[:staging]
+
+      if [is_prod, is_uat, is_staging].count(true) > 1
+        abort "❌ Error: Cannot target multiple environments simultaneously."
+      end
+
+      unless is_prod || is_uat || is_staging
+        puts "ℹ️  No environment flag provided. Using current process environment..."
+        return [nil, {}] 
+      end
+
+      env_key = if is_prod
+                  "production"
+                elsif is_staging
+                  "staging"
+                else
+                  "uat"
+                end
+
+      env_config = config.env_config(env_key)
+      env_file = env_config["env_file"]
+
+      unless File.exist?(env_file)
+         abort "❌ Error: Environment file #{env_file} not found."
+      end
+
+      puts "📖 Loading configuration from #{env_file}..."
+      [env_key, Dotenv.parse(env_file)]
+    end
+
+    def deploy_backend(config, env_vars)
+      puts "🚀 Deploying Backend..."
+      comp = config.components["backend"]
+      validate_mandatory_files(comp, comp["path"])
+      exec_in_dir(comp["path"], env_vars, "#{comp['kamal_cmd']} deploy")
+    end
+
+    def deploy_frontend(config, env_vars)
+      puts "🚀 Deploying Frontend..."
+      comp = config.components["frontend"]
+      validate_mandatory_files(comp, comp["path"])
+      exec_in_dir(comp["path"], env_vars, "#{comp['kamal_cmd']} deploy")
+    end
+
+    def restart_db(config, env_vars)
+      puts "🔄 Restarting Database..."
+      comp = config.components["backend"]
+      exec_in_dir(comp["path"], env_vars, "#{comp['kamal_cmd']} accessory reboot db")
+    end
+
+    def validate_mandatory_files(component_config, path)
+      return unless component_config["mandatory_files"]
+      
+      Dir.chdir(path) do
+        component_config["mandatory_files"].each do |file|
+          unless File.exist?(file)
+            abort "❌ Error: Mandatory file '#{file}' missing in #{path}"
+          end
+        end
+      end
+    end
+
+    def exec_in_dir(dir, env_vars, cmd)
+      Dir.chdir(dir) do
+        unless system(env_vars, cmd)
+          abort "❌ Command failed: #{cmd}"
+        end
+      end
+    end
+  end
+end

data/lib/kamal_easy/config.rb

@@ -0,0 +1,33 @@
+require "yaml"
+require "thor"
+
+module KamalEasy
+  class Config
+    CONFIG_FILE = "config/kamal-easy.yml"
+
+    def self.load
+      unless File.exist?(CONFIG_FILE)
+        abort "❌ Error: Configuration file #{CONFIG_FILE} not found. Run `kamal-easy install`."
+      end
+      new(YAML.load_file(CONFIG_FILE))
+    end
+
+    def initialize(data)
+      @data = data
+    end
+
+    def environments
+      @data["environments"] || {}
+    end
+
+    def components
+      @data["components"] || {}
+    end
+
+    def env_config(env_name)
+      config = environments[env_name.to_s]
+      abort "❌ Error: Environment '#{env_name}' not defined in #{CONFIG_FILE}" unless config
+      config
+    end
+  end
+end

data/lib/kamal_easy/version.rb

@@ -0,0 +1,3 @@
+module KamalEasy
+  VERSION = "0.0.1"
+end

data/lib/kamal_easy.rb

@@ -0,0 +1,6 @@
+require "kamal_easy/version"
+
+module KamalEasy
+  class Error < StandardError; end
+  # Your code goes here...
+end

metadata

@@ -0,0 +1,87 @@
+--- !ruby/object:Gem::Specification
+name: kamal-easy
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Ruslan Vikhor
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-02-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: dotenv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.8'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.8'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+description: Simplifies Kamal deployments with multi-environment support (UAT/Prod)
+  and unified commands for logs and console.
+email:
+- ruslan@overnet.com
+executables:
+- kamal-easy
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- README.md
+- bin/kamal-easy
+- kamal-easy.gemspec
+- lib/kamal_easy.rb
+- lib/kamal_easy/cli.rb
+- lib/kamal_easy/config.rb
+- lib/kamal_easy/version.rb
+homepage: https://github.com/overnet/kamal-easy
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.3
+signing_key:
+specification_version: 4
+summary: Unified deployment wrapper for Kamal
+test_files: []