Skip to content

Nginx Configuration Guide

Clarive Config Nginx entries

The Nginx server linked to your Clarive instalation uses the following directories and files:

  • CLARIVE_BASE/config/nginx/nginx.conf - configures how Nginx will run
  • CLARIVE_BASE/logs/nginx.pid - contains the PID of the Nginx started by Clarive, unless overriden by the user in the nginx.conf. The PID file only exists when Nginx is started and running.
  • CLARIVE_BASE/logs/nginx-access.log - Nginx access logs, with each client that accesses this Nginx
  • CLARIVE_BASE/logs/nginx-error.log - Nginx error messages

It's possible to override the defaults in your config file CLARIVE_BASE/config/MYCONFIG.yml by setting the different variables individually:

# Set your Nginx configuration home:

nginx_prefix: /opt/clarive/config/nginx

# Set the config file directly:

nginx_config: /opt/nginx/conf/nginx.conf

# Tell Clarive where to find the PID, to match your nginx.conf

nginx_pid: /opt/clarive/logs/nginx.pid

Use the cla nginx command to start, stop or reload the Nginx configuration.

Warn

Directories can be overriden by modifying the nginx.conf file directly, but Clarive may not be able to find the config and PID files needed for cla nginx commands to work.

Understanding the Clarive nginx.conf

The provided Nginx configuration for the Clarive server is constructed dynamically using a template with values introduced during cla setup. This documentation provides a detailed breakdown of the configuration's sections and directives.

If you'd like to read the original Nginx, especially if you have a legacy instalation of Clarive+Nginx, you can read the template to check for up to date configuration recommendations.

CLARIVE_HOME/templates/nginx.conf

Alternatively, you can run cla setup mydummy to create a throwaway configuration called mydummy then copy the resulting nginx.conf file that will be created under CLARIVE_BASE/config/nginx/nginx.conf.

Main Configuration

  • worker_processes: Sets the number of Nginx worker processes. This should be set to the number of CPU cores for optimal performance.
  • error_log: The path where Nginx will log any errors it encounters.
  • pid: The path where Nginx saves the PID of the main process.

Events Module

  • worker_connections: This directive limits the number of simultaneous connections a single worker process can handle.

HTTP Module

  • include: This pulls in additional configurations. Here, it's importing MIME types to ensure files are served with the correct type header.
  • default_type: The default MIME type that Nginx will use if it cannot determine one for a given file.
  • log_format: Defines the structure and content of entries in the access log.
  • access_log: Specifies where Nginx will save its access logs, which track all incoming requests.

Temporary File Paths

  • *_temp_path: These paths indicate where Nginx stores temporary files for various purposes. For instance, client_body_temp_path is used for buffering client request bodies, and proxy_temp_path is used when proxying requests.

Compression and Encoding

  • brotli and gzip: Enable or disable specific compression algorithms. Compression can reduce the amount of data sent over the network, improving loading times.
  • brotli_static: Enables serving pre-compressed Brotli files.
  • brotli_comp_level: Sets the compression level for Brotli (ranges from 1 to 11).
  • brotli_types: Specifies which MIME types will be compressed using Brotli.
brotli              on;
brotli_static       on;
brotli_comp_level   4;
brotli_types        text/plain text/css text/javascript text/js text/xml application/json application/javascript
                    application/x-javascript application/xml
                    application/xml+rss application/x-font-ttf image/svg+xml font/opentype
                    font/woff font/woff2 font/woff3 application/x-font-woff;

Server Block

  • server_name: Indicates which domain names or IP addresses this server block will respond to.
  • listen: Designates which port (and optionally IP) the server will listen on.

SSL Configuration

When SSL is configured:

  • ssl_certificate and ssl_certificate_key: Point to the SSL certificate and its corresponding private key, respectively.
  • ssl_protocols: Determines which versions of the SSL/TLS protocol can be used.
  • ssl_ciphers: Specifies which encryption ciphers are permissible.
  • ssl_prefer_server_ciphers: Ensures the server's cipher preferences take precedence.

Read more on SSL configuration further down, under Securing Nginx.

Request and Response Configuration

  • client_max_body_size: Determines the maximum size of the client request body. This is important for uploads.
  • Other directives like client_body_buffer_size and large_client_header_buffers fine-tune how Nginx buffers and processes client requests.

Location Blocks

These blocks define how Nginx responds to requests for specific URLs or URL patterns:

  • location /: Main configuration for handling most HTTP requests. The proxy_pass directive indicates that requests should be forwarded to the Clarive application server.
  • location /pubsub: Dedicated for the pub/sub functionality of Clarive.
  • location /static*: Multiple blocks dedicated to serving various static files and assets for the application.
  • location ~ /socket.io/: Specific configurations for handling WebSocket connections.

Each location block has specific directives for request/response handling, such as proxy settings, buffer sizes, and timeouts.

Securing Nginx

To set up your nginx.conf to enforce the use of only TLS 1.2 and TLS 1.3, as well as ensure the use of either AES (with key sizes greater than 128 bits) or CHACHA20+POLY1305 256, follow the steps below:

