How to Install Nginx Mainline on Rocky Linux

Nginx Mainline provides the latest features, performance improvements, and bug fixes from the Nginx development branch. While the stable branch receives only critical security patches, mainline includes new functionality that many administrators need for modern web deployments, including updated HTTP/2 and HTTP/3 support, improved load balancing algorithms, and enhanced security modules.

This guide walks through installing Nginx Mainline on Rocky Linux 8, 9, or 10 using the official nginx.org repository. By the end, you will have a working Nginx Mainline installation with the service running and firewall rules configured for web traffic.

Understanding Nginx Stable vs Mainline

Before installing, you should understand the difference between the two branches nginx.org maintains:

Nginx Stable

• Receives only critical bug fixes and security patches
• Recommended for production servers where stability is the priority
• New features are not backported from mainline
• Current stable version: 1.28.x

Nginx Mainline

• Contains all new features and enhancements
• Receives bug fixes more frequently than stable
• Recommended by the Nginx team for most deployments
• Current mainline version: 1.29.x

According to the official Nginx documentation, the mainline branch is generally safe for production use and provides access to new functionality sooner. This guide focuses on mainline, but the repository setup allows you to switch between branches easily. For complete setup details, see the official Linux packages documentation.

Update Rocky Linux Before Installation

Before adding external repositories, update your existing packages to avoid dependency conflicts. Run the following command to refresh the repository metadata and upgrade installed packages:

sudo dnf upgrade --refresh

This command ensures your system has the latest security patches and package versions before proceeding.

Remove Existing Nginx Installation (Optional)

If you have Nginx installed from the Rocky Linux AppStream repository or a previous configuration, remove it before installing from nginx.org to prevent package conflicts. Skip this section if Nginx is not currently installed.

Back Up Your Configuration

Before removing Nginx, preserve your existing configuration files. The following command creates a backup of your main configuration file:

sudo cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.backup

If you have custom server blocks or additional configuration, back up the entire directory:

sudo cp -r /etc/nginx /etc/nginx.backup

Stop and Remove the Current Installation

Stop the running Nginx service before uninstalling:

sudo systemctl stop nginx

Next, remove the existing Nginx packages along with any orphaned dependencies:

sudo dnf remove nginx nginx-*

DNF automatically removes unused dependencies by default. Once removal completes, you can proceed with the nginx.org repository installation.

Add the Official Nginx Repository

The official nginx.org repository provides both stable and mainline packages for RHEL-based distributions, including Rocky Linux. This section configures the repository using the $releasever and $basearch variables, which automatically select the correct packages for your Rocky Linux version (8, 9, or 10) and architecture (x86_64 or aarch64).

Install Repository Management Tools

First, install the yum-utils package, which provides the dnf config-manager command for enabling and disabling repositories:

sudo dnf install yum-utils -y

Create the Nginx Repository File

Next, create the repository configuration file that defines both the stable and mainline repositories. The following command creates /etc/yum.repos.d/nginx.repo with the correct settings:

sudo tee /etc/yum.repos.d/nginx.repo <<'EOF'
[nginx-stable]
name=nginx stable repo
baseurl=https://nginx.org/packages/centos/$releasever/$basearch/
gpgcheck=1
enabled=1
gpgkey=https://nginx.org/keys/nginx_signing.key
module_hotfixes=true

[nginx-mainline]
name=nginx mainline repo
baseurl=https://nginx.org/packages/mainline/centos/$releasever/$basearch/
gpgcheck=1
enabled=0
gpgkey=https://nginx.org/keys/nginx_signing.key
module_hotfixes=true
EOF

By default, this configuration enables the stable repository and disables the mainline repository. The module_hotfixes=true option ensures the repository works correctly on systems with modular packages enabled.

The repository uses HTTPS and includes GPG signature verification. When you install Nginx, DNF will prompt you to accept the Nginx signing keys. Verify the fingerprint matches 573B FD6B 3D8F BC64 1079 A6AB ABF5 BD82 7BD9 BF62 before accepting.

Enable the Mainline Repository

Since this guide focuses on Nginx Mainline, enable the mainline repository using dnf config-manager:

sudo dnf config-manager --set-enabled nginx-mainline

This command modifies the repository file to set enabled=1 for the mainline repository. If you prefer the stable branch instead, skip this step and install directly.

Install Nginx Mainline

Now that the repository is configured and the mainline branch is enabled, install Nginx:

sudo dnf install nginx

DNF displays the package details and prompts you to confirm. During the first installation, DNF also asks you to import the Nginx GPG signing keys. Before accepting, verify the fingerprint matches the official key.

Verify the Installation

Once installation completes, verify the installation succeeded by checking the version:

nginx -v

Expected output:

nginx version: nginx/1.29.4

This version number confirms you are running the mainline branch. If you see a version like 1.28.x, you have the stable repository enabled instead of mainline.

Start and Enable the Nginx Service

After installation, start the Nginx service and enable it to start automatically on boot:

sudo systemctl start nginx
sudo systemctl enable nginx

Then, verify the service is running correctly:

sudo systemctl status nginx

Expected output:

● nginx.service - nginx - high performance web server
     Loaded: loaded (/usr/lib/systemd/system/nginx.service; enabled; preset: disabled)
     Active: active (running) since Tue 2026-01-07 08:40:00 UTC; 5s ago
       Docs: https://nginx.org/en/docs/
    Process: 1234 ExecStart=/usr/sbin/nginx -c /etc/nginx/nginx.conf (code=exited, status=0/SUCCESS)
   Main PID: 1235 (nginx)
      Tasks: 2 (limit: 23160)
     Memory: 2.1M
        CPU: 12ms
     CGroup: /system.slice/nginx.service
             ├─1235 "nginx: master process /usr/sbin/nginx -c /etc/nginx/nginx.conf"
             └─1236 "nginx: worker process"

