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 1 commit
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
32 changes: 22 additions & 10 deletions README.md
View file
Open in desktop
Expand Up @@ -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`:
dentarg marked this conversation as resolved.
Show resolved Hide resolved

```ruby
# Easiest way, in your Gemfile:
# Add the localhost gem to your Gemfile
dentarg marked this conversation as resolved.
Show resolved Hide resolved
group(:development) do
gem 'localhost', require: 'localhost/authority'
end
gem 'localhost'
end

# config.ru:
dentarg marked this conversation as resolved.
Show resolved Hide resolved

# 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:
dentarg marked this conversation as resolved.
Show resolved Hide resolved

# 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
dentarg marked this conversation as resolved.
Show resolved Hide resolved
```

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

#### Controlling SSL Cipher Suites

Expand Down