Running with NGINX and TLS

Martini can be configured to run connections over HTTPS with little effort but as an alternative, you can secure your instance using NGINX.

This guide will help you set up your instance behind a proxy server. NGINX in this setup will act as a reverse proxy for Martini. The topology below summarizes the set-up of the servers:

Martini deployed over NGINX topology

In this arrangement, the NGINX server handles all SSL connections from the users. It only decrypts the requests so that it could pass them to the Martini server. Martini's responses are then sent back to the NGINX server for encryption. The NGINX server then returns the encrypted responses to the client's browser. In a setup such as this, Martini does not participate at all in the encryption or decryption process.

This guide will go through the steps you need to take in order to run Martini behind NGINX. The process is discussed with an example and since the guide lays out instructions from a particular context, depending on the variables in your own set-up, you may have to substitute certain values.

This guide assumes that you are familiar with configuring NGINX

To learn more about NGINX, please visit their guide.

Assumptions

The NGINX server is running at IP Address 10.0.0.2
The Martini instance is running at IP Address 10.0.0.3:8080
The domain assigned to the instance will be martini.example.com

Procedure

In your NGINX server, go to the /etc/nginx/conf.d/certs/ directory and create two directories called ssl_crt and ssl_key. Copy your SSL certificate and key in these directories respectively.
1 2 3 4 5
/etc/nginx/conf.d/certs/ ├── ssl_crt │ └── <your-ssl-certicate-here> ├── ssl_key │ └── <your-ssl-key-here>
Create the sites-available and sites-enabled directories inside the /etc/nginx/conf.d directory. NGINX configuration files will be stored inside the sites-available directory. Then later, a symbolic link will be created to point to the sites-enabled directory for NGINX to load the configuration.
1 2 3
/etc/nginx/conf.d ├── sites-available ├── sites-enabled

Edit the file named /etc/nginx/nginx.conf and include all .conf files in the /etc/nginx/conf.d/sites-enabled. By doing this, NGINX will be prompted to load all *.conf files inside the sites-enabled folder upon start or restart of its process.

Your nginx.conf should look roughly like this (see line 20):

user              nginx;
worker_processes  auto;
error_log         /var/log/nginx/error.log error;
pid               /var/run/nginx.pid;
events {
    worker_connections  1024;
}
http {
    include                 /etc/nginx/mime.types;
    default_type            application/octet-stream;
    server_tokens           off;
    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                      '$status $body_bytes_sent "$http_referer" '
                      '"$http_user_agent" "$http_x_forwarded_for"';
    access_log              /var/log/nginx/access.log  main;
    sendfile                on;
    tcp_nopush              on;

    include /etc/nginx/conf.d/*.conf;
    include /etc/nginx/conf.d/sites-enabled/*.conf;
}

Create the configuration file for martini.example.com. In this case, the configuration file is named martini.example.com.conf. It should reside in the directory /etc/nginx/conf.d/sites-available. Below is its content:

upstream martini {
    server 10.0.0.3:8080 fail_timeout=0;
}

server {
    listen 80;
    server_name martini.example.com;
    access_log /var/log/nginx/martini.example.com_access.log;
    error_log /var/log/nginx/martini.example.com_error.log;

    location / {
        return 301 https://$server_name$request_uri;

        proxy_pass http://martini;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Server $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Port 80;
        proxy_set_header Host $host;
        proxy_redirect off;
        proxy_connect_timeout 240;
        proxy_send_timeout 240;
        proxy_read_timeout 240;
    }

}
server {
    listen 443;
    server_name martini.example.com;
    access_log /var/log/nginx/martini.example.com_ssl_access.log;
    error_log /var/log/nginx/martini.example.com_ssl_error.log;
    ssl on;
    ssl_certificate <your-ssl-certicate-here>;
    ssl_certificate_key <your-ssl-key-here>;
    location / {
        proxy_pass http://martini;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Server $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Port 443;
        proxy_set_header X-Forwarded-Proto https;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_redirect off;
        proxy_connect_timeout 240;
        proxy_send_timeout 240;
        proxy_read_timeout 240;
    }
}

HTTP block configuration is optional

The HTTP block in the NGINX configuration is not necessary but provided as a guide in case you'll need to access the HTTP endpoint proxied by NGINX.

Create a symbolic link from the sites-available to the sites-enabled directory.
1
ln -s /etc/nginx/conf.d/sites-available/martini.example.com.conf /etc/nginx/conf.d/sites-enabled/martini.example.com.conf
Test the NGINX configuration.
1
nginx -t
If NGINX has confirmed that all configurations are okay, you can now reload NGINX.
1
nginx -s reload
Configure your DNS. Ensure that your DNS entry points to the IP address of your NGINX instance and not Martini's IP address.

Voila! Martini requests will now pass through the proxy server and will be served using secure connections.

Testing

To test, try accessing your Martini instance via the domain you assigned to it. In this case, it's https://martini.example.com.

Toro Cloud Dev Center

Running with NGINX and TLS

Assumptions

Procedure