ruby-nginx 1.0.0.pre.alpha → 1.0.0.pre.beta.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b353ecaf5dec92d755ac159abf88fc2b921e453985d12ef6be729e2fcd9c2765
-  data.tar.gz: 16c92ddbba0f1e570c3840ccf7bc6564f7da3f333a49f3239155f56ee69857de
+  metadata.gz: 4eb0c324fb8b79dd62fcb04019a2b3a85dcb64f42aec5672fee73a8a222aff77
+  data.tar.gz: ded353048e2e065b6bd3395b5c15299ff2a13056b2bccb974e95eec808b77dcf
 SHA512:
-  metadata.gz: 90db5eb4b5c372b497a0c89ff5d02dde13424ff8dff51a128ade28c55b18ce637584da752b5cb85e3515f2430baefa4852292ecc841e7e453de514c19955bbac
-  data.tar.gz: '039257b96c36d8db7d8476c6b65428bf8d4b68cf5e662e3cb2a9a3e29b4c215b5bda3fe2659b10ae08ce8a80efc1dcdc2acae511b80a9b75b82727dd943c552d'
+  metadata.gz: e1c8b60d5092576ac44959f01e341d0c581e60e1c2900c65868b1c5cf401f0f439a0453ef83deb9941deb6d6d76bba0286d052abac31b7161209a18e0799464c
+  data.tar.gz: 8e9c6495558319fa91d8710abf75d92e85fc688cdd032458d52e3c1a4b1e8c92b09da81dd1135836020f63e65c52890368d2f945187ad259999c13b91033dd43

data/README.md

@@ -1,15 +1,57 @@
 # Ruby NGINX
 
-Utility gem with an added CLI for configuring NGINX with SSL.
+Utility gem with an added CLI for setting up reverse proxies with custom domains. Because sometimes you just don't want to use containers, or your platform doesn't natively run containers without a virtual machine - I'm looking at you - Darwin.
 
-1. ERB for NGINX configuration templating.
-2. Mkcert for SSL certificate generation.
-3. Tried and true NGINX for reverse proxying.
+:heart: ERB for NGINX configuration templating.
 
