Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Improve localhost SSL integration docs [ci skip] #2712

Merged
merged 3 commits into from Sep 25, 2021
Merged

Improve localhost SSL integration docs [ci skip] #2712

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
42d1167
Improve localhost integration docs
dentarg Sep 24, 2021
8917e6f
Apply suggestions from code review
dentarg Sep 25, 2021
e54cfa6
Tweak example
dentarg Sep 25, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
29 changes: 19 additions & 10 deletions README.md
View file
Open in desktop
Expand Up @@ -187,29 +187,38 @@ 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 automatically configures SSL when the [`localhost`] gem is loaded in a `development` environment:

```ruby
# Easiest way, in your Gemfile:
# Add the gem to your Gemfile
group(:development) do
gem 'localhost', require: 'localhost/authority'
end
gem 'localhost'
end

# And require it implicitly using bundler
require "bundler"
Bundler.require(:default, ENV["RACK_ENV"].to_sym)

# Or in your config.ru:
# Alternatively, you can require the gem in config.ru:
require './app'
require 'localhost/authority'
require 'localhost'
run Sinatra::Application
```

...
Additionally, Puma must be listening to an SSL socket:

# Make sure you set up puma to run on an ssl socket:
```shell
$ puma -b 'ssl://localhost:9292' config.ru

# The following options allow you to reach Puma over HTTP as well:
$ puma -b ssl://localhost:9292 -b tcp://localhost:9393 config.ru
```

[`localhost`]: https://github.com/socketry/localhost

#### Controlling SSL Cipher Suites

Expand Down