Nginx & SSL

NimHA should not be exposed directly to the internet. Therefore it is recommended to setup a reverse proxy in front of it.

Nginx

Nginx is a web server which can also be used as a reverse proxy with a high‑performance and low CPU use.

Nginx configuration

The main Nginx configuration file is (normally) located here /etc/nginx/nginx.conf. If you are using the the configurations below, you do not need to edit this file.

The sites served through Nginx are located in /etc/nginx/sites-enabled/default. You can either remove, make a backup or comment out everything in this file and insert the data below.

sudo mv /etc/nginx/sites-enabled/default /etc/nginx/sites-enabled/default.bak
sudo nano /etc/nginx/sites-enabled/default

Web server

The following config is using SSL. If you are going to serve your website without SSL (not recommended), change the port to 80 and remove/comment out the SSL specifications.

Insert the data below into /etc/nginx/sites-enabled/default. Change the <domain> with your domain or IP-address. Read the comments with # and make the appropriated changes.

server {
  listen 443 ssl;
  server_name <domain> www.<domain>;

  # These lines will be added by Certbot (next step). If Certbot does not add them - then uncomment the lines and check that the path matches
  #ssl on;
  #ssl_certificate /etc/letsencrypt/live/<domain>/fullchain.pem;
  #ssl_certificate_key /etc/letsencrypt/live/<domain>/privkey.pem;

  location / {
    root   /home/pi/nim_homeassistant/public; # Edit this path to your NimHA folder

    if ($request_uri ~* ".(ico|css|js|gif|jpe?g|png|svg)$") {
      expires 10d;
      access_log off;
      add_header Pragma public;
      add_header Cache-Control "public";
    }

    server_tokens off;
    add_header X-Frame-Options SAMEORIGIN;
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains";
    add_header X-Content-Type-Options nosniff;
    add_header X-XSS-Protection "1; mode=block";

    proxy_pass http://127.0.0.1:5000; # This is the address and port, where NimHA is running

    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";

    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
  }
}

Websocket

NimHA uses a websocket for continuously updating the webpage without having to refresh.

The following config is using SSL. If you are going to serve your website without SSL (not recommended), change the port to your port specified in secret.cfg and remove/comment out the SSL specifications.

Append the data to /etc/nginx/sites-enabled/default. Change the <domain> with your domain or IP-address. Read the comments with # and make the appropriated changes.

upstream websocketproxy {
    server 127.0.0.1:25437;
}

server {
    listen 443 ssl;
    server_name <domain>;

    # These lines will be added by Certbot (next step). If Certbot does not add them - then uncomment the lines and check that the path matches
    #ssl on;
    #ssl_certificate /etc/letsencrypt/live/<domain>/fullchain.pem;
    #ssl_certificate_key /etc/letsencrypt/live/<domain>/privkey.pem;

    location / {
        proxy_http_version 1.1;

        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_pass http://websocketproxy;
    }
}

MQTT

A MQTT broker is essential for running NimHA. Currently NimHA uses Mosquitto.

MISSING NGINX CONFIG - HELP WANTED

Load config

You need to load your newly modified config file, if Nginx is already up and running.

Check you config file

sudo nginx -t

This commands should tell you, that there's no errors. If there's any error, fix them before continuing.

Load the new config

sudo nginx -s reload

SSL

Secure Sockets Layer (SSL) is a standard security technology for establishing an encrypted link between a server and a client. It is highly recommended if you are exposing NimHA to the internet.

The following guide utilize Certbot, which is a Python tool to simplify the installation of SSL certificates. Please note that the Certbot versions below are specific for Nginx.

We will use Let's Encrypt for the SSL certificate. Normally your certificates will be placed here /etc/letsencrypt/live/<domain>.

Install Certbot

General linux

Use your package manager (apt install certbot-nginx, sudo pacman -S certbot-nginx, etc.) or visit https://certbot.eff.org/all-instructions for installation instructions.

Raspberry Pi

Certbot is not available as a standard download, therefore you need to add the following backport.

Update sources.list

Open sources:

sudo nano /etc/apt/sources.list

Append the following to the bottom of file:

deb http://ftp.debian.org/debian jessie-backports main

Exchange keys

gpg --keyserver pgpkeys.mit.edu --recv-key  7638D0442B90D010
gpg -a --export 7638D0442B90D010 | sudo apt-key add -

Install Certbot

sudo apt update
sudo apt-get install python-certbot-nginx -t jessie-backports

Obtain the certificate

Remember that your router must have port 80 open for Let's Encrypts challenge

General linux

Change the <domain> with your domain.

sudo certbot --nginx -d <domain> -d <domain>

Raspberry Pi

Change the <domain> with your domain.

Due to the old version of Cerbot, we have to make a little hack.

sudo certbot --authenticator standalone --installer nginx -d <domain> --pre-hook "service nginx stop" --post-hook "service nginx start"