A couple of weeks ago, Dan Jenkins kindly wrote a guest blog post about Dana — an up-and-coming open source project which helps to highlight some of the great video-conferencing capabilities in Asterisk. In this blog post, I’d like to expand on that, and show you how to get a simple video-conferencing solution up and running with Asterisk and Dana.

This blog post assumes you already have Asterisk 16.9 or later up and running on your system, that you’re using chan_pjsip, and that you’re comfortable on the Linux command-line. You should have already downloaded and installed codec_opus module as well. You’ll also need a valid TLS certificate for your server, as the WebRTC communication between Asterisk and Dana needs to be encrypted properly. Last but not least, you’ll need the node.js javascript engine and the yarn utility (known as yarnpkg on some systems) for building Dana.

Getting Asterisk configured for WebRTC

Before we install Dana, we first need to configure Asterisk for the WebRTC communication that’s going to go back and forth between Dana and Asterisk. First, we’ll configure a secure websocket transport in chan_pjsip. Open your pjsip.conf config file (usually located in the /etc/asterisk directory), and add the following section if you don’t already have a transport with protocol set to “wss”.

[transport-wss]
type=transport
protocol=wss

Next, we’ll need to create an endpoint in pjsip.conf for Dana to communicate with. Add the following section:

[webrtc]
type=endpoint
aors=webrtc
auth=webrtc
dtls_auto_generate_cert=yes
webrtc=yes
context=videobridge
disallow=all
allow=opus,g722,ulaw,vp9,vp8,h264
max_audio_streams = 1
max_video_streams = 15

As you can see, the endpoint is fairly straightforward. The “context” setting tells where to send authenticated calls into the Asterisk dialplan — in this case, a context called “videobridge”. We’ll use that a bit later when we configure the dialplan. Also note that this endpoint refers to two other PJSIP objects that we’ll need to add — an “aors” object for the addresses of record, and an “auth” object for authentication — both of which have the name of “webrtc”. Let’s add them both now by adding the following to pjsip.conf as well:

[webrtc]
type=aor
max_contacts=100
remove_existing=yes

[webrtc]
type=auth
auth_type=userpass
username=webrtc
password=pleasechangeme ; This is a completely insecure password!
; Do NOT expose this system to the Internet without utilizing
; a better password.

Obviously, you’ll want to choose a different password than the one I have chosen above.

That’s it for the configuration of chan_pjsip. Next up, let’s configure the ConfBridge profile. We need to ensure that the video mode is set to SFU for the default_bridge in confbridge.conf:

[default_bridge]
type=bridge
video_mode=sfu

You may already have a default_bridge entry present from the sample configuration file. If so it is sufficient to uncomment and ensure video_mode is set to sfu.

Now on to the dialplan. As stated earlier, chan_pjsip is configured to send authenticated calls from the “webrtc” endpoint to the “videobridge” context in the dialplan. Let’s define that now. Open your extensions.conf configuration file, and add the following (assuming you don’t already have a context named “videobridge”):

[videobridge]
exten=>testing,1,ConfBridge(${EXTEN},default_bridge,default_user,sample_user_menu)

The section we just added to the dialplan tells Asterisk to put calls to the “testing” extension through to a conference bridge that matches the extension (“testing” in this case) with lots of defaults. Of course, you could change lots of settings on the conference bridge itself, but that’s beyond the scope of this blog post.

Next up, we’ll need to configure Asterisk’s built-in HTTP web server — first so that Dana can talk to Asterisk over the websocket connection, and second so that the HTTP web server can serve up the files for Dana directly. While we could set up Dana under a more traditional web server like Apache or Nginx, for simplicity sake we’ll use what we already have in Asterisk for this demo.

Open up the Asterisk http.conf configuration file. In the [general] section, make sure that the HTTP server is enabled, as shown below. You should also set the bind address and port, to tell Asterisk which IP address and TCP port to listen on. In my case, I’m telling Asterisk to listen for traffic coming from the local machine (127.0.0.1) and to listen on port 8080:

enabled=yes
bindaddr=127.0.0.1
bindport=8080

Next up, we’ll need to enable the “static” setting for the HTTP server. This tells Asterisk that in addition to serving up dynamic content (such as AMI over HTTP), it should also serve up the static files from Dana as well.

enable_static=yes

