Getting Started

Installing Procodile

The easiest way to get started is to download a statically compiled procodile binary from the GitHub Releases page. At the moment, downloads are provided for AMD64, ARM64, and Apple Darwin builds.

Once installed, verify it is available by running:

procodile

Creating a Procfile

Procodile reads process definitions from a Procfile in the application root.

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

Each entry defines a process name and the command to run.

You can also create Procfile.options and Procfile.local in the same directory as the Procfile to define additional configuration (Procfile.local overrides Procfile.options).

For more details, see Configuration.

Starting Your Application

procodile start immediately starts normal long-running processes.

Scheduled processes are enabled by start, but they do not run immediately. They run the next time their schedule matches.

If this is your first time running Procodile, it is usually best to start in development mode first. This keeps Procodile in the foreground so you can see what is happening in the logs.

procodile start --dev

To start in the background, similar to Foreman:

procodile start

In this case, the log output you just saw in the terminal will be saved into a procodile.log file in the application root.

For command details, see start command.

Loading an Env File

You can load environment variables from an env file when starting the supervisor:

procodile start --env-file
procodile start --env-file .env.production

If no file is given, .env is used. For precedence rules and file-loading behavior, see Environment Files.

Stopping Processes

To stop all running processes:

procodile stop

To stop a specific process or instance:

procodile stop -p web
procodile stop -p web.2

For scheduled processes, stop -p job disables future runs. If you also want to stop a currently running scheduled instance, stop that instance explicitly, for example procodile stop -p job.3.

For command details, see stop command.

Restarting Processes

To restart configured long-running processes:

procodile restart

To restart only selected process types:

procodile restart -p web,worker

Scheduled processes behave differently: restart reloads and re-enables their schedules, but does not run them immediately.

If you target a running scheduled instance explicitly, for example procodile restart -p job.3, Procodile restarts that instance and also re-enables future scheduling for that job.

For command details, see restart command.

Checking Status

To inspect the current state:

procodile status

For a condensed machine-friendly summary:

procodile status --simple

For command details, see status command.

Reloading Configuration

When you change the Procfile or the options files, use procodile reload to update the running supervisor’s configuration.

procodile reload

Changes to scheduled processes take effect immediately. Long-running processes pick up configuration changes the next time they are restarted.

For command details, see reload command.

Scheduled Processes

Procodile supports scheduled jobs in addition to normal long-running processes.

Example:

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

Scheduled processes are not run immediately by start or restart. They are enabled and then run the next time their schedule matches.

Before relying on a scheduled job, it is often a good idea to run the command once with procodile run to make sure it works without errors.

For details, see Scheduled Processes.

Runtime Issues

Procodile keeps track of important runtime problems such as:

• processes that fail repeatedly
• invalid scheduled cron expressions
• scheduled jobs that repeatedly skip because a previous run is still active

These issues are shown in status output and after CLI commands.

For details, see Runtime Issues and Errors.

Next Steps

• Configuration
• CLI Reference
• Scheduled Processes
• Runtime Issues and Errors