Restarting applications
on Passenger + Nginx
When you have deployed an application on Passenger, you will want to restart it from time to time. For example when you have deployed a new version of your application, the new version isn't activated until you restart the application. Or when you have modified a configuration file that belongs to the application, the application may not activate the configuration changes until you restart it.
This guide explains how you can restart applications on Passenger.
Table of contents
- Loading...
Why restarts are necessary
Passenger does not start the application from scratch on every request. Instead, Passenger starts one or more instances of the application (application processes) and keeps them around for handling many requests. Because those processes are kept around, updates to the application don't take effect until the application is restarted.
Application restart methods
Passenger supplies several ways to restart an application that is running in Passenger.
passenger-config restart-app
The preferred method for restarting an application, is through the passenger-config restart-app tool. This tool can run interactively or non-interactively.
Interactive invocation
If you invoke passenger-config restart-app without arguments, it will ask you which application you want to restart. Here is an example:
$ passenger-config restart-app Please select the application to restart. Tip: re-run this command with --help to learn how to automate it. If the menu doesn't display correctly, press '!' ‣ /Users/phusion/testapp/public (development) Cancel
Use the Up and Down arrow keys to navigate the menu. Press Enter and it will restart the selected application.
Non-interactive invocation
You can also tell passenger-config restart-app to restart a specific application instead of asking you with a menu. The command accepts an application path prefix as first argument. When given, it will restart all applications whose path matches the given prefix.
For example, suppose that your application is located in /Users/phusion/testapp. You have tell Passenger to restart the application like this:
$ passenger-config restart-app /Users/phusion/testapp Restarting /Users/phusion/testapp/public (development)
There is an even shorter way. You can tell Passenger to restart all apps that it is currently serving, by specifying / as the argument. This is because all applications' paths start with /.
$ passenger-config restart-app / Restarting /Users/phusion/testapp/public (development)
Security
In Passenger versions prior to 5.0.10, passenger-config restart-app must be run as the same user that the Passenger core process is running as. Because that is usually root, passenger-config restart-app usually needed to be run with sudo (or rvmsudo if you're using RVM).
Since 5.0.10, it is possible to run passenger-config restart-app without sudo. In that case, you will only be able to restart apps that are running as the same user as the user that invoked passenger-config.
More information
The passenger-config restart-app tool is self-documentating. Run the following to learn more about it:
passenger-config restart-app --help
restart.txt
Another method to restart an application is by touching the file restart.txt in the application directory's tmp subdirectory. Once Passenger has noticed that the file's timestamp has changed, it will restart the application.
To many people, this mechanism may seem a little weird, but it was introduced for a reason. Passenger was originally designed in an age when shared hosting was popular. Back then, most popular shared hosters only provided FTP access and no SSH access. There was no way to run a command like passenger-config restart-app, but even using FTP it was possible to change the timestamp of a file. Thus, restart.txt was introduced as a way to.
Unlike passenger-config restart-app, touching restart.txt doesn't result in the application being restarted immediately. Passenger checks for the timestamp change on every request, but subject to a throttling rate for performance reasons.
Restarting Nginx
You can restart all applications that Passenger is serving, by restarting Nginx.
Sometimes you may want to restart Nginx without restarting all Passenger-served applications, e.g. to update some configuration. If so, try the Flying Passenger mode.
Blocking restart vs zero-down time restart (rolling restart)
If you use passenger-config restart-app or restart.txt or restart an application, then Passenger never drops any requests during the restart.
However, Passenger performs a blocking restart by default. Passenger will shut down all processes for that application and spawn a new one. The spawning of a new application process could take a while (may be as high as 30 seconds for a moderate-sized Rails application on a busy server). Any requests that come in during this time won't be dropped, but will be blocked until this first application process has spawned. Visitors may experience this as "downtime".
In the Enterprise version of Passenger, a feature called rolling restarts is provided which solves this problem. With rolling restarts enabled, Passenger Enterprise restarts the application in the background so that visitors never experience any delays and never experience any degraded user experience. Please learn more at Zero-downtime app updates and restarts.
Deployment error resistance
Closely related to zero-downtime restarts is the Deployment error resistance Enterprise feature. Suppose that you have upgraded your application and you have issued a command to restart it, but the application update contains an error (e.g. a syntax error or a database configuration error) that prevents Passenger from successfully spawning a process. Passenger would normally display an error message to the visitor in response to this.
By enabling deployment error resistance, Passenger Enterprise "freezes" the application's process list. Existing application processes (belonging to the previous version) will be retained to serve requests. The error is logged, but visitors do not see any error messages. Passenger keeps the old processes around until an administrator has taken action. This way, visitors will suffer minimally from deployment errors.
Learn more about this feature in Deployment Error Resistance guide.
Application restarts vs Nginx configuration changes
Restarting an application does not activate any Nginx configuration changes. You have to restart Nginx for Nginx configuration changes to take effect.
