Changing and testing Nginx configuration

You can make adjustment to the Nginx rules and rewrites on MageStack by editing two key files

/microcloud/domains/example/domains/example.com/___general
/microcloud/domains/example/domains/example.com/___rewrites

To make the changes effective, you need to restart Nginx, you can do this either

  • Using Monit - by selecting the respective web node, selecting nginx, then pressing "Restart"
  • Using SSH - by typing /etc/init.d/nginx reload

Configuration testing

It is important to test your configuration before restarting Nginx, or a malformed syntax could prevent Nginx from successfully starting.

We have bundled in functionality to perform this test,

  • Using Monit - by using "nginx-configtest", select "nginx-configtest" then press either "start" or "stop". The configuration test results will be logged to both Kibana and your disk log files
  • Using SSH - by executing /etc/init.d/nginx configtest

Disk log file

Replace webX, and YYYY-MM-DD with the web server hostname and date respectively, as necessary.

/microcloud/logs_ro/webX/nginx-error-YYYY-MM-DD.log.gz

You should use a combination of zcat and tail to view the gzipped log files, eg.

zcat /microcloud/logs_ro/webX/nginx-error-YYYY-MM-DD.log.gz | tail

Kibana search string

Change to the web dashboard, https://kibana.magestack.com/#/dashboard/elasticsearch/web

app:"nginx-error"

Graceful restarting

Using restart on Nginx is considered aggressive (and a last resort), as it involves completely stopping the process and starting it again. This can cause lost sessions on the front-end.

Instead, it is wiser to use the graceful reload functionality of Nginx, we made this the default action of "restart" in Monit.

We have bundled in functionality to perform this test,

  • Using Monit - by selecting the respective web node, selecting nginx, then pressing "Restart". This will trigger a graceful reload, if there is a syntax error during reload, the error will be logged (see above).
  • Using SSH - by typing /etc/init.d/nginx reload