Now that we’ve got the basics down for the HTTP server, let’s configure our TLS secure web server settings as well. We need to tell Asterisk to enable secure HTTP over TLS, and which address and port to listen for TLS-encrypted web connections. In my case, I’m telling it to bind to 0.0.0.0 (which means all local IP addresses on this server), and port 8089. I’m also pointing the “tlscertfile” setting at my TLS certificate for this server, and “tlsprivatekey” at the private key for that TLS certificate. (And while getting a TLS certificate is slightly beyond the scope of this blog article as well — I hope you won’t mind a shameless plug for my favorite open source Let’s Encrypt client, named lego. Lego is a client, written in the Go language, that made it simple to get a TLS certificate for my demo system using either a DNS or HTTP challenge.)

tlsenable=yes
tlsbindaddr=0.0.0.0:8089
tlscertfile=/etc/asterisk/keys/pbx.jaredsmith.net.crt
tlsprivatekey=/etc/asterisk/keys/pbx.jaredsmith.net.key

The final bit we need in http.conf is a redirect. While not strictly necessary, this will be used for convenience. The redirect says that if I were to use my web browser to visit the main page of the Asterisk web server, I would be redirected to /static/dana/index.html — which is where we’ll be installing Dana shortly. So, add this line to http.conf as well:

redirect=/ /static/dana/index.html

Now that we have Asterisk configured and ready, go ahead and restart it so that it can re-read all the configuration files that we’ve changed. Please pay close attention to any error messages in the log that might indicate a typo or syntax error in the configurations we’ve added.

Building and installing Dana

Dana is hosted on GitHub, and can be downloaded using the “git” command-line utility. In my case, I already have a directory called /home/jsmith/Git, and I’m going to put the Dana source in a directory underneath it:

cd /home/jsmith/Git
git clone https://github.com/nimbleape/dana-the-stream-gatekeeper
cd dana-the-stream-gatekeeper/

That created a new directory called “dana-the-stream-gatekeeper”, which contains the source code for Dana.

We need to make two small changes to make this work better when running under the web server inside of Asterisk. (These changes are not necessary if you’re running Dana the webroot of a traditional web server like Apache or Nginx.) The first is to add a line to package.json, right underneath the line that says “name”: “dana-tsg”,

“homepage” : "https://pbx.jaredsmith.net:8089/static/dana",

This tells Dana where it will be served up from. The second minor change we need to make to Dana also involves helping it know where it’s being served up from. Underneath Dana’s directory, edit the src/components/Routes.js file. Around line 27 you’ll see a line that looks like this:

<Route exact path="/" component={Login} />

Change it to instead read:

<Route exact path="/static/dana/index.html" component={Login} />

Now that you’ve made those two minor changes, let’s build dana. This is as simple as running the “yarn build” command. (On some systems, this will be “yarnpkg build” instead.)

This builds a static copy of the Dana code in the “build/” subdirectory. Now simply move this build directory under Asterisk’s http static directory (usually /var/lib/asterisk/static-http), and rename it to “dana”:

sudo mv build /var/lib/asterisk/static-http/dana

The Moment of Truth

Now that Dana is installed, let’s try it out! First, open your browser and navigate to the Asterisk HTTP server on the TLS port — mine is https://pbx.jraedsmith.net:8089/. If you’ve followed the instructions above, you should get a login page that looks something like this:

Click on the gear icon in the upper right-hand corner, so that you can configure Dana to point at Asterisk. Fill out the values as shown below, substituting your server address in the second and third boxes, and using the password that you used in pjsip.conf above in the fourth box. The last box (for the MQTT WSS URI) can be left blank. Click Finish.

Now, go back to your web server address again (https://pbx.jaredsmith.net:8089/ for me) again, and enter “testing” for the room name and press the “Join” button. This corresponds with the extension we created in the “videobridge” context in the dialplan. You can obviously create as many rooms as you like in the dialplan, but for this demo we’ll use the “testing” extension that we created.

After entering the room and pressing Join, you’ll be given a chance to check your video settings before joining the conference, as shown below:

Unfortunately, I wasn’t looking very “spiffing” when I wrote this, so please forgive me. Click on the button that says “Yes, Yes I Do” and you’ll be entered into the conference.

And that’s it! You’ve got Dana up and running! In a future blog post, I’ll go into detail about getting transcriptions (thanks to Google’s speech to text service) with Dana and Asterisk. Until then, enjoy! If you have any additional questions about Dana, or feel like contributing new features, please give feedback on the Dana GitHub page at https://github.com/nimbleape/dana-the-stream-gatekeeper. As always, send feedback on Asterisk and any of Sangoma’s other open source code to opensourcefeedback@sangoma.com.