-This gem is intended to be an aid to your development environment - complemented by [Rails NGINX](https://github.com/bert-mccutchen/rails-nginx). **Don't use this in production.**
+:yellow_heart: Self-signed certificate generation via mkcert for HTTPS.
+
+:green_heart: Tried and true NGINX for reverse proxying, and hosts mapping for DNS.
 
 [![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/M4M76DVZR)
 
+---
+
+### Key Features
+
+The aim of this gem is to be easy to use, while keeping the user in control of their own machine. With Ruby NGINX's automation, you should feel comfortable, informed, and in control of the process.
+
+- Automated installation of NGINX and mkcert that are entirely optional.
+  - You will be prompted before installation. You may reject installation to install NGINX or mkcert on your own terms.
+- Sudo - only when necessary, and on your own terms.
+  - By default, all attempts to configure or interact with NGINX, /etc/hosts, and mkcert, are done without elevated privileges. Sudo is only used when the initial attempt fails with your users privileges.
+  - You will be prompted to accept sudo elevation, and why it is required. Rejection will immediately abort the process.
+- Isolated NGINX configuration.
+  - Your NGINX configuration will automatically be updated to include configuration files from `~/.ruby-nginx/servers`. This ensures a clean separation exists between your personal NGINX configuration and Ruby NGINX's automation.
+- Cross-platform and support for multiple package managers.
+  - macOS - brew
+  - Linux - apt-get, pacman, yum, zypper
+- Complete configuration - everything is configurable. You can even bring your own NGINX config, and if you'd like, your own :beers:.
+
+> [!WARNING]
+>This gem is intended to be an aid to your development environment - complemented by [Rails NGINX](https://github.com/bert-mccutchen/rails-nginx). **Don't use this gem in production.**
+
+---
+
+### Contents
+
+- [Installation](#installation)
+- [Library Usage](#library-usage)
+  - [Adding an NGINX configuration](#adding-an-nginx-configuration)
+  - [Removing an NGINX configuration](#removing-an-nginx-configuration)
+- [CLI Usage](#cli-usage)
+  - [Help](#help)
+  - [Adding an NGINX configuration](#adding-an-nginx-configuration-1)
+  - [Removing an NGINX configuration](#removing-an-nginx-configuration-1)
+- [Development](#development)
+  - [Setup](#setup)
+  - [Lint / Test](#lint--test)
+  - [Debug Console](#debug-console)
+  - [CLI Executable](#cli-executable)
+  - [Release](#release)
+- [Contributing](#contributing)
+- [License](#license)
+
 ## Installation
 
 Install via Bundler:
@@ -22,11 +64,11 @@ Or install it manually:
 gem install ruby-nginx
 ```
 
-## Usage
+## Library Usage
 
-### Library Usage
+### Adding an NGINX configuration
 
-#### Adding an NGINX configuration
+You can pass configuration options directly.
 ```ruby
 Ruby::Nginx.add!(
   # required
@@ -38,11 +80,11 @@ Ruby::Nginx.add!(
   # default: 127.0.0.1
   host: "localhost",
 
-  # default: included template
-  template_path: "$HOME/projects/example-app/nginx.conf.erb",
+  # default: [packaged template]
+  template_path: "~/projects/example-app/nginx.conf.erb",
 
   # default: $PWD
-  root_path: "$HOME/projects/example-app/public",
+  root_path: "~/projects/example-app/public",
 
   # default: false
   ssl: true,
@@ -51,33 +93,64 @@ Ruby::Nginx.add!(
   log: true,
 
   # default: ~/.ruby-nginx/certs/_[DOMAIN].pem
-  ssl_certificate_path: "$HOME/projects/example-app/tmp/nginx/_example.test.pem",
+  ssl_certificate_path: "~/projects/example-app/tmp/nginx/_example.test.pem",
 
   # default: ~/.ruby-nginx/certs/_[DOMAIN]-key.pem
-  ssl_certificate_key_path: "$HOME/projects/example-app/tmp/nginx/_example.test-key.pem",
+  ssl_certificate_key_path: "~/projects/example-app/tmp/nginx/_example.test-key.pem",
 
   # default: ~/.ruby-nginx/logs/[DOMAIN].access.log
-  access_log_path: "$HOME/projects/example-app/log/nginx/example.test.access.log",
+  access_log_path: "~/projects/example-app/log/nginx/example.test.access.log",
 
   # default: ~/.ruby-nginx/logs/[DOMAIN].error.log
-  error_log_path: "$HOME/projects/example-app/log/nginx/example.test.error.log"
+  error_log_path: "~/projects/example-app/log/nginx/example.test.error.log"
 )
 ```
 
-#### Removing an NGINX configuration
+OR you can interact with the configuration object via a block.
+```ruby
+Ruby::Nginx.add! do |config|
+  config.options[:domain] = "example.test"
+  config.options[:port] = 3000
+  # etc.
+end
+```
+
+### Removing an NGINX configuration
+
+You can pass configuration options directly.
 ```ruby
 Ruby::Nginx.remove!(domain: "example.test")
 ```
 
-### CLI Usage
+OR you can interact with the configuration object via a block. However, only domain is used during removal - all other options are ignored.
+```ruby
+Ruby::Nginx.remove! do |config|
+  config.options[:domain] = "example.test"
+end
+```
+
+## CLI Usage
+
+### Help
+
+To print the help text.
+```
+> ruby-nginx help
+Commands:
+  ruby-nginx add -d, --domain=DOMAIN -p, --port=N  # Add a NGINX server configuration
+  ruby-nginx help [COMMAND]                        # Describe available commands or one specific command
+  ruby-nginx remove -d, --domain=DOMAIN            # Remove a NGINX server configuration
+```
+
+### Adding an NGINX configuration
 
-#### Adding an NGINX configuration
 ```
+> ruby-nginx help add
 Usage:
   ruby-nginx add -d, --domain=DOMAIN -p, --port=N
 
 Options:
-  -d,          --domain=DOMAIN                                        # eg. your-app.test
+  -d,          --domain=DOMAIN                                        # eg. example.test
   -p,          --port=N                                               # eg. 3000
   -h,          [--host=HOST]                                          # default: 127.0.0.1
   -r,          [--root-path=ROOT_PATH]                                # default: $PWD
@@ -87,22 +160,62 @@ Options:
   -key-file,   [--ssl-certificate-key-path=SSL_CERTIFICATE_KEY_PATH]  # default: ~/.ruby-nginx/certs/_[DOMAIN]-key.pem
   -access-log, [--access-log-path=ACCESS_LOG_PATH]                    # default: ~/.ruby-nginx/logs/[DOMAIN].access.log
   -error-log,  [--error-log-path=ERROR_LOG_PATH]                      # default: ~/.ruby-nginx/logs/[DOMAIN].error.log
+
+Add a NGINX server configuration
 ```
 
-#### Removing an NGINX configuration
+### Removing an NGINX configuration
+
 ```
+> ruby-nginx help remove
 Usage:
   ruby-nginx remove -d, --domain=DOMAIN
 
 Options:
-  -d, --domain=DOMAIN  # eg. your-app.test
+  -d, --domain=DOMAIN  # eg. example.test
+
+Remove a NGINX server configuration
 ```
 
 ## 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
+
+Install development dependencies.
+```
+./bin/setup
+```
+
+### Lint / Test
+
+Run the Standard Ruby linter, and RSpec test suite.
+```
+bundle exec rake
+```
+
+### Debug Console
+
+Start an interactive Ruby console (IRB).
+```
+./bin/console
+```
+
+### CLI Executable
+
+Run the gem's Thor CLI directly.
+```
+./exe/ruby-nginx
+```
+
+OR build and install the gem to your local machine.
+```
+bundle exec rake install
+ruby-nginx help
+```
+
+### Release
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+A new release will automatically be built and uploaded to RubyGems by a [GitHub Actions workflow](./.github/workflows/gem-push.yml) upon the push of a new Git tag.
 
 ## Contributing
 

data/lib/ruby/nginx/cli.rb

@@ -44,17 +44,16 @@ module Ruby
         }.compact
 
         Ruby::Nginx.add!(**config)
+      rescue Ruby::Nginx::Error => e
+        abort "[Ruby::Nginx] #{e.message}"
       end
 
       desc "remove", "Remove a NGINX server configuration"
       method_option :domain, aliases: "-d", type: :string, required: true, desc: "eg. example.test"
       def remove
         Ruby::Nginx.remove!(domain: options.domain)
-      end
-
-      desc "template", "Copy a NGINX server configuration template"
-      def template
-        copy_file File.expand_path("templates/nginx.conf.erb", __dir__), "nginx.conf.erb"
+      rescue Ruby::Nginx::Error => e
+        abort "[Ruby::Nginx] #{e.message}"
       end
     end
   end

data/lib/ruby/nginx/commands/add_host_mapping.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "terminal_command"
+
+module Ruby
+  module Nginx
+    module Commands
+      class AddHostMapping < TerminalCommand
+        def initialize(host, ip, sudo: false)
+          @host = host
+          @ip = ip
+          @sudo = sudo
+          sudo_reason = "Allow sudo elevation to add \"#{host}\" to /etc/hosts?"
+          cmd = "echo \"#{ip} #{host}\" | #{sudoify("tee -a /etc/hosts", sudo, sudo_reason)}"
+
+          super(cmd:, raise: Ruby::Nginx::ConfigError)
+        end
+
+        def run
+          super
+        rescue Ruby::Nginx::ConfigError
+          raise if @sudo
+
+          # Elevate to sudo and try again.
+          self.class.new(@host, @ip, sudo: true).run
+        end
+      end
+    end
+  end
+end

data/lib/ruby/nginx/commands/add_nginx_config.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "../constants"
+require_relative "../system/safe_file"
+
+module Ruby
+  module Nginx
+    module Commands
+      class AddNginxConfig
+        include Ruby::Nginx::Constants
+
+        def run(name, config)
+          Ruby::Nginx::System::SafeFile.write("#{SERVERS_PATH}/#{name}.conf", config)
+        end
+      end
+    end
+  end
+end

data/lib/ruby/nginx/commands/create_mkcert_certificate.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "terminal_command"
+
+module Ruby
+  module Nginx
+    module Commands
+      class CreateMkcertCertificate < TerminalCommand
+        def initialize(domain, cert_file_path, key_file_path)
+          super(
+            cmd: "mkcert -cert-file #{cert_file_path} -key-file #{key_file_path} #{domain}",
+            raise: Ruby::Nginx::CreateError
+          )
+        end
+      end
+    end
+  end
+end

data/lib/ruby/nginx/commands/install_mkcert.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative "terminal_command"
+require_relative "../system/os"
+
+module Ruby
+  module Nginx
+    module Commands
+      class InstallMkcert < TerminalCommand
+        def initialize
+          super(cmd: resolve_command, raise: Ruby::Nginx::InstallError, printer: :pretty)
+        end
+
+        def run
+          return if installed?
+
+          if yes?("Would you like to install mkcert?")
+            super
+          else
+            raise Ruby::Nginx::AbortError, "mkcert is required to continue. Please install mkcert."
+          end
+        end
+
+        private
+
+        def installed?
+          TTY::Command.new(printer: :null).run!("which mkcert").success?
+        end
+
+        def apt_get_command
+          "sudo apt-get install -y libnss3-tools && " \
+          "curl -L -C - \"https://dl.filippo.io/mkcert/latest?for=linux/amd64\" -o ./mkcert_download && " \
+          "chmod +x ./mkcert_download && " \
+          "sudo mv ./mkcert_download /usr/local/bin/mkcert"
+        end
+
+        def brew_command
+          "brew install mkcert nss"
+        end
+
+        def pacman_command
+          "sudo pacman -Syu nss mkcert"
+        end
+
+        def yum_command
+          "sudo yum install -y nss-tools && " \
+          "curl -L -C - \"https://dl.filippo.io/mkcert/latest?for=linux/amd64\" -o ./mkcert_download && " \
+          "chmod +x ./mkcert_download && " \
+          "sudo mv ./mkcert_download /usr/local/bin/mkcert"
+        end
+
+        def zypper_command
+          "sudo zypper install -y mozilla-nss-tools && " \
+          "curl -L -C - \"https://dl.filippo.io/mkcert/latest?for=linux/amd64\" -o ./mkcert_download && " \
+          "chmod +x ./mkcert_download && " \
+          "sudo mv ./mkcert_download /usr/local/bin/mkcert"
+        end
+
+        def resolve_command
+          send("#{Ruby::Nginx::System::OS.instance.package_manager}_command")
+        end
+      end
+    end
+  end
+end

data/lib/ruby/nginx/commands/install_nginx.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "terminal_command"
+require_relative "../system/os"
+
+module Ruby
+  module Nginx
+    module Commands
+      class InstallNginx < TerminalCommand
+        def initialize
+          super(cmd: resolve_command, raise: Ruby::Nginx::InstallError, printer: :pretty)
+        end
+
+        def run
+          return if installed?
+
+          if yes?("Would you like to install Nginx?")
+            super
+          else
+            raise Ruby::Nginx::AbortError, "Nginx is required to continue. Please install Nginx."
+          end
+        end
+
+        private
+
+        def installed?
+          TTY::Command.new(printer: :null).run!("which nginx").success?
+        end
+
+        def apt_get_command
+          "sudo apt-get install -y nginx"
+        end
+
+        def pacman_command
+          "sudo pacman -Syu nginx"
+        end
+
+        def brew_command
+          "brew install nginx"
+        end
+
+        def yum_command
+          "sudo yum install -y nginx"
+        end
+
+        def zypper_command
+          "sudo zypper install -y nginx"
+        end
+
+        def resolve_command
+          send("#{Ruby::Nginx::System::OS.instance.package_manager}_command")
+        end
+      end
+    end
+  end
+end

data/lib/ruby/nginx/commands/nginx_options.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "terminal_command"
+
+module Ruby
+  module Nginx
+    module Commands
+      class NginxOptions < TerminalCommand
+        def initialize
+          super(cmd: "nginx -V", raise: Ruby::Nginx::Error)
+        end
+
+        def run
+          super
+
+          # nginx -V outputs to stderr
+          format_output(result.stderr)
+        end
+
+        private
+
+        def format_output(output)
+          output.split(/configure arguments: */)[1].split.map(&method(:format_option)).to_h
+        end
+
+        def format_option(option)
+          key_val = option.split("=")
+          [key_val[0], key_val[1] || true]
+        end
+      end
+    end
+  end
+end

data/lib/ruby/nginx/commands/nginx_version.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "terminal_command"
+
+module Ruby
+  module Nginx
+    module Commands
+      class NginxVersion < TerminalCommand
+        def initialize
+          super(cmd: "nginx -v", raise: Ruby::Nginx::Error)
+        end
+
+        def run
+          super
+
+          # nginx -v outputs to stderr
+          Ruby::Nginx::Version.new(result.stderr.match(/\d+\.\d+\.?\d?/).to_s)
+        end
+      end
+    end
+  end
+end

data/lib/ruby/nginx/commands/remove_host_mapping.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative "terminal_command"
+require_relative "../system/os"
+
+module Ruby
+  module Nginx
+    module Commands
+      class RemoveHostMapping < TerminalCommand
+        def initialize(host, sudo: false)
+          @host = host
+          @sudo = sudo
+          @sudo_reason = "Allow sudo elevation to remove \"#{host}\" from /etc/hosts?"
+
+          super(cmd: resolve_command, raise: Ruby::Nginx::ConfigError)
+        end
+
+        def run
+          super
+        rescue Ruby::Nginx::ConfigError
+          raise if @sudo
+
+          # Elevate to sudo and try again.
+          self.class.new(@host, sudo: true).run
+        end
+
+        private
+
+        def darwin_command
+          sudoify("sed -i '' '/#{@host}/d' /etc/hosts", @sudo, @sudo_reason)
+        end
+
+        def linux_command
+          sudoify("sed -i '/#{@host}/d' /etc/hosts", @sudo, @sudo_reason)
+        end
+
+        def resolve_command
+          if Ruby::Nginx::System::OS.instance.darwin?
+            darwin_command
+          else
+            linux_command
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby/nginx/commands/remove_nginx_config.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "../constants"
+require_relative "../system/safe_file"
+
+module Ruby
+  module Nginx
+    module Commands
+      class RemoveNginxConfig
+        include Ruby::Nginx::Constants
+
+        def run(name)
+          Ruby::Nginx::System::SafeFile.rm("#{SERVERS_PATH}/#{name}.conf")
+        end
+      end
+    end
+  end
+end

data/lib/ruby/nginx/commands/setup_mkcert.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative "terminal_command"
+
+module Ruby
+  module Nginx
+    module Commands
+      class SetupMkcert < TerminalCommand
+        def initialize
+          super(cmd: "mkcert -install", raise: Ruby::Nginx::SetupError)
+        end
+      end
+    end
+  end
+end

data/lib/ruby/nginx/commands/setup_nginx.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require_relative "../constants"
+require_relative "../system/nginx"
+require_relative "../system/safe_file"
+require_relative "terminal_command"
+
+module Ruby
+  module Nginx
+    module Commands
+      class SetupNginx < TerminalCommand
+        include Ruby::Nginx::Constants
+
+        INCLUDE_STATEMENT = "include #{File.expand_path(SERVERS_PATH)}/*;"
+        EXTERNAL_INCLUDE_STATEMENTS = [
+          "include /etc/nginx/sites-enabled/\\*;",
+          "include servers/\\*;"
+        ]
+
+        def initialize(sudo: false)
+          @sudo = sudo
+          sudo_reason = "Allow sudo elevation to add \"#{INCLUDE_STATEMENT}\" to NGINX configuration file?"
+          cmd = "echo \"#{new_config}\" | #{sudoify("tee #{config_file_path}", sudo, sudo_reason)}"
+
+          super(cmd:, raise: Ruby::Nginx::SetupError)
+        end
+
+        def run
+          super unless setup?
+        rescue Ruby::Nginx::SetupError
+          raise if @sudo
+
+          # Elevate to sudo and try again.
+          self.class.new(sudo: true).run
+        end
+
+        private
+
+        def setup?
+          config.include?(INCLUDE_STATEMENT)
+        end
+
+        def config_file_path
+          @config_file_path ||= Ruby::Nginx::System::Nginx.options["--conf-path"]
+        end
+
+        def config
+          @config ||= Ruby::Nginx::System::SafeFile.read(config_file_path)
+        end
+
+        def external_include_statement
+          EXTERNAL_INCLUDE_STATEMENTS.each do |statement|
+            match = config.match(/(?<indent>\s*)(?<statement>#{statement})/)
+            return match if match
+          end
+
+          raise Ruby::Nginx::SetupError,
+            "Could not find a suitable place to add the include statement.\n" \
+            "Please add the following line to your NGINX configuration file:\n" \
+            "#{INCLUDE_STATEMENT}"
+        end
+
+        def new_config
+          match = external_include_statement
+          indent = match[:indent]
+          statement = match.to_s
+
+          config
+            .gsub(statement, "#{statement}\n#{indent}#{INCLUDE_STATEMENT}\n")
+            .gsub("\"", "\\\"")
+        end
+      end
+    end
+  end
+end