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

Improve the Linux setup documentation #219

Merged
merged 2 commits into from
Nov 23, 2019
Merged

Improve the Linux setup documentation #219

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0e44e47
Improve the Linux setup documentation
Nov 9, 2019
aba2512
Add more info about trusting certificates
Nov 20, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 48 additions & 9 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,26 +78,65 @@ When puma-dev is installed as a user agent (the default mode), it will log outpu

In the future, puma-dev will provide an integrated console for this log output.

------------
------

## Linux Support

Puma-dev supports Linux but requires additional installation to make all the features work. For example, `-install` and `-setup` flags for Linux are not provided, puma-dev root CA is generated but not installed or trusted.
Puma-dev supports Linux but requires the following additional installation steps to be followed to make all the features work (`-install` and `-setup` flags for Linux are not provided):

### puma-dev root CA

The puma-dev root CA is generated (in `~/.puma-dev-ssl/`), but you will need to install and trust this as a Certificate Authority.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For Chrome:

  1. Settings
  2. Advanced --> Privacy and security
  3. Manage certificates
  4. Open tab Authorities
  5. Import
  6. Select file ~/.puma-dev-ssl/cert.pem

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I decided against putting specific instructions for this step:

  • there are multiple ways to do this (adding to the operating system trust store vs. doing so in a specific browser), and the complexities around which browsers use/do not use the operating system store
  • multiple browsers (should I add instructions for Firefox, Opera, etc)
  • changes that will occur between browser versions.

I will add a bit more details about the options of using the operating system certificate trust store vs. adding directly to the browser which should give enough information to the user to be able to search online for information


### Alternate Domains (.test or similar)
### Domains (.test or similar)

Install the [dev-tld-resolver](https://github.com/puma/dev-tld-resolver) to make domains resolve.
In order for requests to the `.test` (or any other custom) domain to resolve, install the [dev-tld-resolver](https://github.com/puma/dev-tld-resolver), making sure to use `test` (or the custom TLD you want to use) when configuring TLDs.

### Port 80/443 binding

There are 2 options to allow puma-dev to listen on port 80 and 443.
Linux prevents applications from binding to ports lower that 1024 by default. You don't need to bind to port 80/443 to use puma-dev but it makes using the `.test` domain much nicer (e.g. you'll be able to use the domain as-is in your browser rather than providing a port number)

There are 2 options to allow puma-dev to listen on port 80 and 443:

1. Give puma-dev the capabilities directly:
```shell
sudo setcap CAP\_NET\_BIND\_SERVICE=+eip /path/to/puma-dev
```
or
2. Install `authbind`. and invoke puma-dev with it when you want to use it e.g.
```shell
authbind puma-dev -http-port 80 -https-port 443
```

There is a shortcut for binding to 80/443 by passing `-sysbind` to puma-dev when starting, which overrides `-http-port` and `-https-port`.

### Systemd (running puma-dev in the background)

On Linux, puma-dev will not automatically run in the background (as per the MacOS `-install` script); you'll need to [run it in the foreground](#running-in-the-foreground). You can set up a system daemon to start up puma-dev in the background yourself.

1. Create `/lib/systemd/system/puma-dev.service` and put in the following:
```
[Unit]
After=network.target

[Service]
User=$USER
ExecStart=/path/to/puma-dev -sysbind
Restart=on-failure

1. `sudo setcap CAP\_NET\_BIND\_SERVICE=+eip /path/to/puma-dev`
2. Use `authbind`.
[Install]
WantedBy=multi-user.target
```

You don't need to bind to port 80/443 to use puma-dev but obviously it makes using the `.dev` domain much nicer.
Replace `path/to/puma-dev` with an absolute path to puma-dev
Replace the `$USER` variable with the name of the user you want to run under.

There is a shortcut for binding to 80/443 by passing `-sysbind` which overrides `-http-port` and `-https-port`.
2. Start puma-dev using systemd:
```shell
sudo systemctl daemon-reload
sudo systemctl enable puma-dev
sudo systemctl start puma-dev
```

------

Expand Down