Setup SSL Protocols and Ciphers:

Within the http block or within your specific server block of your nginx.conf file or respective site configuration file, set the ssl_protocols and ssl_ciphers directives as follows:

ssl_protocols TLSv1.2 TLSv1.3;  # Ensure you're using modern TLS versions
ssl_ciphers 'ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA384';
ssl_prefer_server_ciphers on;

Make sure you also have ssl_prefer_server_ciphers off; so that the client's cipher list preference is honored (especially for TLS 1.3).

Redirect from HTTP to HTTPS:

To force redirecting all HTTP traffic to HTTPS, you can set up a separate server block that listens on port 80 and redirects all requests to HTTPS.

Forcing an HTTP to HTTPS redirect ensures that all data transmitted between the user's browser and the server is encrypted, thereby enhancing confidentiality and security. This prevents man-in-the-middle attacks, eavesdropping, and data tampering that can occur when data is sent over unencrypted, plain HTTP.

server {
    listen 80;
    server_name my.clarive.server;  # <--- change this to your server
    location / {
        return 301 https://$host$request_uri;
    }
}

If you're using an alternate 8080 configuration (8443 for HTTPS), do the following:

server {
    listen 8080;
    server_name my.clarive.server;  # <--- change this to your server
    location / {
        return 301 https://$host:8443$request_uri;
    }
}

You must also disable HTTP in your current server configuration, by commenting the HTTP port line:

    #listen 8080;

Note

Make sure you use a valid SSL certificate for your Clarive domain otherwise your users will be constantly warned that the Clarive SSL certificates are not safe and will need to do extra steps to open the Clarive main app website.

Point to your SSL Certificates

Ensure you have the path to your SSL certificates and private keys correctly configured. For instance:

ssl_certificate /etc/nginx/ssl/your_domain_name.crt;
ssl_certificate_key /etc/nginx/ssl/your_domain_name.key;

Splitting the Clarive server load (or failover)

You can make Nginx try more than one Clarive web server for improving response times for requests made to the Clarive web and pubsub. You do that setting up an upstream entry in the nginx.conf file.

http {
    # ... etc ...

    upstream clapool {
        server myclariveserver1:3000 max_fails=1 fail_timeout=1s;
        server myclariveserver2:3000 max_fails=1 fail_timeout=1s;
    }

Replace myclariveserver1 and myclariveserver2 with the hostname or IP of your Clarive servers.

Now update the server { ... } section to point to the upstream pool you just created:

    server {
        # ... etc ...
        location / {
            proxy_pass     http://clapool;  # <-- use the name of the pool in upstream
            # ... etc ...
        }
        # ... etc ...
    }

The same can be done for the pubsub server port, which is different from the main web port, by default 3001:

http {
    # ... etc ...
    upstream clapubsubpool {
        server myclariveserver1:3001 max_fails=1 fail_timeout=1s;
        server myclariveserver2:3001 max_fails=1 fail_timeout=1s;
    }

    server {
        # ...etc...
        location /pubsub {
            proxy_pass         http://clapubsubpool/pubsub;
        }
    }

    # ...etc...
}

Reload or Restart NGINX

After making the changes, you need to either reload or restart the NGINX service for the new configuration to take effect:

cla nginx-restart -c MYCONFIG

Or, if nginx is running independently on your system:

nginx -s reload

Ensure that you test your configuration after making these changes. Tools like SSL Labs can provide a comprehensive analysis of your SSL/TLS setup.

Template Configuration Variables

For documentation purposes, these are the cla setup variables that get fullfilled into the CLARIVE_HOME/templates/nginx.conf template file.

  • $base: The foundational directory for the Clarive installation. Paths related to logs and temporary files usually stem from this directory.
  • $home: Home directory for the Clarive application, primarily used to serve static content.
  • $nginx_host: The domain name or IP address that Nginx responds to. Default is set to 'localhost'.
  • $nginx_port: Port where Nginx listens for incoming HTTP connections. Default is set to 8080.
  • $nginx_pid: Location where Nginx will store its process ID.
  • $max_body_size: The maximum size of the body in a client request, e.g., file uploads. The default value is '2g', which means 2 gigabytes.
  • $worker_processes: Dictates how many worker processes Nginx spawns. Default is set to 2.
  • $worker_connections: The maximum number of connections each worker process can handle simultaneously. Default is set to 1024.
  • $clarive_url: URL pointing to the main Clarive application server.
  • $pubsub_url: URL dedicated for Clarive's publish/subscribe functionality.
  • $server_ssl_port: The port where Nginx listens for incoming HTTPS connections.
  • $ssl_certificate: Location of the SSL certificate used for HTTPS.
  • $ssl_certificate_key: Location of the private key corresponding to the SSL certificate.

Note

This Nginx configuration is tailored for the Clarive server's needs, balancing performance, security, and functionality. Always ensure to backup your configuration and test changes in a controlled environment before applying them in production.