Configuration

Procodile uses a Procfile for process definitions, and optional Procfile.options and Procfile.local files in the same directory for additional configuration.

Procfile

The Procfile defines process names and commands:

web: bundle exec puma -C config/puma.rb
worker: bundle exec rake app:worker

Process names must be unique case-insensitively. For example, web and Web are considered duplicates and are not allowed.

Scheduled Processes in Procfile

Procodile supports scheduled processes directly in the Procfile.

Use the __AT__ separator between the process name and a cron expression:

"cleanup__AT__*/10 * * * * *": bundle exec rake cleanup

Notes:

• __AT__ must be uppercase and has two underscores on both sides.
• The cron expression uses five or six space-separated fields:
  • second (this is optional)
  • minute
  • hour
  • day
  • month
  • weekday
• The optional second field is an extra extension beyond traditional five-field crontab syntax.

Schedules can also be defined with processes.<name>.at in the options files. For a fuller guide, see Scheduled Processes.

Options Files

Procfile.options and Procfile.local are collectively referred to here as the options files.

In the options files, process names must match the Procfile entry exactly.

Procfile.options

Procfile.options defines shared configuration that should usually be committed with your application.

# The application name shown in status output and other user-facing messages
app_name: Llama Kit

# The absolute path to the application (optional but useful when working
# with symlinks)
root: /absolute/path/to/app

# The directory that all PIDs will be stored in (default is `pids`)
pid_root: tmp/procodile-pids

# The path to the log file where the Procodile supervisor log will be stored.
# By default this is `procodile.log` in the application root.
log_path: log/procodile.log

# The directory where per-process log files should be stored. If this is set,
# each process can log to a separate file in this directory instead of sharing
# the main procodile.log file.
log_root: log

# The user that the application should run as. If specified, Procodile will
# re-execute itself as this user via sudo, so the supervisor and managed
# processes run as that user.
user: rails

# If your application has a console, configure it here so `procodile console`
# can start it with the application environment already loaded.
console_command: bundle exec rails console

# Environment variables that should be provided to all spawned processes
env:
  RAILS_ENV: production
  SECRET_KEY_BASE: XXX

# Per-process configuration options
processes:
  web:
    # The number of instances of this process that should be started
    # (default is 1)
    quantity: 2

    # The path to store STDOUT/STDERR output for this process (default is to
    # store it in procodile.log, or under log_root if one is configured)
    log_path: log/processes/web.log

    # The file name to use under log_root when log_path is not provided
    log_file_name: webserver.log

    # The mode that should be used when restarting this process
    # (default is term-start). See [[Restart Modes|Restart-Modes]].
    restart_mode: usr2

    # The maximum number of respawns permitted in the respawn window
    # (default is 5)
    max_respawns: 10

    # The size of the respawn window in seconds (default is 3600)
    respawn_window: 300

    # The signal sent to terminate this process (default is TERM)
    term_signal: INT

    # If set, Procodile will automatically assign PORT values to instances of
    # this process, starting from this number
    allocate_port_from: 7000

    # The network protocol used by this process when allocating ports.
    # Supported values are tcp and udp (default is tcp). Proxying requires tcp.
    network_protocol: tcp

    # Configure the proxy listener for this process when supervisor-level proxy
    # mode is enabled. There is no default proxy port. The default proxy
    # address is 127.0.0.1.
    proxy_port: 5050
    proxy_address: 0.0.0.0

    # Environment variables for all instances of this process
    env:
      PORT: 5500

Procfile.local

Procfile.local is intended for machine-local or deployment-specific overrides and is normally not committed.

As above, you don't need to add every option, just ones you wish to override.

processes:
  worker:
    quantity: 4

Scheduled Processes in the Options Files

You can also define schedules in the options files by using at: instead of the special Procfile syntax.

processes:
  cron_cleanup:
    # Run this process on a schedule. The cron expression uses five or six
    # space-separated fields. If present, the optional first field is second.
    # WARNING: if you later remove `at` from an existing scheduled process and
    # reload, Procodile will treat it as a normal long-running process under the
    # current implementation.
    at: "*/10 * * * * *"
    # Randomly delay each scheduled run by up to this many seconds.
    random_delay: 600

This is equivalent to defining the process as cron_cleanup__AT__*/10 * * * * * in the Procfile.

Environment Variables

Global environment variables can be defined in env, and per-process variables can be defined under processes.<name>.env.

When starting the supervisor with --env-file, precedence is: process env > env file > global env. See Environment Files for details.

Server-Wide Configuration

The server-wide configuration allows you to define one (or more) applications which can be invoked without first entering the application's directory. This allows you to run procodile commands from any directory and Procodile will make sure it is executed from the right place.

This file should be placed in /etc/procodile.

root: /opt/appmail/app/current

Multiple Applications

If you have multiple applications on your server, you can define them all in this file. You'll be prompted to choose one when you run procodile.

-
  name: Widgets App
  root: /path/to/widgets/app
-
  name: Another App
  root: /path/to/another/app