puma-dev Documentation

Restart a specific app

To restart a single application without stopping the entire puma-dev server, create a restart.txt file in that application's tmp directory:

touch tmp/restart.txt

Stop all applications

To stop all running applications (useful for resource issues or if an app is stuck), send the USR1 signal to puma-dev using the -stop flag:

puma-dev -stop

To fully configure puma-dev on macOS, follow these steps:

1. Configure DNS settings: This requires root privileges to set up the resolver.

   sudo puma-dev -setup

2. **Install as a background service**: This configures `puma-dev` to run in the background on ports 80 and 443 using the `.test` domain.
   ```bash
puma-dev -install

Custom Ports: If you want to use a port other than 80, use the -install-port flag:

puma-dev -install -install-port 81

Note for v0.2 users: If you previously used version 0.2, run sudo puma-dev -cleanup to remove obsolete firewall rules.

To run puma-dev in the background on Linux, create a systemd service file at /lib/systemd/system/puma-dev.service:

[Unit]
After=network.target

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

[Install]
WantedBy=multi-user.target

Steps to activate:

1. Replace /path/to/puma-dev with the absolute path to your binary.
2. Replace $USER with your actual username.
3. Run the following commands:

sudo systemctl daemon-reload
sudo systemctl enable puma-dev
sudo systemctl start puma-dev

Note: If using SELinux, you may need to run restorecon /path/to/puma-dev.

To make an application available via puma-dev, you must symlink its directory into the puma-dev directory (which defaults to ~/.puma-dev).

You can do this manually using ln -s or use the built-in helper command puma-dev link.

Manual method:

cd ~/.puma-dev
ln -s /path/to/your/app appname

Helper method:

puma-dev link [-n name] [dir]

Once linked, if you link a directory named test, the app will be accessible at test.test.

Since Linux restricts binding to ports below 1024, use one of these two methods to allow puma-dev to use port 80/443:

Option 1: Use Capabilities

Grant the binary the CAP_NET_BIND_SERVICE capability:

sudo setcap CAP\_NET\_BIND\_SERVICE=+eip /path/to/puma-dev

Option 2: Use authbind

Install authbind and invoke puma-dev with it:

authbind puma-dev -http-port 80 -https-port 443

Shortcut: You can use the -sysbind flag when starting puma-dev to automatically override -http-port and -https-port to 80 and 443 respectively.

authbind puma-dev -http-port 80 -https-port 443
# OR
puma-dev -sysbind

To remove puma-dev, run:

puma-dev -uninstall

Important: If you provided custom options to the -setup command (e.g., -d test:localhost), you must pass those same options to the -uninstall command. Failure to do so may leave orphaned entries in /etc/resolver/*.

Before installing puma-dev, ensure the puma gem is installed in your application's Gemfile.

You can install puma-dev using one of the following methods:

Homebrew (macOS or GNU/Linux)

brew install puma/puma/puma-dev

Pre-built Binaries

Download binaries for macOS and Linux from the GitHub releases page.

Build from Source

Ensure go is installed, then run:

go get github.com/puma/puma-dev/...
cd $GOPATH/src/github.com/puma/puma-dev/
make && make install

# Gemfile
gem 'puma'

On Linux, you must manually trust the puma-dev root CA generated in ~/.puma-dev-ssl/. First, start puma-dev to ensure ~/.puma-dev-ssl/cert.pem is generated.

Arch Linux, Fedora (p11-kit)

# convert from PEM to DER
openssl x509 -in ~/.puma-dev-ssl/cert.pem -outform der -out ~/.puma-dev-ssl/cert.crt

# store certificate as an anchor in the trust policy store
sudo trust anchor --store ~/.puma-dev-ssl/cert.crt

# verify
trust list --filter=ca-anchors | grep -i -C2 Puma-dev

Debian, Ubuntu

sudo mkdir -p /usr/local/share/ca-certificates
sudo cp ~/.puma-dev-ssl/cert.pem /usr/local/share/ca-certificates/puma-dev-pem.crt
sudo update-ca-certificates

To implement the Creative Theme template in your existing Jekyll project, follow these steps:

1. Configure site settings: Update your _config.yml file with your specific project information.
2. Customize layout: Modify _layouts/front.html to reorder or remove sections according to your design preferences.

When FindAppByDomainName or lookupApp is called, AppPool follows this logic:

1. Check Memory: If the app is already in the apps map, it returns the existing instance.
2. Path Resolution: It looks for a directory or symlink at Dir/name.
3. Subdomain Stripping: If no match is found, it strips subdomains (e.g., sub.app.test becomes app.test) and tries again.
4. Launch vs Proxy:
   • If the path is a directory, it calls LaunchApp, which boots a Puma server using a Unix socket.
   • If the path is a file, it calls readProxy, which treats the file as a configuration containing a destination address (e.g., a port or a URL) to proxy requests to.
5. Fallback: If no match is found after stripping subdomains, it attempts to find an app named default.