README.md

Path: tools/jungle/upstart/README.md
Last Update: Wed Jul 24 14:57:07 -0400 2013

# 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.

[Validate]