How to Upgrade NGINX to the Latest Version (v1.29.2)

Keeping your NGINX server up to date is essential for maintaining strong security, optimal performance, and compatibility with the latest web standards.

This guide walks you through the safe and efficient way to upgrade NGINX to the latest mainline release (v1.29.2).

Step 1: Check the Current Version

Start by confirming which version of NGINX is currently installed on your server:

Run this command on terminal

nginx -v

Step 2: Backup Existing Configuration

Before performing any upgrade, always back up your current NGINX configuration and web directory.

sudo cp -r /etc/nginx /etc/nginx-backup-$(date +%F)

sudo cp -r /usr/share/nginx/html /usr/share/nginx/html-backup-$(date +%F)

These backups allow you to restore NGINX quickly if something goes wrong.

Step 3: Add the Official NGINX Repository

Run below commands in terminal 

For Ubuntu / Debian:

Remove any old NGINX packages and add the latest official NGINX mainline repository

sudo apt remove nginx nginx-common nginx-full -y

sudo apt update

sudo apt install curl gnupg2 ca-certificates lsb-release ubuntu-keyring -y

curl https://nginx.org/keys/nginx_signing.key | sudo gpg --dearmor -o /usr/share/keyrings/nginx-archive-keyring.gpg

echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] http://nginx.org/packages/mainline/ubuntu $(lsb_release -cs) nginx" | sudo tee /etc/apt/sources.list.d/nginx.list

For CentOS / RHEL:

sudo yum remove nginx -y

sudo yum install yum-utils -y

sudo tee /etc/yum.repos.d/nginx.repo <<EOF

[nginx-mainline]

name=nginx mainline repo

baseurl=http://nginx.org/packages/mainline/centos/\$releasever/\$basearch/

gpgcheck=1

enabled=1

gpgkey=https://nginx.org/keys/nginx_signing.key

EOF

Step 4: Install the Latest NGINX

For Ubuntu / Debian:

sudo apt update && sudo apt install nginx -y

For CentOS / RHEL:

sudo yum install nginx -y

Verify installation:

You should see: nginx version: nginx/1.29.2

Step 5: Test the Configuration

sudo nginx -t

IF you see:

nginx: configuration file /etc/nginx/nginx.conf test is successful

then your configuration is ready to go.

Step 6: Restart and Verify

Restart the service to apply the update

sudo systemctl restart nginx

sudo systemctl status nginx

Step 7: Rollback if Needed

If you encounter issues, revert to your previous backup:

sudo systemctl stop nginx

sudo rm -rf /etc/nginx

sudo cp -r /etc/nginx-backup-YYYY-MM-DD /etc/nginx

sudo systemctl start nginx

Final Tips

Step	Best Practice
Backup	Always back up before upgrade
Test	Validate with nginx -t
Monitor	Check logs and performance after upgrade
Secure	Keep your system packages up to date

Post-Upgrade Checklist for .NET Applications on NGINX (v1.29.2 Upgrade)

When upgrading NGINX, the primary concern for a hosted .NET (Core/ASP.NET Core) application is ensuring that the reverse proxy configuration and the application's runtime environment remain functional and optimized.

The steps below assume you have successfully completed the NGINX binary upgrade to v1.29.2.

---

SECTION 1: NGINX Reverse Proxy Verification

NGINX acts as a Reverse Proxy, passing client requests to the Kestrel web server (where your .NET application runs). You must ensure the configuration correctly forwards traffic and preserves crucial headers.

Step 1: Test NGINX Configuration and Restart

This is the most critical step after the NGINX binary upgrade. You must verify the configuration is compatible with the new NGINX version.

Command	Purpose
sudo nginx -t	Tests the NGINX configuration syntax. This must return syntax is ok and test is successful. If it fails, restore your configuration backup and manually merge the required new directives.
sudo systemctl restart nginx	Restarts NGINX to load the new v1.29.2 binary and the existing configuration files.
nginx -v	Verification. Confirms the running version is nginx/1.29.2.

Step 2: Verify Reverse Proxy Headers

Check your site-specific configuration file (e.g., /etc/nginx/sites-available/default or /etc/nginx/conf.d/myapp.conf). The location block for your application must contain the following directives:

Nginx

location / {
    # 1. Forward traffic to the Kestrel application (e.g., listening on 5000)
    proxy_pass http://localhost:5000; 

    # 2. HTTP Version: Necessary for connection management and protocols
    proxy_http_version 1.1;

    # 3. WebSockets/SignalR support (CRUCIAL for many modern .NET apps)
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection keep-alive;

    # 4. Host Header: Passes the original domain name to the application
    proxy_set_header Host $host;
    proxy_cache_bypass $http_upgrade;
    
    # 5. X-Forwarded Headers: CRITICAL for .NET's ForwardedHeadersMiddleware
    #    (Passes client IP and scheme, required for authentication/HTTPS redirection)
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Step 3: Review Security Headers (Optional but Recommended)

New NGINX versions often enable performance or security enhancements. Ensure your NGINX configuration applies modern security headers to the response, such as:

Nginx

# Add these in the 'server' or 'http' block
add_header X-Frame-Options "SAMEORIGIN";
add_header X-Content-Type-Options "nosniff";
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

---

SECTION 2: .NET Application Runtime and Service Health

The NGINX upgrade is separate from the .NET environment, but both should be current and in sync.

Step 4: Check and Update .NET Runtime Environment

The application relies on the .NET Runtime being installed on the server. If your NGINX upgrade was part of a broader maintenance window, consider updating the runtime as well for critical security patches.

Command (Ubuntu/Debian Example)	Purpose
dotnet --info	Displays all installed .NET SDKs and Runtimes.
sudo apt update	Updates the package list.
sudo apt install aspnetcore-runtime-<Version>	Updates the ASP.NET Core Runtime (e.g., aspnetcore-runtime-8.0) to the latest patch version.

Step 5: Restart the .NET Application Service

Even if the application service (Kestrel) was not explicitly stopped, it must be restarted to ensure it uses the new NGINX connection and, more importantly, any updated system libraries or .NET Runtimes.

Command	Purpose
sudo systemctl status <YourAppName>.service	Checks the current status of your application's systemd service.
sudo systemctl restart <YourAppName>.service	Restarts your .NET application. This ensures Kestrel is running correctly on the updated system.
sudo journalctl -fu <YourAppName>.service	Monitors the application's logs for immediate errors after restart.

---

SECTION 3: Final Verification

1. Browser Check: Access your application via the public URL. Verify all pages load correctly, form submissions work, and interactive features (like chat or real-time updates using SignalR) are functional.

2. Log Check: Review the NGINX access and error logs (/var/log/nginx/access.log and /var/log/nginx/error.log) for any new warnings or failures related to the reverse proxy connection.