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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 151e248fb2678159f70e8175be1ce25f180dbe4b0d0c53d1296479c52c0a562a
-  data.tar.gz: cf941023b67ac13deb0d7d1ac00532a3d7ea1db3ad04bc4bdab9b285136ec9ec
+  metadata.gz: b509ef92a5f9976f4a3861fef1049fd3d2002cc28600292da5221898508712b7
+  data.tar.gz: a2dfd4812dfedbfed4d50c0d03b930fbd8d37c3eae58d31ec9e3f6ce94fb98a9
 SHA512:
-  metadata.gz: 195e2ee3c84a1bf29f6d67dc77c69e83a62bb56702564fbde5a2821ae28ce00a216bfdc6c2afe75b2e075de9981ac77b517aa9bbb1fb204073b2d3c5a8f44f7c
-  data.tar.gz: a09e3c8ec74a32ac165802e8d0bd202d4b44c871f436e7a31a859d0dabd06f9732397074c1abcf0ad6a46cc24aee0c189aa205907d84685f8d7ac73271a50d60
+  metadata.gz: f2f8e5d2cd168828389987d512b4fc44000b0556ffff35c131f3a16c716fed5ea6a4292099e6d8106be725ec1c28fb0b0dd1a96423193440757e1b381eb2713f
+  data.tar.gz: 01f238f9c4e310ff12f41d19dd44ebbf319d040ebb1c95f8cd0dc5d14a700f8e7b573f75f0016377105f14668e33544114c86a714867f4d8bdca199781435589

data/README.md

@@ -1,15 +1,39 @@
 # Rails NGINX
 
-Automatically configure NGINX with SSL upon boot for Rails applications.
+Rails Puma plugin convenience wrapper for Ruby NGINX. Take a look at the [Ruby NGINX project documentation](https://github.com/bert-mccutchen/ruby-nginx) for more in depth details.
 
-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. **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)
 
