The 'passenger' command

The passenger command starts or stops a Passenger server in Standalone mode. In this section we will teach you how to use this command.

Table of contents

Starting a server

passenger is the most basic command, and is often used during development. If you have read the 5 minute quickstart then you have already encountered this command. Throughout this basics tutorial, we will encounter this command often.

You begin using Passenger Standalone by starting a Passenger Standalone server. This can be done with the passenger start command.

$ bundle exec passenger start
======= Phusion Passenger Standalone web server started =======
PID file: /Users/phusion/myapp/tmp/pids/passenger.3000.pid   1
Log file: /Users/phusion/myapp/log/passenger.3000.log        2
Environment: development                     3
Accessible via: http://0.0.0.0:3000/         4

You can stop Phusion Passenger Standalone by pressing Ctrl-C.
===============================================================

During startup, Passenger prints its runtime parameters to the console. There are several things you see here:

Passenger has created a PID file. The PID file contains the process ID of the Passenger instance, and allows other passenger subcommands to know which process to operate on.
Passenger has created a log file. We will talk about logging later.
Passenger has started your app under the development environment. This means that it has set the environment variables RAILS_ENV and RACK_ENV to the value development.

Various Ruby web frameworks – in particular Rails – use the value of one of these environment variables to adjust their behavior. 4. Passenger is serving your app on http://0.0.0.0:3000/.

If you go to http://0.0.0.0:3000/, you will see your application:

$ curl http://0.0.0.0:3000/
...your app's front page HTML...

All of these parameters can be customized. We will talk about customization later.

You can also use "bundle exec rails server"

If you use Rails, then you can also run bundle exec rails server. As long as you have the above Gemfile entry, that command will start a Passenger-based server.

Logs

Passenger itself logs things. The application itself may also log things. Here we will describe how logs are handled.

You have learned that Passenger Standalone has a log file. Your application probably logs things to a log file. For example, Rails apps log to log/development.log when run in development mode. These are two distinct log files: the Passenger log file is not the application log file.

Your application may also print to stdout or stderr. Passenger also considers these messages as logs.

Passenger handles all of these logs as follows:

Passenger's own logs are printed to the Passenger log file.
Anything the application logs to its log file, will end up there only, not in the Passenger log file.
Anything the application prints to stdout and stderr, are printed to the Passenger log file.
Passenger's own logs, the application log file, and anything the application prints to stdout and stderr, are printed to the terminal.

There is just one caveat here. Passenger can only print the application log file to the terminal, if the log file is named log/<ENVIRONMENT NAME>.log. This is true for most Rails apps, at least.

Stopping the server

If you stop Passenger, Passenger will stop your app.

There are two ways to stop the server. The first is by pressing Ctrl-C in the terminal. The second way is by running passenger stop.

Ctrl-C

Let us try out the Ctrl-C method. Go to the terminal where the Passenger server was started, and press Ctrl-C there. You should see that it stops.

# This is what you typed before:
$ bundle exec passenger start
...

# Now press Ctrl-C:
^C
Stopping web server... done!

'passenger stop'

Let us also try out the passenger stop command. First, start Passenger up again:

$ bundle exec passenger start

Open a seperate terminal, change the working directory to your application, and run passenger stop.

$ cd /path-to-your-app
$ bundle exec passenger stop

When you switch back to the first terminal, you should see that Passenger has indeed stopped.

Configuration

Command line options

Most configuration is done by customizing the options passed to the passenger command. For example, you can customize the port that Passenger listens on using --port, and you can customize the location of the log file using --log-file.

Here is an example invocation:

$ bundle exec passenger start --port 4000 --log-file awesome.log
======= Phusion Passenger Standalone web server started =======
PID file: /Users/phusion/myapp/tmp/pids/passenger.4000.pid
Log file: /Users/phusion/myapp/awesome.log
Environment: development
Accessible via: http://0.0.0.0:4000/

You can stop Phusion Passenger Standalone by pressing Ctrl-C.
===============================================================

Many more configuration options are available. You can see all available options by passing --help:

$ bundle exec passenger start --help
Usage: passenger start [DIRECTORY] [OPTIONS]
Starts Phusion Passenger Standalone and serve one or more web applications.

Server options:
    -a, --address HOST               Bind to the given address.
                                     Default: 0.0.0.0
    -p, --port NUMBER                Use the given port number. Default: 3000
...

Passengerfile.json

Command line options are great for temporarily changing a parameter, but if you want to persist a change, then it is best to store configuration in Passengerfile.json. Passenger Standalone automatically loads configuration from that file if it exists.

The configuration file format is JSON. You can find more information about the configuration file (such as its precedence compared to environment variables and command line options) in the Configuration introduction.

Here is an example Passengerfile.json which customizes the port, log file path and environment name:

{
    "port": 4000,
    "log_file": "awesome.log",
    "environment": "staging"
}

All command line options have a configuration file equivalent. Just omit the initial two dashes --, and replace other dashes - with underscores _.

Next step

Next up we will consider process management, a key feature in Passenger. Process management is what allows Passenger to keep your application stable and to maximize performance.

Continue »