The Active: active (running) status confirms Nginx is running. Similarly, the enabled status in the Loaded line confirms it will start automatically after reboot.

Configure Firewalld for Web Traffic

Rocky Linux uses firewalld by default. To allow incoming HTTP and HTTPS traffic, add the appropriate services to your firewall configuration.

Opening ports 80 and 443 exposes your server to the public internet. Before allowing traffic, ensure your Nginx configuration does not expose sensitive directories, default credentials, or development files. For production deployments, configure SSL/TLS certificates and review security headers to protect against common web vulnerabilities.

Allow HTTP and HTTPS Traffic

Run the following commands to permanently allow web traffic through the firewall:

sudo firewall-cmd --permanent --zone=public --add-service=http
sudo firewall-cmd --permanent --zone=public --add-service=https

The --permanent flag ensures these rules persist across reboots. Without it, the firewall would discard the rules on restart.

Reload the Firewall

Next, apply the new rules by reloading firewalld:

sudo firewall-cmd --reload

Verify Firewall Configuration

Finally, confirm that both services now appear in the firewall configuration:

sudo firewall-cmd --list-services --zone=public

Expected output:

cockpit dhcpv6-client http https ssh

The presence of http and https in the list confirms the firewall allows web traffic. You can now access the Nginx default page by navigating to your server’s IP address in a web browser.

Switch Between Mainline and Stable Branches

Because the nginx.org repository contains both branches, you can switch between mainline and stable without reconfiguring the repository files. This section explains the process for switching between branches.

Switch to Stable

To switch from mainline to stable, first remove the current installation:

sudo systemctl stop nginx
sudo dnf remove nginx

Next, disable the mainline repository and enable stable:

sudo dnf config-manager --set-disabled nginx-mainline
sudo dnf config-manager --set-enabled nginx-stable

Finally, reinstall Nginx:

sudo dnf install nginx
sudo systemctl start nginx
sudo systemctl enable nginx

Finally, verify the stable version is installed:

nginx -v

Expected output for stable:

nginx version: nginx/1.28.1

Switch Back to Mainline

To return to mainline from stable, reverse the process by enabling the mainline repository and disabling stable:

sudo systemctl stop nginx
sudo dnf remove nginx
sudo dnf config-manager --set-enabled nginx-mainline
sudo dnf config-manager --set-disabled nginx-stable
sudo dnf install nginx
sudo systemctl start nginx
sudo systemctl enable nginx

Update Nginx

The nginx.org repository delivers Nginx updates automatically. To update Nginx when new versions become available, run:

sudo dnf upgrade nginx

Alternatively, update all packages on your system, including Nginx:

sudo dnf upgrade --refresh

After updating, restart Nginx to load the new binary:

sudo systemctl restart nginx

You must restart Nginx after package updates because the update replaces the nginx binary. Using reload only applies configuration changes without loading the updated executable.

Remove Nginx

If you need to completely remove Nginx and the nginx.org repository from your system, follow these steps.

Stop and Remove the Package

First, stop the Nginx service and remove the package:

sudo systemctl stop nginx
sudo systemctl disable nginx
sudo dnf remove nginx

Remove the Repository

Next, delete the nginx.org repository file:

sudo rm /etc/yum.repos.d/nginx.repo

Remove Configuration Files (Optional)

The following command permanently deletes all Nginx configuration files, including any custom server blocks, SSL certificates stored in the Nginx directory, and site configurations. Back up any files you want to keep before proceeding.

sudo rm -rf /etc/nginx

Verify Removal

To verify removal, confirm that the nginx command no longer exists:

nginx -v

Expected output:

-bash: nginx: command not found

Troubleshooting

Port 80 Already in Use

If Nginx fails to start with a “bind() failed” error, another service is using port 80. Check which process is using the port:

sudo ss -tlnp | grep :80

For example, this output shows Apache using port 80:

LISTEN  0  511  *:80  *:*  users:(("httpd",pid=1234,fd=4))

To resolve this, stop the conflicting service before starting Nginx:

sudo systemctl stop httpd
sudo systemctl start nginx

Configuration Syntax Errors

If Nginx fails to start or reload due to configuration errors, test the configuration syntax:

sudo nginx -t

Example output with a successful test:

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

If the test finds errors, Nginx displays the file and line number causing the problem. Fix the configuration and test again before restarting.

Repository Errors

If DNF reports errors fetching the nginx.org repository, verify the repository file is correctly configured:

cat /etc/yum.repos.d/nginx.repo

Ensure the baseurl lines contain $releasever and $basearch (with the dollar signs). If these variables are missing or incorrectly escaped, regenerate the repository file using the commands in the “Add the Official Nginx Repository” section.

Next Steps

With Nginx Mainline installed and running, consider these related guides to configure your web server:

• Install PHP on Rocky Linux for serving dynamic web applications with Nginx
• Configure security headers in Nginx to protect against common web vulnerabilities
• Enable gzip compression in Nginx to reduce bandwidth and improve page load times
• Create a reverse proxy in Nginx to route traffic to backend applications
• Change ports in Nginx if you need to run the server on non-standard ports

Conclusion

You now have Nginx Mainline installed from the official nginx.org repository on Rocky Linux, with the service running and firewall rules configured for web traffic. The repository setup uses version-agnostic variables, so future Rocky Linux upgrades will continue to receive Nginx updates without reconfiguration. To maintain security and access new features, update Nginx regularly using dnf upgrade.