+---
+
+> [!WARNING]
+>This gem is intended to be an aid to your development environment - powered by [Ruby NGINX](https://github.com/bert-mccutchen/ruby-nginx). **Don't use this gem in production.**
+
+---
+
+### Contents
+
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Basic Usage](#basic-usage)
+  - [Default Configuration](#default-configuration)
+  - [Advanced Usage](#advanced-usage)
+    - [Multiple Configurations](#multiple-configurations)
+    - [Inheriting Configurations](#inheriting-configurations)
+- [Development](#development)
+  - [Setup](#setup)
+  - [Lint / Test](#lint--test)
+  - [Debug Console](#debug-console)
+  - [Release](#release)
+- [Contributing](#contributing)
+- [License](#license)
+
 ## Installation
 
 Install via Bundler:
@@ -24,44 +48,141 @@ gem install rails-nginx
 
 ## Usage
 
-### config/puma.rb
-```ruby
-port ENV.fetch('PORT') { 3000 } unless Rails.env.development?
+### Basic Usage
+
+Add the Puma plugin to your configuration, and limit it to your development environment.
 
+**config/puma.rb**
+```ruby
 plugin :rails_nginx if Rails.env.development?
+```
 
-# All configuration is entirely optional, the following blocks are not required.
-rails_nginx_config(:primary) do |config|
-  config[:domain] = 'route1.spline-reticulator.test' # default eg. rails-app-name.test
-  config[:host] = '0.0.0.0' # default '127.0.0.1'
-  config[:root_path] = './public' # default `Rails.public_path`
-  config[:ssl] = false # default true
-  config[:log] = false # default true
+> [!IMPORTANT]
+> **If you skip this, NGINX reverse proxy will have a randomized port while Puma will not. The reverse proxy will not work.**
+>
+> Puma's `port` configuration option makes it impossible for Rails NGINX to assign a random open port back to Puma.
+>
+> To fix this issue, simply remove it from our Puma configuration.
+>
+> **config/puma.rb**
+> ```ruby
+> port ENV.fetch("PORT") { 3000 }
+> ```
+>
+> OR simply disable it in your development environment:
+> ```ruby
+> port ENV.fetch("PORT") { 3000 } unless Rails.env.development?
+> ```
+>
+> OR always manually provide an open port when starting Rails:
+> ```
+> ./bin/rails server -p 3001
+> ```
+
+### Default Configuration
+By default, Rails NGINX will configure [Ruby NGINX](https://github.com/bert-mccutchen/ruby-nginx) with the following options. For the examples, pretend I have an application called "HelloWorld".
+
+| Option | Default | Example |
+|---|---|---|
+| `domain` | Your rails app name as dashes, with the test TLD. | `hello-world.test` |
+| `host` | `127.0.0.1` | |
+| `root_path` | `Rails.public_path` | `/home/bert/hello_world/public` |
+| `ssl` | `true` | |
+| `log` | `true` | |
+| `ssl_certificate_path` | `Rails.root` + `tmp/nginx/_[DOMAIN].pem` | `/home/bert/hello_world/tmp/nginx/_hello-world.test.pem` |
+| `ssl_certificate_key_path` | `Rails.root` + `tmp/nginx/_[DOMAIN]-key.pem` | `/home/bert/hello_world/tmp/nginx/_hello-world.test-key.pem` |
+| `access_log_path` | `Rails.root` + `log/nginx/[DOMAIN].access.log` | `/home/bert/hello_world/log/hello-world.test.access.log` |
+| `error_log_path` | `Rails.root` + `log/nginx/[DOMAIN].error.log` | `/home/bert/hello_world/log/hello-world.test.error.log` |
+
+### Advanced Usage
+
+You can override all the default values and provide your own configuration. Rails NGINX will use your configuration automatically if one is present. Default values are retained if not overridden.
+
+**config/puma.rb**
+```ruby
+rails_nginx_config do |config|
+  config[:domain] = "example.test"
+  config[:host] = "localhost"
+  # etc.
+end
+```
+
+#### Multiple Configurations
+
+Let's say you have a multi-tenant Rails application, and you want to simulate the application running behind two separate domains in your development environment. No problem, Rails NGINX can support multiple configurations, no matter how wildly different they may be.
+
+**config/puma.rb**
+```ruby
+rails_nginx_config(:work) do |config|
+  config[:domain] = "work.todo-list.test"
+  config[:ssl] = true
+  config[:log] = true
 
-  # default location Rails.root + tmp/nginx/
-  config[:ssl_certificate_path] = './tmp/certs/_spline-reticulator.test.pem'
-  config[:ssl_certificate_key_path] = './tmp/certs/_spline-reticulator-key.test.pem'
+  config[:ssl_certificate_path] = "~/work/my-cert.pem"
+  config[:ssl_certificate_key_path] = "~/work/my-cert-key.pem"
 
   # default location Rails.root + log/nginx/
-  config[:access_log_path] = './log/route1.nginx.access.log'
-  config[:error_log_path] = './log/route1.nginx.error.log'
+  config[:access_log_path] = "~/work/logs/todo-list.access.log"
+  config[:error_log_path] = "~/work/logs/todo-list.error.log"
+end
+
+rails_nginx_config(:home) do |config|
+  config[:domain] = "home.todo-list.test"
+  config[:ssl] = false
+  config[:log] = false
 end
+```
+
+#### Inheriting Configurations
 
-# You can define multiple configurations and all will be created on puma boot.
-rails_nginx_config(:secondary) do |config|
-  config.merge!(rails_nginx_config(:primary))
+Since Rails NGINX configurations are a simple Ruby Hash, you can merge configurations to prevent needless duplication. This is possible because Rails NGINX allows you to read back previously defined configurations.
 
-  config[:domain] = 'route2.spline-reticulator.test'
-  config[:access_log_path] = './log/route2.nginx.access.log'
-  config[:error_log_path] = './log/route2.nginx.error.log'
+**config/puma.rb**
+```ruby
+rails_nginx_config(:kids) do |config|
+  config.merge!(rails_nginx_config(:home))
+
+  config[:domain] = "kids.todo-list.test"
+  config[:log] = true
 end
 ```
 
 ## 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
+```
+
+#### Generating a new Dummy server
+
+There's a built-in executable if you'd like to generate a new Dummy server to upgrade the regression tests to work with the latest version of Rails.
+
+This executable will delete the current `spec/dummy` directory, update the `rails` gem to the latest version, and generate a new `spec/dummy` application using the options defined in the `.dummy.railsrc` file.
+```
+./bin/dummy
+```
+
+### Debug Console
+
+Start an interactive Ruby console (IRB).
+```
+./bin/console
+```
+
+### Release
+
+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.
 
-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).
 
 ## Contributing
 

data/lib/rails/nginx/version.rb

@@ -2,6 +2,6 @@
 
 module Rails
   module Nginx
-    VERSION = "1.0.0-alpha.1"
+    VERSION = "1.0.0-beta"
   end
 end

data/lib/rails/nginx.rb

@@ -2,7 +2,7 @@
 
 require "socket"
 require "ruby/nginx"
-require_relative "./nginx/version"
+require_relative "nginx/version"
 
 module Rails
   module Nginx
@@ -17,13 +17,17 @@ module Rails
 
       config = Ruby::Nginx.add!(options.reverse_merge(defaults(options)), &block)
 
-      puts start_message(config.options) # rubocop:disable Rails/Output
+      puts start_message(config.options)
+    rescue Ruby::Nginx::Error => e
+      abort "[Ruby::Nginx] #{e.message}"
     end
 
     def self.stop!(options = {}, &block)
       return unless rails_server?
 
       Ruby::Nginx.remove!(options.reverse_merge(defaults(options)), &block)
+    rescue Ruby::Nginx::Error => e
+      abort "[Ruby::Nginx] #{e.message}"
     end
 
     private

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rails-nginx
 version: !ruby/object:Gem::Version
-  version: 1.0.0.pre.alpha.1
+  version: 1.0.0.pre.beta
 platform: ruby
 authors:
 - Bert McCutchen
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-11-22 00:00:00.000000000 Z
+date: 2025-02-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: puma
@@ -74,7 +74,7 @@ metadata:
   source_code_uri: https://github.com/bert-mccutchen/rails-nginx
   changelog_uri: https://github.com/bert-mccutchen/rails-nginx/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -90,7 +90,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.5.22
-signing_key: 
+signing_key:
 specification_version: 4
 summary: Automatic NGINX+SSL configuration for Rails.
 test_files: []