How to start up your development environment - lemmings-io/02-facebook-example GitHub Wiki

Clojure Bot Startup Guide

Summary

To develop a clojure bot, you'll need:

  • A working vagrant setup
  • A terminal running the lein ring server command within your vagrant virtual machine and your project directory
  • A terminal running the ngrok http 3000 command within your vagrant virtual machine.
  • A Facebook App with its webhook set to your webhook URL

Table of Contens

1. Preparation

Clojure & Vagrant

This guide will assume you completed the [Clojure & Atom Setup Guide](https:// lemmings.io/clojure-and-atom-editor-setup-40f8f09237b4)

You should also have downloaded the files from Clojure Vagrant Setup somewhere onto your computer, e.g.:

macOS/Linux:

/Users/silvio/lemmings/clojure/

Windows:

C:\Users\silvio\lemmings\clojure

This path will subsequently be called your vagrant directory.

Inside your vagrant directory there should be a projects directory containing the actual project you want to work on, e.g.:

macOS / Linux:

/Users/silvio/lemmings/clojure/projects/02-facebook-example

Windows:

C:\Users\silvio\lemmings\clojure\projects\02-facebook-example

This path will subsequently be called your project directory. If you don't have a project directory yet, check out the Facebook Example Project

Note: These paths might look different for you, depending on your operating system, your username or the project you are working on.

To be able to run the ngrok command, you have to run

vagrant provision

from within your vagrant directory once (if you've previously developed a bot on your computer, you can probably skip this step)

Facebook

You'll need your own Facebook Page & App to set up your webhook.

Note: It can be useful to create your own testing page & app which you can then reuse for future development of your own bots - before you publish them with their own proper Facebook Page.

This guide will assume you have already created your Facebook Page, your Facebook App and you already have created a profiles.clj file inside your project directory containing the page access token and verify-token

2. Starting your development environment

To develop a bot we need:

  • a running clojure server (lein ring server-headless)

    The clojure server is the actual program we are working. As a server, it offers a service to its clients and in this case, the client is Facebook, forwarding the messages our Facebook Page receives to our server where they'll be processed according to the code we write.

  • a running ngrok instance (ngrok http 3000)

    The location of our server needs to be reachable by Facebook and that is why we need ngrok. A running ngrok instance provides a temporary public URL, which tunnels all traffic to our local computer.

The clojure server and ngrok each require a seperate terminal session within your virtual machine. Repeat Starting a terminal twice and then proceed to Starting up the server.

Starting a terminal

  1. Start a terminal and change into your vagrant directory via the cd command.

    macOS / Linux:

    cd /Users/silvio/lemmings/clojure/

    Windows:

    cd C:\Users\silvio\lemmings\clojure\

  2. Connect to your virtual machine via

    vagrant ssh

    to connect to your virtual machine. Your Terminal should now look like this: Vagrant Greeting

  3. Change into your project directory via the cd command. As you are already inside the vagrant directory, you only need to enter the remaining path:

    cd projects/02-facebook-example

Starting up the server

At this point should have two open terminals at your hands. We can now proceed with starting our clojure server.

Choose one terminal. As you are already inside the project directory, you only need to enter the remaining path:

cd projects/02-facebook-example

Now start the clojure server with the

lein ring server-headless

command. Your terminal should now look like this:

The clojure server is now running and will continue to do so until you interrupt it via the ctrl+c command.

Note: This terminal will show useful informations and errors. If something doesn't work as expected, take a look here and see if you can find out what's wrong with your code. Your server might also crash completely - in this case you'll have to restart it via the lein ring server-headless command.

Starting up ngrok

Our server should now be running, but it's not reachable from outside our network. We need ngrok to get a temporary URL so we can then tell Facebook where to find our server

Change to the other terminal. where you are already inside your project directory. Now run ngrok http 3000 to start up your ngrok instance. Your terminal window should now look like this:

Running ngrok instance

Your ngrok URL looks similar to this https://431e1705.ngrok.io .

Remember: You'll need to append /webhook to your url when setting up the Facebook webhook. So your Webhook URL looks like this: https://431e1705.ngrok.io/webhook

Note: Whenever you start a new ngrok instance you'll get a new URL and therefore will need to set up the Facebook Webhook again!

Nearly done!

You can now go to your Facebook Developer Dashboard and set up your webhook!

Troubleshooting

The ngrok http 3000 command fails via command not found

You'll probably need to run vagrant provision inside your vagrant directory but outside your vagrant virtual machine (that is, before using the vagrant ssh command).

The lein ring server-headless command fails with some long error message - what does it mean?

Your clojure code you are trying to run likely has some errors in it. Try to read the error message and see if you can find the error. If you are struggling, you can always start a new project by cloning the Facebook Example Project into your projects directory again.

Setting the webhook in the Facebook Developer Dashboard fails.

Check out the HTTP Status Code first to see why it fails: Webhook error message

  • 404: Your webhook URL might be wrong. Please check your ngrok terminal to see if the ngrok URL matches and you also appended /webhook.
  • 403: The Verify Token might not match the token you entered into your profiles.clj. Please doublecheck and remember: After you've made changes to profiles.clj you'll have to restart your clojure server via the lein ring server-headless command.

Working without vagrant

Basically you can just skip the vagrant ssh command and change straight into your project directory to start your clojure server and ngrok