how ports work in Passenger GLS

When starting an application using the Generic Language Support (GLS) built into Passenger, all that is required is to specify how Passenger should start your app on a specific port. To achieve this you specify the app start command which is the command you would otherwise use on the command line to start your app, with a placeholder $PORT where Passenger should substitute its chosen port, for your app to receive and bind to. Passenger requires that your application listens on a particular port that Passenger has chosen, and has provided to the application by replacing the $PORT string in its startup command with the actual port number.

Regardless of how your app accepts port arguments, the app startup command must be able to convert from a cli argument to what works for your app. We will privde some examples how to convert a command line argument to other methods of passing a config to your app.

command argument

The simplest case is where your app can take a command line argument to choose the port to listen on directly, in which case your app start command would look like this:

/usr/local/bin/myApp --port $PORT

environment variable

If you need to pass your app it's configuration via environment variables then the env tool can be very helpful:

/usr/bin/env APP_PORT=$PORT /usr/local/bin/myApp

config file

If your app can only accept configuration via config file, then you can use a wrapper script to start your app after writing the config file:

#!/usr/bin/env ruby

port=ARGV.first.to_i
File.write("/tmp/config_file",<<-HEREDOC
{
"port": #{port},
}
HEREDOC
)
exec(["/usr/local/bin/myApp","myApp"])