# Setting up SSL locally - Handbook

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.  Sign up for an ngrok account (or sign in with GitHub) and run `ngrok authtoken <TOKEN>`

2.  Find your ngrok config file location:

Terminal

PostHog AI

```bash
ngrok config check --log=stdout
```

On macOS, this will show `~/Library/Application Support/ngrok/ngrok.yml` (XDG location). The legacy location `~/.ngrok2/ngrok.yml` is deprecated.

3.  Edit your ngrok config file and add the following after the line with `authtoken: <TOKEN>`:

YAML

PostHog AI

```yaml
tunnels:
  django:
    proto: http
    addr: 8000
  webpack:
    proto: http
    addr: 8234
```

4.  Start ngrok. This will give you tunnel URLs such as [https://68f83839843a.ngrok-free.dev](https://68f83839843a.ngrok-free.dev)

Terminal

PostHog AI

```bash
ngrok start --all
```

5.  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:

Terminal

PostHog AI

```bash
export WEBPACK_HOT_RELOAD_HOST=0.0.0.0
export LOCAL_HTTPS=1
export JS_URL=https://68f83839843a.ngrok-free.dev
pnpm start
```

6.  Use the same URL as the value for `JS_URL` again and start the Django server

Terminal

PostHog AI

```bash
export DEBUG=1
export LOCAL_HTTPS=1
export JS_URL=https://68f83839843a.ngrok-free.dev
python manage.py runserver
```

7.  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.

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

## Set up SSL via NGINX and a local certificate

0.  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

Terminal

PostHog AI

```bash
openssl req -x509 -newkey rsa:4096 -sha256 -days 3650 -nodes \
  -keyout localhost.key -out localhost.crt -subj "/CN=secure.posthog.dev" \
  -addext "subjectAltName=DNS:secure.posthog.dev,IP:10.0.0.1"
```

2.  Trust the key for Chrome/Safari

Terminal

PostHog AI

```bash
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain localhost.crt
```

3.  Add `secure.posthog.dev` to /etc/hosts

text

PostHog AI

```text
127.0.0.1 secure.posthog.dev
```

4.  Install nginx (`brew install nginx`) and add the following config in `/usr/local/etc/nginx/nginx.conf`

nginx

PostHog AI

```nginx
upstream backend {
         server 127.0.0.1:8000;
     }
     server {
         server_name secure.posthog.dev;
         rewrite ^(.*) https://secure.posthog.dev$1 permanent;
     }
     server {
         listen       443 ssl;
         server_name  secure.posthog.dev;
         ssl_certificate  /path/to/your/certs/localhost.crt;
         ssl_certificate_key /path/to/your/certs/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/ {
            proxy_pass http://127.0.0.1:8234/static/;
        }
     }
```

5.  Add the following command to start nginx

Terminal

PostHog AI

```bash
nginx -p /usr/local/etc/nginx/ -c /usr/local/etc/nginx/nginx.conf
```

6.  You can stop the nginx server with

Terminal

PostHog AI

```bash
nginx -p /usr/local/etc/nginx/ -c /usr/local/etc/nginx/nginx.conf -s stop
```

7.  To run local development, use

Terminal

PostHog AI

```bash
bin/hogli start
```

### Community questions

Ask a question

### Was this page useful?

HelpfulCould be better