puma--puma/docs/jungle/upstart/README.md

Puma as a service using Upstart

Manage multiple Puma servers as services on the same box using Ubuntu upstart.

Installation

# Copy the scripts to services directory 
sudo cp puma.conf puma-manager.conf /etc/init

# Create an empty configuration file
sudo touch /etc/puma.conf

Managing the jungle

Puma apps are referenced in /etc/puma.conf by default. Add each app's path as a new line, e.g.:

/home/apps/my-cool-ruby-app
/home/apps/another-app/current

Start the jungle running:

sudo start puma-manager

This script will run at boot time.

Start a single puma like this:

sudo start puma app=/path/to/app

Logs

Everything is logged by upstart, defaulting to /var/log/upstart.

Each puma instance is named after its directory, so for an app called /home/apps/my-app the log file would be /var/log/upstart/puma-_home_apps_my-app.log.

Conventions

• The script expects:
  • a config file to exist under config/puma.rb in your app. E.g.: /home/apps/my-app/config/puma.rb.
  • a temporary folder to put the PID, socket and state files to exist called tmp/puma. E.g.: /home/apps/my-app/tmp/puma. Puma will take care of the files for you.

You can always change those defaults by editing the scripts.

Here's what a minimal app's config file should have

pidfile "/path/to/app/tmp/puma/pid"
state_path "/path/to/app/tmp/puma/state"
activate_control_app

Before starting...

You need to customise puma.conf to:

• Set the right user your app should be running on unless you want root to execute it!
  • Look for setuid apps and setgid apps, uncomment those lines and replace apps to whatever your deployment user is.
  • Replace apps on the paths (or set the right paths to your user's home) everywhere else.
• Uncomment the source lines for rbenv or rvm support unless you use a system wide installation of Ruby.