Skip to content

Getting Started

Adam Cooke edited this page Oct 18, 2016 · 2 revisions

Installing Procodile

Procodile requires Ruby 2.1 or higher so install this in whatever way you feel most comfortable. It's available in most package managers or you can install it from source pretty quickly. Once installed, you'll need to install the Procodile gem.

$ [sudo] gem install procodile

It isn't recommended that you add procodile to an application's Gemfile if you have one. It is better practice to run Procodile as a system gem on your local machine and/or server.

You can test that Procodile is installed by just running procodile from your shell.

Configuring your application

Procodile knows what processes your applications needs by looking in a Procfile in the root of your application. A Procfile looks like this:

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

It's a simple file which includes a short name for the process followed by the full commanded needed to execute it. There are ways to add lots of additional configuration but we'll cover this later. In most cases Procodile will work just fine with the default configuration and it's a good way to get started.

Starting your application

To start your processes, just run the procodile start command. By default, this will run each of your process types once. If this is your first time running Procodile, it's probably best to start things in development mode to begin with. This will keep Procodile in the foreground so you can see what's going on.

$ procodile start --dev

Your Procfile will now be parsed and the processes started. You'll see any output from STDOUT or STDERR appear as and when it's sent by your processes. Once everything is running, you can press CTRL+C which will terminate all the processes. To run the commands in the background, just go ahead and run the start command without the --dev. When you do this, all the log output you saw previously will be saved into a procodile.log file in the root of your application.

Stopping your application

To stop your proceses, just run the procodile stop command. This will send a TERM signal to each of your applications. You'll see all this happening in your log file.

$ procodile stop

If you find that your processes aren't stopping of their own accord you may need to make adjustments in your application to ensure it terminates whenever it receives the TERM signal.

Restarting your application

Now your application is starting & stopping successfully, we can move onto the fun bit... restarting. Whenever you deploy your application or make changes you may need to restart your processes.

$ procodile restart

By default, this will send all your running processes TERM signal and then wait for them to stop and start new processes in their place. While this is the default and the safest, there are a number of other methods which we'll explore later which help with ensuring zero-downtime deployments.

## Getting the status

Procdile can tell you its current status by running the status command. This will show the status for all processes that are being supervised by Procodile.

$ procodile status

Next steps

That's the basics covered.