Enable NGINX with reverse proxy on cPanel

cPanel ships its own NGINX package, ea-nginx, which sits in front of Apache. NGINX takes the visitor connections, serves cached and static content quickly, and passes everything else to Apache. Your .htaccess rules keep working because Apache still handles the dynamic requests. This guide shows how to install it, manage caching per account and troubleshoot it.

Before you start

• cPanel & WHM using EasyApache 4, with root access.
• No other web server or proxy already bound to ports 80 and 443.
• A backup EasyApache profile. See the EasyApache 4 guide.
• A test site you can check after each step.

Install NGINX

From WHM

1. In WHM, open Software » NGINX Manager.
2. Click Install. WHM shows a progress log.
3. When it finishes, click Go to NGINX Manager.

The installer sets up every account to use NGINX, with caching on by default.

From SSH

On AlmaLinux or Rocky Linux:

dnf install ea-nginx

On Ubuntu:

apt install --purge ea-nginx

You can also provision the cPanel Default NGINX profile in EasyApache 4.

Manage caching per account

NGINX Manager has two areas:

• System Settings: Use Caching by Default sets the default for new accounts and for accounts without their own setting. This area also has Clear Cache for All Users, Restart NGINX and Rebuild Configuration.
• User Settings: search for an account and set caching Enabled or Disabled for it. A per-user setting overrides the system default. You can select several users and use Enable NGINX Cache or Disable NGINX Cache.

Turn caching off for sites that show personal content to logged-in visitors without proper cache headers, such as some shops or membership sites, until you have tested them.

To let users control caching themselves, enable the EA4 - Allow enabling/disabling NGINX caching feature in WHM » Packages » Feature Manager. Users then see an NGINX Caching option in cPanel.

From SSH, the ea-nginx script does the same:

/usr/local/cpanel/scripts/ea-nginx cache USER --enabled=0
/usr/local/cpanel/scripts/ea-nginx cache USER --enabled=1

Clear the cache

After a site update, clear its cache so visitors see the new content.

In WHM, click Clear Cache next to the user in User Settings, or Clear Cache for All Users. From SSH:

/usr/local/cpanel/scripts/ea-nginx clear_cache USER
/usr/local/cpanel/scripts/ea-nginx clear_cache --all

You must give either a username or --all, not both.

Check it works

Confirm NGINX answers on port 443 and passes requests to Apache:

ss -ltnp | grep -E ':(80|443) '
curl -sI https://example.com | grep -iE 'server|x-cache'

The listening process on 80 and 443 should be nginx. Many cached responses include a cache status header; request the page twice and compare. Then check a login page, a form and an .htaccess redirect still behave correctly.

Troubleshoot 502 Bad Gateway

A 502 means NGINX could not get a reply from Apache.

• Apache is down: check systemctl status httpd (AlmaLinux) or systemctl status apache2 (Ubuntu), then restart it from WHM » Restart Services » HTTP Server (Apache).
• Configuration out of date after account changes: rebuild all NGINX config and reload:

  /usr/local/cpanel/scripts/ea-nginx config --all
  nginx -t && /usr/local/cpanel/scripts/ea-nginx reload

• Read the log: tail -n 50 /var/log/nginx/error.log shows connect failed or upstream timed out with the reason.
• Slow PHP pages time out: the PHP request takes longer than the proxy timeout. Fix the slow page, or raise the timeout through cPanel's documented NGINX customisation includes, not the generated user files.
• Stale page after an update: the cache still holds the old version. Clear it for that user.

Do not edit the generated files in /etc/nginx/conf.d/users/. They are rebuilt.

Next steps

• Make sure every site has a certificate: set up AutoSSL in cPanel & WHM.
• Tune Apache behind the proxy: Apache settings in WHM.
• Restart services safely: restart services in WHM.