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¶