Skip to main content

Nginx Upgrade

This guide applies to environments installed using the Nginx Deployment Guide, with Nginx installed in /usr/local/nginx/ and managed by systemd. Run the following commands as root.

Note

The upgrade briefly stops Nginx. Perform it during a maintenance window. Replace only the Nginx executable, keeping existing proxy settings, certificates, and log rotation settings. Check compatibility separately if you use a custom installation path or modules.

Upgrade Steps​

  1. Check the Current Version and Configuration, and Back Up the Installation Directory

    /usr/local/nginx/sbin/nginx -v
    /usr/local/nginx/sbin/nginx -t
    cp -a /usr/local/nginx /usr/local/nginx.bak

    If /usr/local/nginx.bak already exists, move the previous backup elsewhere before running the backup command. Continue only after the configuration check and backup succeed.

  2. Download and Extract the Target Version

    wget https://pdpublic.mingdao.com/private-deployment/offline/common/nginx-1.30.6-glibc2.17-amd64.tar.gz
    tar -zxvf nginx-1.30.6-glibc2.17-amd64.tar.gz

  3. Check the Existing Configuration with the New Version

    ./nginx/sbin/nginx -v
    ./nginx/sbin/nginx -p /usr/local/nginx/ -c /usr/local/nginx/conf/nginx.conf -t

    Confirm that the version is correct and that the output includes syntax is ok and test is successful. Resolve any missing dependencies or incompatible settings before stopping the existing service.

  4. Stop the Service and Replace the Nginx Executable

    systemctl stop nginx

    After confirming that the service has stopped, run:

    cp -a ./nginx/sbin/nginx /usr/local/nginx/sbin/nginx
    /usr/local/nginx/sbin/nginx -t

    Do not extract the package directly into /usr/local/, as this may overwrite the existing configuration.

  5. Start Nginx

    After the configuration check succeeds, run:

    systemctl start nginx

  6. Verify the Upgrade

    /usr/local/nginx/sbin/nginx -v
    systemctl status nginx --no-pager

    Confirm that the version has changed and the service status is active (running). Open HAP and check page access, login, and file uploads and downloads.

Version Rollback​

If the new version fails to start or application access is affected, restore the executable from /usr/local/nginx.bak/.

  1. Stop Nginx

    systemctl stop nginx

  2. Restore the Previous Nginx Executable

    After confirming that the service has stopped, run:

    cp -a /usr/local/nginx.bak/sbin/nginx /usr/local/nginx/sbin/nginx
    /usr/local/nginx/sbin/nginx -t

  3. Start Nginx

    After the configuration check succeeds, run:

    systemctl start nginx

  4. Verify the Rollback

    /usr/local/nginx/sbin/nginx -v
    systemctl status nginx --no-pager

    Confirm that the previous version is restored and the service status is active (running). Check HAP access and application functions again.