Exposing Opsdroid via tunnels¶
Many chat connectors require your Opsdroid instance to be accessible on the public internet. This is because they send events to Opsdroid by calling HTTP endpoints directly.
You may choose to run Opsdroid on an internet facing machine such as a VM from a cloud vendor. You also have the option to configure DNS (or at home Dynamic DNS) and open up ports on your router.
Alternatively you can tunnel traffic to Opsdroid through a variety of services. This page documents many of those tunneling options.
Most connectors will read the web.base-url
config option and configure things for you, but this is not always the case.
For some connectors you may need to configure the URL of your bot yourself. See your specific connector’s docs for info.
Note
As this page documents third-party tools and sevices it may become out of date. If you notice any errors or omissions please
consider raising a Pull Request <https://github.com/opsdroid/opsdroid/edit/master/docs/exposing.md>
_.
Ngrok¶
Type: SaaS
Cost: $5/month (or free with random URLs)
Source: Proprietary
Website: https://ngrok.com/
Ngrok forwards any local web server to the internet via HTTP/HTTPS.
Install¶
See the official instructions.
Start tunnel¶
Opsdroid will run on port 8080
by default so let’s start an HTTP tunnel to that port.
$ ngrok http 8080
ngrok by @inconshreveable (Ctrl+C to quit)
Session Status online
Session Expires 7 hours, 59 minutes
Version 2.3.35
Region United States (us)
Web Interface http://127.0.0.1:4040
Forwarding http://NGROK_URL.ngrok.io -> http://localhost:8080
Forwarding https://NGROK_URL.ngrok.io -> http://localhost:8080
Connections ttl opn rt1 rt5 p50 p90
0 0 0.00 0.00 0.00 0.00
Configure Opsdroid¶
$ opsdroid config edit
Add the following to your config.
web:
base-url: https://NGROK_URL.ngrok.io # Whatever your https URL is in the ngrok output
Warning
If you use a free Ngrok account the URL will be randomised every time your start Ngrok and you will need to update your Opsdroid config and restart.
Run Opsdroid¶
$ opsdroid start
INFO opsdroid.logging: ========================================
INFO opsdroid.web: Started web server on https://NGROK_URL.ngrok.io
INFO opsdroid.core: Opsdroid is now running, press ctrl+c to exit.
Running as a service¶
It is likely that you are running Opsdroid as a service via something like systemd or Docker.
PageKite¶
Type: SaaS
Cost: Free (pay what you want)
Source: Open source (GitHub)
Website: https://pagekite.net/
PageKite forwards any local web server to the internet via HTTP/HTTPS.
Install¶
See the official instructions.
Start tunnel¶
Opsdroid will run on port 8080
by default so let’s start an HTTP tunnel to that port.
$ pagekite 8080 YOUR_CHOSEN_SUBDOMAIN.pagekite.me
You will then be prompted to answer some questions and enter your email address. Once you have clicked the link in the email your session should start.
>>> Hello! This is pagekite v1.5.2.201011. [CTRL+C = Stop]
Connecting to front-end relay xxx.xxx.xxx.xxx:443 ...
- Relay supports 10 protocols on 19 public ports.
- Raw TCP/IP (HTTP proxied) kites are available.
- To enable more logging, add option: --logfile=/path/to/logfile
Abuse/DDOS protection: Relaying traffic for up to 5 clients per 10800s.
Quota: You have 31 days, 5.0 tunnels left.
~<> Flying localhost:8080 as https://YOUR_CHOSEN_SUBDOMAIN.pagekite.me/
xxx.xxx.xxx.xxx < http://YOUR_CHOSEN_SUBDOMAIN.pagekite.me:443 (localhost:8080)
<< pagekite.py [flying] Kites are flying and all is well.
Configure Opsdroid¶
$ opsdroid config edit
Add the following to your config.
web:
base-url: https://YOUR_CHOSEN_SUBDOMAIN.pagekite.me
Run Opsdroid¶
$ opsdroid start
INFO opsdroid.logging: ========================================
INFO opsdroid.web: Started web server on https://YOUR_CHOSEN_SUBDOMAIN.pagekite.me
INFO opsdroid.core: Opsdroid is now running, press ctrl+c to exit.
Running as a service¶
It is likely that you are running Opsdroid as a service via something like systemd or Docker.
You can also run PageKite as a serivce, see their FAQ for info.
LocalTunnel¶
Type: SaaS
Cost: Free
Source: Open source (GitHub)
Website: https://localtunnel.github.io/www/
LocalTunnel forwards any local web server to the internet via HTTP/HTTPS.
Install¶
See the official instructions.
Start tunnel¶
Opsdroid will run on port 8080
by default so let’s start an HTTP tunnel to that port.
$ lt --port 8080 --subdomain YOUR_CHOSEN_SUBDOMAIN
your url is: https://LOCALTUNNEL_URL.loca.lt
Configure Opsdroid¶
$ opsdroid config edit
Add the following to your config.
web:
base-url: https://LOCALTUNNEL_URL.loca.lt
Warning
Without the --subdomain
flag the URL will be randomised every time your start lt and you will need
to update your Opsdroid config and restart.
Run Opsdroid¶
$ opsdroid start
INFO opsdroid.logging: ========================================
INFO opsdroid.web: Started web server on https://LOCALTUNNEL_URL.loca.lt
INFO opsdroid.core: Opsdroid is now running, press ctrl+c to exit.
localhost.run¶
Type: SaaS
Cost: Free ($3.50/month for custom domains)
Source: NA
Website: http://localhost.run/
localhost.run uses SSH to port forward a local service to an HTTP/HTTPS endpoint.
Install¶
localhost.run uses SSH, so there is nothing to install.
Start tunnel¶
Opsdroid will run on port 8080
by default so let’s start an HTTP tunnel to that port.
$ ssh -R 80:localhost:8080 ssh.localhost.run
===============================================================================
Welcome to localhost.run!
Head over to https://twitter.com/localhost_run and give us a follow for the
hottest SSH port forwarded local dev env news.
**You need a SSH key to access this service.**
Github has a great howto, follow along with it to get prepared for the change:
https://help.github.com/en/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent
**CUSTOM DOMAINS ARE HERE AND I'M SO EXCITED**
I've been working hard on custom domains and I'm soft launching the custom
domain plan option to existing users. If you own a domain name that you'd like
localhost.run on visit https://admin.localhost.run/ to look at the plan
and set it up.
===============================================================================
Connect to http://LOCALHOST_RUN_URL.localhost.run
{"domain": "LOCALHOST_RUN_URL.localhost.run", "listen_port": 80, "status": "success", "message": "Connect to http://LOCALHOST_RUN_URL.localhost.run"}
Configure Opsdroid¶
$ opsdroid config edit
Add the following to your config.
web:
base-url: https://LOCALHOST_RUN_URL.localhost.run
Warning
Unless you subscribe for custom domains the subdomain will be randomised each time you connect and you will need to update your Opsdroid config and restart.
Run Opsdroid¶
$ opsdroid start
INFO opsdroid.logging: ========================================
INFO opsdroid.web: Started web server on https://LOCALHOST_RUN_URL.localhost.run
INFO opsdroid.core: Opsdroid is now running, press ctrl+c to exit.
Inlets¶
Type: Self hosted
Cost: Free + the cost of your exit-node VM (Hosted PRO version available from $20/month)
Source: Open Source (GitHub)
Website: https://docs.inlets.dev/
Inlets is a client/server application which tunnels traffic between them. You run the server on a machine with a public IP and the client inside your network.
Inlets also has support for Kubernetes to simplify exposing your services to the internet.
Install¶
To install inlets you must install both the client and server applications.
On your local machine install the client following the official instructions.
To install the server you must first create an exit-node server with a public IP address. Inlets has many scripts for creating one automatically for you from a variety of cloud vendors. Alternatively you can install it yourself on a VM and set it to run as a service with this script.
For the sake of this guide we are going to create an inlet on Digital Ocean, which will cost $5/month, using the official script. First we must install doctl and authenticate.
Then we can download and run the DO script.
$ git clone https://github.com/inlets/inlets.git
$ cd inlets
$ ./hack/provision-digitalocean.sh
Creating: DROPLET_NAME
==============================
Droplet: DROPLET_NAME has been created
IP: DROPLET_IP
Login: ssh root@DROPLET_IP
==============================
To destroy this droplet run: doctl compute droplet delete -f DROPLET_NAME
Once you have your inlets server running you must take note of the server token. We can do this by using SSH to connect to the droplet and checking the logs.
$ ssh root@DROPLET_IP
# systemctl status inlets
● inlets.service - Inlets Server Service
Loaded: loaded (/etc/systemd/system/inlets.service; enabled; vendor preset: enabled)
Active: active (running) since Mon 2020-11-02 12:24:15 UTC; 3min 41s ago
Main PID: 1789 (inlets)
CGroup: /system.slice/inlets.service
└─1789 /usr/local/bin/inlets server --port=80 --token=SERVER_TOKEN
Nov 02 12:24:15 inlets7c442412 systemd[1]: Started Inlets Server Service.
Nov 02 12:24:15 inlets7c442412 inlets[1789]: 2020/11/02 12:24:15 Welcome to inlets.dev! Find out more at htt
Nov 02 12:24:15 inlets7c442412 inlets[1789]: 2020/11/02 12:24:15 Starting server - version 2.7.10
Nov 02 12:24:15 inlets7c442412 inlets[1789]: 2020/11/02 12:24:15 Server token: "SERVER_TOKEN
Nov 02 12:24:15 inlets7c442412 inlets[1789]: 2020/11/02 12:24:15 Control Plane Listening on :80
Nov 02 12:24:15 inlets7c442412 inlets[1789]: 2020/11/02 12:24:15 Data Plane Listening on :80
Here we can see the SERVER_TOKEN in the output which we will need to open the tunnel.
Start tunnel¶
Opsdroid will run on port 8080
by default so let’s start an HTTP tunnel to that port. We need to specify the IP of the droplet, the local connection and the token.
$ inlets client \
--remote=DROPLET_IP \
--upstream=http://127.0.0.1:8080 \
--token=SERVER_TOKEN
Configure Opsdroid¶
$ opsdroid config edit
Add the following to your config.
web:
base-url: http://DROPLET_IP
Warning
Only HTTP traffic has been configured here. For secure HTTPS you will need to use a reverse proxy on the exit-node and configure
something like LetsEncrypt. See this tutorial using Caddy <https://blog.alexellis.io/https-inlets-local-endpoints/>
_.
Run Opsdroid¶
$ opsdroid start
INFO opsdroid.logging: ========================================
INFO opsdroid.web: Started web server on http://DROPLET_IP
INFO opsdroid.core: Opsdroid is now running, press ctrl+c to exit.