Charlie El Awbery

Troubleshooting Django deployment with cPanel and Passenger


June 6, 2020 |  Categories:   tech   python   django   deployment   tutorials  

This is the fifth and final page in a tutorial series, Deploying Django, a step-by-step guide to deployment for individuals building personal or small Django web projects. If you followed this guide from the beginning, you made many changes without having the environment set up to test your app view until now. Don’t despair if it didn’t work first time. In this section you’ll learn how to approach debugging the cPanel-Passenger-Python app environment. This page covers the most common error messages and how to go about debugging them. It cannot cover every possible problem, but if you come across an error message that you think would be useful to add here, please let me know. IMPORTANT! While you are debugging, keep a record of each change you make as you go along so that you can quickly undo it if it doesn't work. Keep a record of your fixes. You supposedly should never have to restart Apache, but in case a cache is preventing changes taking effect, it may help. Try this first.


The Index page view

index of slash page view

Apache recognizes the domain name but it doesn’t know that it’s supposed to send this page to Passenger. There is a problem with your Passenger app registration. 1. Using the application manager in cPanel verify that Passenger knows about your app . Check all the spellings are correct. 2. Verify that your application path directory does actually exist. You set up a path to your app’s source code when you registered the app with Passenger. Using your ssh connection in the terminal check that the path takes you to your source code directory.

3. Look at the Apache error log. If you want to see more lines of the error log file, use a number argument to the command, for example:

# tail -n25 /var/log/apache2/error_log

will show the last 25 lines. If there is no error log from Apache, this means Apache is oblivious to Passenger and is not recognizing a problem. The question to ask is “why is Passenger not getting activated?” 4. Check in the cPanel Domains interface that it thinks the account is supposed to serve the domain.


The Passenger error page

passenger error page view

The Passenger Phusion error page

This is an excellent problem to have! It indicates that your app registration worked: Passenger knows about the app but couldn’t run it for some reason. The Passenger log file is, by default, the global Apache error log file. To see the Passenger log history, you need root access to your server where you can view the Apache error log. Use ssh in your terminal to log in to the server as root. The command to see the log is typically tail /var/log/apache2/error_log

Try to fix the problem by understanding the log messages and search online for the error message if it's unclear what it means. A possible cause for this error page view is that Passenger is not running the same Python language version as used by your app. By default, cPanel configures Passenger to run Python2. Check that the path assigned to the INTERP variable in passenger_wsgi.py is the correct path to the Python version installed in your app environment. Use your ssh connection in your virtual environment on the server to determine that the Python version installed for your app is the one you think it is:

$ python --version

Log in as root to check what Python version Apache is running with Passenger. If you are confident that Passenger is running the Python version specified by your app source code, return to Step 4 of this guide which covers how to configure the passenger_wsgi.py file in your Django project. Go back to this step and check that you correctly customized all the arguments.


cPanel error

database image not displaying

Apache is sorry

This error message means that cPanel doesn’t recognize your domain. Go to domains in cPanel to debug.


Server Errors

database image not displaying

The web server encountered a problem with the HTTP request but can’t find an error message more specific than that. View the global Apache error log file.

database image not displaying

Apache’s 404 error message

The most likely cause for a 404 error is an unrecognized url.


Django errors

database image not displaying

Your app registered successfully with Passenger and the web server deployed it. There’s something wrong with your Django app code. Check for error messages in your ssh terminal connection and debug the app as you would locally.

*** Was this page useful? How could it be better? I'm grateful for suggestions, please DM me @_awbery_on Twitter with feedback. Thank you!