A local .test domain for development with https using Puma-dev (on macOS or Linux)

When you maintain a few projects locally developing against localhost works good enough. npm start or rails s or python manage.py runserver or php -S 127.0.0.1:8000 will boot up a server that binds to a local port and allows you to see your work locally. The advantage of using localhost is that you don’t have to bother with https-traffic as browsers don’t require https for their latest features, but sometimes you need different domains to test and running multiple services distinguished by nothing more than their port numbers can become hard to manage.

To address this problem not only for websites served by the puma server, puma-dev exists. It is a spiritual successor to Sam Stephenson’s Pow, which solved this problem for rack-apps. puma-dev, however, can proxy other servers as well, whether these are written in Javascript, PHP, ruby or other languages; as long as these exposes a port to 127.0.0.1, your local loopback/host you can use puma-dev for it.

Warning

You’re adding a new CA to your browser, a CA that you control. A CA that you may not protect properly. The risk here is that an unknown third party might create a certificate using the private key that you may or may not have properly protected from them. This allows them to generate certificates for any domain you may visit and present this as a valid, protected website. See for more information this issue: https://github.com/puma/puma-dev/issues/215

If you’re just figuring out development or mainly running one application at a time, feel free to continue using localhost using four-digit port numbers, it is not inherently bad.

But if you’re feeling the pain of running multiple applications on carefully selected port-numbers, here might be your answer.

Installing

It starts with installing the code, on mac:

$ brew install puma/puma/puma-dev

Set up

On macOS there is a ready made set up script, for linux it is a bit harder and I’d advise you to check the documentation on github.

First you have to make sure the DNS settings are properly set, additionally a local certificate authority will need to be set up:

sudo puma-dev -setup

Then you’ll want puma-dev to run in the background, serving at port 80 and 443 with the domain .test:

puma-dev -install

Getting Firefox to work

Firefox maintains it own list of trusted certificates. The puma-dev -setup command doesn’t register the

Open your keychain and export the Puma-dev CA certificate as .cer; then import the certificate

Go to preferences (about:preferences), and search for certificates. Then choose show certificates and go to the organisations tab. Here you can import the exported .cer file which will then add the certificate to the trusted list of certificates

Using it

For rack applications (such as Rails)

create a symlink to the application’s root folder with the desired domain name:

$ cd ~/.puma-dev; ln -s /path/to/my/app test

Which will allow you to visit https://test.test and the application will start automatically using rack.

For non-rack applications

$ cd ~/.puma-dev; echo 3000 > test

This will now proxy http://localhost:3000 via https://test.test

Thanks to @gertgoet (or @eval on github/gitlab) to introducing me to puma-dev