mybuddy/docs/setup/ssl.md

5.9 KiB

HTTPS/SSL

The example Docker and manual deployment methods do not include HTTPS/SSL by default. Additional tools and configuration are required to add HTTPS support.

Configuration requirements

For either approach (host- or container-based) Baby Buddy's configuration will need to be updated to account for the proxy. For details on these settings see Proxy configuration.

After configuring the proxy set the following two environment variables and then restart necessary services:

CSRF_TRUSTED_ORIGINS=https://babybuddy.example.com
SECURE_PROXY_SSL_HEADER=True

Host-based proxy

This guide assumes Baby Buddy has been deployed to a Debian-like system with snapd installed using the example deployment however this approach can also be used with a Docker deployment if having the proxy in the host is desired (otherwise see Container-based proxy).

If the example deployment with uWSGI and NGINX is already used skip to Install Certbot and Obtain and install certificate.

Install NGINX

If NGINX is not already installed on the host system install it with a package manager.

apt-get -y install nginx

NGINX will be used to proxy HTTPS traffic to Baby Buddy. There are many other proxies available for this (often with Let's Encrypt support, as well) so a different one can be used if desired.

Configure NGINX

If Baby Buddy is running from Docker a new NGINX site will need to be created to send traffic to Docker. The configuration below uses the example domain babybuddy.example.com and assumes Docker has exposed Baby Buddy on port 8000 (the default configuration).

editor /etc/nginx/sites-available/babybuddy

Initial configuration:

server_tokens               off;
access_log                  /var/log/nginx/babybuddy.access.log;
error_log                   /var/log/nginx/babybuddy.error.log;

server {
  server_name               babybuddy.example.com;
  location / {
    proxy_pass              http://localhost:8000;
    proxy_set_header        Host $host;
  }
}

Enable the new site:

ln -s /etc/nginx/sites-available/babybuddy /etc/nginx/sites-enabled/babybuddy
service nginx restart

Confirm the site is not accessible at http://babybuddy.example.com. Note: Attempting to log in will result in a CSRF error! This will be addressed after HTTPS has been established.

Install Certbot

This example uses Let's Encrypt's free service for obtaining SSL certificates. Other methods can be used to obtain and install a certificate as desired.

Certbot is used to obtain free SSL certificates from Let's Encrypt.

snap install core && snap refresh core
snap install --classic certbot
ln -s /snap/bin/certbot /usr/bin/certbot

Obtain and install certificate

The following command will ask for an email address to register with Let's Encrypt and then prompt a service agreement and which NGINX host to obtain a certificate for. The certificate will be installed and activated automatically.

certbot --nginx
[answers prompts as required]
service nginx restart

Certbot should have updated the NGINX site configuration (/etc/nginx/sites-available/babybuddy) to look something like this:

server_tokens               off;
access_log                  /var/log/nginx/babybuddy.access.log;
error_log                   /var/log/nginx/babybuddy.error.log;

server {
  server_name               babybuddy.example.com;
  location / {
    proxy_pass              http://localhost:8000;
    proxy_set_header        Host $host;
  }

    listen 443 ssl; # managed by Certbot
    ssl_certificate /etc/letsencrypt/live/babybuddy.example.com/fullchain.pem; # managed by Certbot
    ssl_certificate_key /etc/letsencrypt/live/babybuddy.example.com/privkey.pem; # managed by Certbot
    include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot
}

server {
    if ($host = babybuddy.example.com) {
        return 301 https://$host$request_uri;
    } # managed by Certbot

  server_name               babybuddy.example.com;
  listen                    80;
    return 404; # managed by Certbot
}

If the certificate was obtained by some other means the configuration about should be instructive for how to add it to the NGINX site configuration.

Container-based proxy

If Baby Buddy is already hosted in a Docker container the proxy (NGINX) can be hosted there as well. The configuration provided here assumes the docker-compose.yml example from the Docker deployment method is used.

Add NGINX service

Add the following services entry to docker-compose.yml:

babybuddy-nginx:
  image: nginx
  container_name: babybuddy-nginx
  volumes:
    - /path/to/appdata/nginx.conf:/etc/nginx/conf.d/default.conf
    - /path/to/appdata/logs:/var/log/nginx
    - /path/to/appdata/certs:/certs
  ports:
    - 80:80
    - 443:443
  depends_on:
    - babybuddy

Set the contents of /path/to/appdata/nginx.conf to:

server {
    server_name         babybuddy.example.com;
    listen              443 ssl;
    ssl_certificate     /certs/babybuddy.example.com.crt;
    ssl_certificate_key /certs/babybuddy.example.com.key;
    location / {
        proxy_pass              http://babybuddy:8000;
        proxy_set_header        Host $host;
    }
}

server {
    if ($host = babybuddy.example.com) {
        return 301 https://$host$request_uri;
    }

    server_name         babybuddy.example.com;
    listen              80;
    return 404;
}

Add certificates

Place certificates in /path/to/appdata/certs using the files name of ssl_certificate and ssl_ceritifcate_key in the NGINX configuration.