Puma

Puma is a Ruby web server built for speed and parallelism. It is designed for running Rack apps only. It is licensed under the BSD 3-Clause license. This guide explains how to install Puma and run a minimal, custom Ruby application.

Note

For this guide you should be familiar with the basic concepts of

Prerequisites

We’re using Ruby in the stable version 2.5:

[isabell@stardust ~]$ uberspace tools version show ruby
Using 'Ruby' version: '2.5'
[isabell@stardust ~]$

If you want to use Puma with your own domain you need to setup your domain first:

[isabell@stardust ~]$ uberspace web domain list
isabell.uber.space
[isabell@stardust ~]$

Installation

Use gem to install the latest version of Puma:

[isabell@stardust ~]$ gem install puma
Fetching: puma-3.12.0.gem (100%)
Building native extensions. This could take a while...
Successfully installed puma-3.12.0
1 gem installed
[isabell@stardust ~]$

Create a directory, and inside the directory a file rubyapp.ru for the application:

[isabell@stardust ~]$ mkdir ~/puma
[isabell@stardust ~]$ touch ~/puma/rubyapp.ru
[isabell@stardust ~]$

This file is the Rackup file for the application. Add the following content to ~/puma/rubyapp.ru, a simple Hello World application:

class HelloWorld
  def call(env)
    [200, {"Content-Type" => "text/plain"}, ["Hello World"]]
  end
end

run HelloWorld.new

Create the folder for logs:

[isabell@stardust ~]$ mkdir ~/logs/puma
[isabell@stardust ~]$

Configuration

Puma configuration file

Next, create a Puma configuration file:

[isabell@stardust ~]$ touch ~/puma/config.rb
[isabell@stardust ~]$

… and add the following content. Adapt the highlighted lines to your setup.

#!/usr/bin/env puma

# The directory to operate out of.
directory '/home/isabell/puma'

# The path to the rackup file
rackup '/home/isabell/puma/rubyapp.ru'

# Bind Puma to the port
bind 'tcp://0.0.0.0:9000'

# Enable logging
stdout_redirect '/home/isabell/logs/puma/out.log', '/home/isabell/logs/puma/err.log', true

Setup supervisord

Create ~/etc/services.d/puma.ini with the following content. Adapt the highlighted lines to your setup.

[program:puma]
command=/opt/uberspace/etc/isabell/binpaths/ruby/puma --config %(ENV_HOME)s/puma/config.rb
autostart=yes
autorestart=yes

The --config parameter provides the path to the configuration file.

After creating the configuration, tell supervisord to refresh its configuration and start the service:

[isabell@stardust ~]$ supervisorctl reread
SERVICE: available
[isabell@stardust ~]$ supervisorctl update
SERVICE: added process group
[isabell@stardust ~]$ supervisorctl status
SERVICE                            RUNNING   pid 26020, uptime 0:03:14
[isabell@stardust ~]$

Configure web server

Note

puma is running on port 9000.

To make the application accessible from the outside, configure a web backend:

[isabell@stardust ~]$ uberspace web backend set / --http --port <port>
Set backend for / to port <port>; please make sure something is listening!
You can always check the status of your backend using "uberspace web backend list".
[isabell@stardust ~]$

Test

To validate the installation, open a browser and visit isabell.uber.space. If everything is set up correctly, you will see “Hello World”.

Updates

Note

Check the update feed regularly to stay informed about the newest version.

Use gem to update Puma:

[isabell@stardust ~]$ gem update puma
(...)
[isabell@stardust ~]$

Puma

Prerequisites

Installation

Configuration

Puma configuration file

Setup supervisord

Configure web server

Test

Updates

Further Reading