Local testing and development

You are browsing unreleased documentation.

Run ngrok

ngrok exposes a local URL to the internet. Download ngrok and install.

ngrok is only needed for local testing or development, it’s not a requirement for the plugin itself.

Run ngrok:

./ngrok http localhost:8000

The output includes your generated hostname:

Forwarding    http://example-host-12345.ngrok.io -> http://localhost:8000
Forwarding    https://example-host-12345.ngrok.io -> http://localhost:8000

Substitute example-host-12345.ngrok.io with the host shown in your ngrok output and export the hostname to an environment variable:

export NGROK_HOST=example-host-12345.ngrok.io

Leave the process running.

Configure the plugin

1. Configure a service:

    curl http://localhost:8001/services \
      --data "name=acme-test" \
      --data "url=https://httpbin.konghq.com"
   

2. Configure a route:

    curl http://localhost:8001/routes \
      --data "service.name=acme-test" \
      --data "hosts=$NGROK_HOST"
   

3. Enable the plugin:

    curl localhost:8001/plugins \
      --data "name=acme" \
      --data "config.account_email=test@test.com" \
      --data "config.tos_accepted=true" \
      --data "config.domains[]=$NGROK_HOST" \
      --data "config.storage=kong"
   

   This example uses kong storage for demo purposes, which stores the certificate in the Kong database. kong storage is not supported in DB-less mode or Konnect, use one of the other storage options instead.

Validate

1. Trigger certificate creation:

    curl https://$NGROK_HOST:8443 --resolve $NGROK_HOST:8443:127.0.0.1 -vk
   

   This might take a few seconds.

2. Check the new certificate:

    echo q |openssl s_client -connect localhost -port 8443 -servername $NGROK_HOST 2>/dev/null |openssl x509 -text -noout