Setting up SSL locally

Last updated:

|Edit this page

Setting up HTTPS locally can be useful if you're trying to debug hard to replicate issues (e.g cross domain cookies, etc).

There are two ways you can get HTTPS locally:

  1. ngrok
  2. NGINX and a local certificate.

The easiest option is to use ngrok.

Set up SSL via ngrok

  1. Make sure you have ngrok installed.

  2. Sign up for an ngrok account (or sign in with GitHub) and run ngrok authtoken <TOKEN>

  3. Edit $HOME/.ngrok2/ngrok.yml and add the following after the line with authtoken: <TOKEN>:

proto: http
addr: 8000
proto: http
addr: 8234
  1. Start ngrok. This will give you tunnel URLs such as
ngrok start --all
  1. Copy the HTTPS URL for the tunnel to port 8234 and set it as the value for the JS_URL environment variable. Then, start webpack:
export LOCAL_HTTPS=1
export JS_URL=
pnpm start
  1. Use the same URL as the value for JS_URL again and start the Django server
export DEBUG=1
export LOCAL_HTTPS=1
export JS_URL=
python runserver
  1. Open the HTTPS URL for the tunnel to port 8000.

Tips & Tricks

If you're testing the Toolbar, make sure to add the ngrok urls to the list on the 'Project Settings' page.

Permitted domains

Also, watch out, network requests can be slow through ngrok:

Network slow with ngrok

Set up SSL via NGINX and a local certificate

  1. Update openssl if "openssl version" tells you "LibreSSL" or something like that.

In case brew install openssl and brew link openssl don't work well, use /usr/local/opt/openssl/bin/openssl instead of openssl in the next step.

  1. Create key
openssl req -x509 -newkey rsa:4096 -sha256 -days 3650 -nodes \
-keyout localhost.key -out localhost.crt -subj "/" \
-addext ",IP:"
  1. Trust the key for Chrome/Safari
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain localhost.crt
  1. Add to /etc/hosts
  1. Install nginx (brew install nginx) and add the following config in /usr/local/etc/nginx/nginx.conf
upstream backend {
server {
rewrite ^(.*)$1 permanent;
server {
listen 443 ssl;
ssl_certificate /Users/timglaser/dev/localhost.crt;
ssl_certificate_key /Users/timglaser/dev/localhost.key ;
ssl_prefer_server_ciphers on;
ssl_session_cache shared:SSL:1m;
ssl_session_timeout 5m;
ssl_ciphers HIGH:!aNULL:!MD5;
location / {
proxy_pass http://backend;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header Host $http_host;
proxy_redirect off;
proxy_set_header X-Forwarded-Proto $scheme;
location /static/ {
  1. Add the following command to start nginx
nginx -p /usr/local/etc/nginx/ -c /usr/local/etc/nginx/nginx.conf
  1. You can stop the nginx server with
nginx -p /usr/local/etc/nginx/ -c /usr/local/etc/nginx/nginx.conf -s stop
  1. To run local development, use


Was this page useful?

Next article

Tech talks

We encourage engineers to give tech talks on topics they"re interested in/knowledgeable about. Here are our talks so far: "PostHog Cloud infrastructure" by James Greenhill "Let"s Talk About PyCharm" by Marius Andra "Approaches to scaling" by Karl-Aksel Puulmann "Databases 101" by James Greenhill

Read next article