From 42d116728e8181d36dc9a60654620e35fb06f1c9 Mon Sep 17 00:00:00 2001 From: Patrik Ragnarsson Date: Fri, 24 Sep 2021 02:38:54 +0200 Subject: [PATCH 1/3] Improve localhost integration docs Close https://github.com/puma/puma/issues/2706 --- README.md | 32 ++++++++++++++++++++++---------- 1 file changed, 22 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 46f6ccb396..dc7f5bc4a4 100644 --- a/README.md +++ b/README.md @@ -187,29 +187,41 @@ Need a bit of security? Use SSL sockets: ``` $ puma -b 'ssl://127.0.0.1:9292?key=path_to_key&cert=path_to_cert' ``` -#### Self-signed SSL certificates (via _localhost_ gem, for development use): +#### Self-signed SSL certificates (via the [`localhost`] gem, for development use): -Puma supports [localhost](https://github.com/socketry/localhost) gem for self-signed certificates. This is particularly useful if you want to use Puma with SSL locally, and self-signed certificates will work for your use-case. Currently, `localhost-authority` can be used only in MRI. +Puma supports the [`localhost`] gem for self-signed certificates. This is particularly useful if you want to use Puma with SSL locally, and self-signed certificates will work for your use-case. Currently, the integration can only be used in MRI. -To use [localhost](https://github.com/socketry/localhost), you have to `require "localhost/authority"`: +Puma will automatically configure SSL if you require the [`localhost`] gem when running in environment `development`: ```ruby -# Easiest way, in your Gemfile: +# Add the localhost gem to your Gemfile group(:development) do - gem 'localhost', require: 'localhost/authority' -end + gem 'localhost' +end + +# config.ru: + +# Require it implicitly using bundler +require "bundler" +Bundler.require(:default, ENV["RACK_ENV"].to_sym) -# Or in your config.ru: +# Or require it explicitly require './app' -require 'localhost/authority' +require 'localhost' run Sinatra::Application +``` -... +You also need to make sure Puma listens to an SSL socket: -# Make sure you set up puma to run on an ssl socket: +```shell $ puma -b 'ssl://localhost:9292' config.ru + +# You can still have Puma being reachable over HTTP by repeating +# the -b flag (tcp://), but you need to use a different port: +$ puma -b ssl://localhost:9292 -b tcp://localhost:9393 config.ru ``` +[`localhost`]: https://github.com/socketry/localhost #### Controlling SSL Cipher Suites From 8917e6f940da936cef90a118020176f6fe9d92f1 Mon Sep 17 00:00:00 2001 From: Patrik Ragnarsson Date: Sat, 25 Sep 2021 17:47:32 +0200 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: Jacob Herrington --- README.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index dc7f5bc4a4..e3ad84427b 100644 --- a/README.md +++ b/README.md @@ -191,15 +191,15 @@ $ puma -b 'ssl://127.0.0.1:9292?key=path_to_key&cert=path_to_cert' Puma supports the [`localhost`] gem for self-signed certificates. This is particularly useful if you want to use Puma with SSL locally, and self-signed certificates will work for your use-case. Currently, the integration can only be used in MRI. -Puma will automatically configure SSL if you require the [`localhost`] gem when running in environment `development`: +Puma automatically configures SSL when the [`localhost`] gem is loaded in a `development` environment: ```ruby -# Add the localhost gem to your Gemfile +# Add the gem to your Gemfile group(:development) do gem 'localhost' end -# config.ru: +# Alternatively, you can require the gem in config.ru: # Require it implicitly using bundler require "bundler" @@ -211,13 +211,12 @@ require 'localhost' run Sinatra::Application ``` -You also need to make sure Puma listens to an SSL socket: +Additionally, Puma must be listening to an SSL socket: ```shell $ puma -b 'ssl://localhost:9292' config.ru -# You can still have Puma being reachable over HTTP by repeating -# the -b flag (tcp://), but you need to use a different port: +# The following options allow you to reach Puma over HTTP as well: $ puma -b ssl://localhost:9292 -b tcp://localhost:9393 config.ru ``` From e54cfa6f9aa8b5ab14d27cf721d16312c91ae72a Mon Sep 17 00:00:00 2001 From: Patrik Ragnarsson Date: Sat, 25 Sep 2021 17:51:58 +0200 Subject: [PATCH 3/3] Tweak example [ci skip] --- README.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index e3ad84427b..0dcb10ce7c 100644 --- a/README.md +++ b/README.md @@ -199,13 +199,11 @@ group(:development) do gem 'localhost' end -# Alternatively, you can require the gem in config.ru: - -# Require it implicitly using bundler +# And require it implicitly using bundler require "bundler" Bundler.require(:default, ENV["RACK_ENV"].to_sym) -# Or require it explicitly +# Alternatively, you can require the gem in config.ru: require './app' require 'localhost' run Sinatra::Application