SSL with the Bridge Framework

This is a quick guide for how to set up a HTTPS development environment on a POSIX OS (OS X or Linux).


Prerequisites

  1. Install Dart
  2. Install the Bridge installer:
pub global activate new_bridge

Creating a project

At the time of writing this article, SSL is only available in the dev channel of Bridge, so to create a project we need to use the --dev flag on the installer.

new_bridge ssl_sample --dev && cd ssl_sample

Once the install is done and we’re inside the project directory, we can verify that the default settings are working by running this command:

dart bridge start

If everything works we can visit http://localhost:1337 and see the Bridge logo. Press ^X to exit the program.

Getting a self signed certificate and key

As a default, Bridge assumes a certificate file at storage/certificate.pem and a private key at storage/key.pem. Although this is an easy edit in the config if you already have a certificate and key installed somewhere else, since we’re going to generate a self signed certificate, let’s just follow that convention with this command:

(Stolen from here)

openssl genrsa -out key.pem 2048 &&
openssl req -new -key key.pem -out csr.pem &&
openssl req -x509 -days 365 -key key.pem -in csr.pem -out certificate.pem

I’ve added the ampersands between commands so that everything can be copy pasted and run immediately.

Once you do, you’ll be asked a series of questions. Just answer whatever, but be sure to ignore the two last “extra” questions. They will probably mess this guide up.

Changing the config

Let’s open up config/http.yaml and check the default (at the time of writing this guide):

server:
port: 1337
host: localhost
 public_root: web
build_root: storage/.build
 use_ssl: false
 ssl:
port: 1337
certificate: storage/certificate.pem
private_key: storage/key.pem
password: env(SSL_PRIVATE_KEY_PASSWORD)

To enable https, we simply need to flick the switch on the use_ssl option. However, since the port value under ssl and server are the same, only the secure server will be available (http://localhost:1337 will not work). This would also be the behaviour if the ssl.port option was omitted entirely.

In a real life scenario, it’s recommended to have a web server like Nginx proxy through to the localhost ports that Bridge listens on. So given we have some domain name like example.com pointing to our server, then we’d have to proxy both example.com:80 (http) and example.com:443 (https).

So let’s change the HTTP port to something else, like 1338. Then, in production, the proxies would look like this:

  • example.com:80—localhost:1338
  • example.com:443 — localhost:1337

Another, more straightforward option is to let Nginx handle the redirect, in which case the default behaviour of Bridge only setting up the HTTPS server will suffice:

  • example.com:80 — example.com:443
  • example.com:443 — localhost:1337

This is our resulting config/http.yaml file:

server:
port: 1338
host: localhost
 public_root: web
build_root: storage/.build
 use_ssl: true
 ssl:
port: 1337
certificate: storage/certificate.pem
private_key: storage/key.pem
password: env(SSL_PRIVATE_KEY_PASSWORD)

Profit

Just like that you’re done. Run dart bridge start and enjoy your SSL connection on https://localhost:1337 (Just ignore the warnings or add the certificate to the list of trusted ones on your machine).

If you visit http://localhost:1338, you’re redirected to the corresponding secure page.

Listening on public ports

If you want to try it, you can change the ports in config/http.yaml to the public ones:

server:
port: 80
host: localhost
 public_root: web
build_root: storage/.build
 use_ssl: true
 ssl:
port: 443
certificate: storage/certificate.pem
private_key: storage/key.pem
password: env(SSL_PRIVATE_KEY_PASSWORD)

Now you’ll have to run Bridge as sudo, which is not recommended:

sudo dart bridge start

If you visit http://localhost or https://localhost they will both work, and redirect correctly.