Before starting: Make sure you have the necessary folders and permissions — get more information.

Links: Homepage | Downloads
Dependencies: None
Version: 0.11

Puma-dev is a tool to manage Rack apps in development with Puma.

Get the Code

Switch to /usr/local/src and download the pre-compiled binary.

cd /usr/local/src
curl --remote-name --location https://github.com/puma/puma-dev/releases/download/VERSION/puma-dev-vVERSION-darwin-amd64.zip


Unpack the binary into /usr/local/mac-dev-env/puma-dev-VERSION.

mkdir -p /usr/local/mac-dev-env/puma-dev-VERSION
tar -zxvf puma-dev-vVERSION-darwin-amd64.zip -C /usr/local/mac-dev-env/puma-dev-VERSION

Create a symbolic link to /usr/local/puma-dev.

sudo ln -s mac-dev-env/puma-dev-VERSION /usr/local/puma-dev


Execute the following lines to update your Bash startup script.

echo 'export PATH=/usr/local/puma-dev:$PATH' >> ~/.bash_profile

Load the new shell configurations.

source ~/.bash_profile

Verify the Installation

Verify that you have successfully installed Puma-dev.

puma-dev -V


This configures the settings that require root access on macOS.

sudo puma-dev -setup

Enter your system password to continue.

Create a folder for your applications.

mkdir -p ~/.puma-dev
cd ~/.puma-dev

For each application, add a symlink.

ln -s /path/to/appname

Manual Start/Stop

To start the Puma-dev server.

puma-dev -d localhost

Load the application.


Press CTRL-C to stop the Puma-dev server.

Configure Puma-dev for use with Apache

Configure Puma-dev to start as a service.

puma-dev -install -install-port 9280 -install-https-port 9283 -d localhost

Add the following to the Apache configuration file /usr/local/apache/conf/httpd.conf.

LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_http_module modules/mod_proxy_http.so

<VirtualHost *:80>
  # Passthrough for non-Ruby projects.

<VirtualHost *:80>
  ServerName puma
  ServerAlias *.dev

  ProxyPreserveHost On
  ProxyPass / http://localhost:9280/
  ProxyPassReverse / http://localhost:9280/

Restart Apache.

sudo apachectl restart

Load the application.



If you have any apps that have stopped responding, you can have puma-dev stop all the apps.

puma-dev -stop


To uninstall Puma-dev.

puma-dev -uninstall -d localhost

Then remove the following from your filesystem.

sudo rm /usr/local/puma-dev
rm ~/Library/Logs/puma-dev.log
rm -r /usr/local/mac-dev-env/puma-dev-VERSION
rm -r ~/.puma-dev
rm -r "~/Library/Application Support/io.puma.dev"

Don't forget to remove any Apache and Bash configurations if applicable.