.. _configuring nginx:

###################
Nginx Configuration
###################

To configure nginx, the following template can be used:

Default nginx.conf
==================

The **dist** configuration shipped with nginx looks similar to the following:

nginx.conf
--------------------------------------------------------------------------------

| user nginx nginx;
| worker_processes 1;
| 
| error_log /var/log/nginx/error_log info;
| 
| events {
|    worker_connections 1024;
|    use epoll;
| }
|
| http {
|    include /etc/nginx/mime.types;
|    default_type application/octet-stream;
|
|    log_format main
|       '$remote_addr - $remote_user [$time_local] '
|       '"$request" $status $bytes_sent '
|       '"$http_referer" "$http_user_agent" '
|       '"$gzip_ratio"';
|
|    client_header_timeout 10m;
|    client_body_timeout 10m;
|    send_timeout 10m;
|
|    connection_pool_size 256;
|    client_header_buffer_size 1k;
|    large_client_header_buffers 4 2k;
|    request_pool_size 4k;
|
|    gzip off;
|
|    output_buffers 1 32k;
|    postpone_output 1460;
|
|    sendfile on;
|    tcp_nopush on;
|    tcp_nodelay on;
|
|    keepalive_timeout 75 20;
|
|    ignore_invalid_headers on;
|
|    index index.html;
|
|    server {
|       listen 0.0.0.0:80  default_server;
|       server_name localhost;
|
|       access_log /var/log/nginx/localhost.access_log main;
|       error_log /var/log/nginx/localhost.error_log info;
|
|       root /var/www/localhost/htdocs;
|    }
|
|    # SSL example
|    #server {
|    #  listen 127.0.0.1:443;
|    #  server_name localhost;
|
|    #  ssl on;
|    #  ssl_certificate /etc/ssl/nginx/nginx.pem;
|    #  ssl_certificate_key /etc/ssl/nginx/nginx.key;
|
|    #  access_log /var/log/nginx/localhost.ssl_access_log main;
|    #  error_log /var/log/nginx/localhost.ssl_error_log info;
|
|    #  root /var/www/localhost/htdocs;
|    #}
| }

--------------------------------------------------------------------------------

Save a coy of this to '$HOME/.local/etc/nginx/nginx.conf'

.. code-block:: shell

   ~/documentation $ mkdir -p $HOME/.local/etc/nginx
   ~/documentation $ $EDITOR $HOME/.local/etc/nginx/nginx.conf

or alternatively, copy the entire nginx dist configuration

.. code-block:: shell

   ~/documentation $ cp -R /etc/nginx $HOME/.local/etc

.. _nginx-dev-conf:

Local nginx dev configuration
=============================

Add the prefix '$HOME/.local' to all the lines starting with $HOME
(expanding $HOME to your full path):

| /var/...

In the **http** block, *add* the following:

| proxy_temp_path /tmp/nginx;
| fastcgi_temp_path /tmp/nginx;
| scgi_temp_path /tmp/nginx;
| uwsgi_temp_path /tmp/nginx;

... and in the **server** block, change the port from 80 to 8181

| listen 0.0.0.0:8181

Check dev-conf
--------------

Make sure the configuration is syntactically correct:

.. code-block:: shell

   nginx -t \
      -c $HOME/.local/etc/nginx/nginx.conf \
      -e $HOME/.local/var/log/nginx/error_log 


nginx options
-------------

From `nginx -h`

   nginx version: nginx/1.21.6
   Usage: nginx [-?hvVtTq] [-s signal] [-p prefix]
   [-e filename] [-c filename] [-g directives]

   Options:
      -?,
         -h : this help

      -v
          version and exit

      -V
         : show version and configure options then exit

      -t
         : test configuration and exit

      -T
         : test configuration, dump it and exit

      -q
         : suppress non-error messages during configuration testing

      -s signal
         : send signal to a master process: stop, quit, reopen, reload

      -p prefix
         : set prefix path (default: /usr/)

      -e filename
         : set error log file (default: /var/log/nginx/error_log)

      -c filename
         : set configuration file (default: /etc/nginx/nginx.conf)

      -g directives
           : set global directives out of configuration file

Remove user and group
---------------------

As this will be a local user running the server,
the *user* directive needs to be removed.

This is used when root launches the process to hand control over to the named
user/group.

Add root location
-----------------

Add the following the to **server** block

   root $HOME/git/documentation/build/html;

Making nginx log directories
----------------------------

.. code-block:: shell

   ~/documentation $ mkdir -p $HOME/.local/var/log/nginx

Run nginx dev docs
------------------

To run the server and view the documentation:

.. code-block:: shell

   ~/documentation $ nginx -c ~/.local/etc/nginx/nginx.conf \
      -e $HOME/.local/var/log/nginx/error_log
   ~/documentation $ xdg-open http://localhost:8181

.. _home-path:

Create an nginx-dev alias
=========================

To make launching the server easier, the following can be added '$HOME/.bashrc'

.. code-block:: shell

   ~/documentation $ printf "
   alias nginx-dev=\"nginx\"\\
   \" -c \$HOME/.local/etc/nginx/nginx.conf\"\\
   \" -e \$HOME/.local/var/log/nginx/error_log\"
   " >> $HOME/.bashrc

Then to launch the server, the following can be used:

.. code-block:: shell

   ~/documentation $ nginx-dev


Obtaining the '$HOME' value
---------------------------

.. code-block:: shell

   ~/documentation $ echo $HOME
   /home/..