Glific - Two Way Open Source Communication Platform

Pre-requisites

There is level of understanding middle to advanced level. It is assumed that you know how to use a terminal, install things and have git; for the backend, and for the frontend use install yarn and react.

1. Software dependency - Postgres server
2. Software dependency - Erlang / Elixir
3. Backend - Download
4. External service - Gupshup. <-- Get a Free trial to get API-key
5. External service - Oban. <-- Needs 100 Euro per month
6. Backend - Install certificate
7. Backend - Config
8. Frontend

1. Software dependency - Postgres server

• Download and start postgres server

For Postgres, for the development server, we default to using postgres/postgres as the username/password. This is configurable

We tested and developed against the following version:

    - postgres : v13.x

2. Software dependency - Erlang / Elixir

• Install Elixir using asdf (check package versions below)

For Ubuntu users you also need to install the inotify-tools package

We tested and developed against the following versions:

    - erlang : 25.3.2
    - elixir : 1.14.5-otp-25

Note: It is important to use asdf to install Erlang and Elixir.

3. Backend - Download

• Download the latest code from GitHub

git clone https://github.com/glific/glific

DO NOT run mix deps.get until the next steps are completed.

4. External service - Gupshup Create and link your Gupshup Account

Gupshup is an external service that connects to WhatsApp

You will need to do the following:

• Create a Gupshup Account
• Create an app and select Access API
• You can name it NewNameHere "GlificTest <-- Bot Name is already in use, then use anotherone"
• Run the following command cp config/dev.secret.exs.txt config/dev.secret.exs
• Find your API Key, check the top right corner and click the profile picture or inside the curl sample message
• Enter your APP name and API Key in the dev.secret.exs file

5. External service - Oban Pro

Oban is a cron-like library. Glific depends 100% on job processing. Oban is required before running mix for Glific to operate.

For contributors: Please get in touch with the team on Discord and get a limited time key.

For production use: You must purchase license. When purchashing you must buy WEB+PRO . After you purchased Go to account and get this information and run this command in glific_backend

mix hex.repo add oban https://getoban.pro/repo --fetch-public-key SHA256:4/abc/edf/gef+aIWPc --auth-key abcdefghi

Replace public key "SHA256:4/abc/edf/gef+aIWPc" with your public key and auth key "abcdefghi" with your auth key.

Make sure your key is in the list

mix hex.repo list

Name        URL                             Public key                                          Auth key
oban        https://getoban.pro/repo        SHA256:4/abc/edf/gef+aIWPc   abdedcqweasdj__KEY_AUTH__asdafasdf

If you see it twice, it will not work and fail, since Oban moved from public repository to private this is how an example of failing looks like

Name        URL                             Public key                                          Auth key
hexpm:oban  https://repo.hex.pm/repos/oban  SHA256:abc/edf/gef+aIWPc     abdedcqweasdj__KEY_AUTH__asdafasdf
oban        https://getoban.pro/repo        SHA256:4/abc/edf/gef+aIWPc   abdedcqweasdj__KEY_AUTH__asdafasdf

this is wrong, and you run mix deps.get it will try to fetch from public and ignore private and fail simply remove the public one

mix hex.repo remove hexpm:oban

Now check again

mix hex.repo list

Name        URL                             Public key                                          Auth key
oban        https://getoban.pro/repo        SHA256:4/abc/edf/gef+aIWPc   abdedcqweasdj__KEY_AUTH__asdafasdf

6. Install certificate - Use SSL for frontend and backend

Before install also you need to create this SSL cert simila to this Go to glific_backend folder in the terminal console.

• Install mkcert (https://github.com/FiloSottile/mkcert)

• mkcert --install

• mkcert glific.test api.glific.test

• mkdir priv/cert

• mv glific.test* priv/cert

• cd priv/cert

• ls -1 Check that glific.test+1-key.pem and glific.test+1.pem exists

  if not then copy any certificate found in there to the correct names
  for example if I see:
  

      ❯ ls -1
      glific.test+*-key.pem
      glific.test+*.pem
      glific.test+*-key.pem
      glific.test+*.pem
      ❯ cp glific.test+*-key.pem glific.test+1-key.pem
      ❯ cp glific.test+*.pem glific.test+1.pem

  And check again

      ❯ ls -1
      glific.test+*-key.pem
      glific.test+*.pem
      glific.test+*-key.pem
      glific.test+*.pem
      glific.test+*-key.pem
      glific.test+*.pem

• Check port 4001 sudo lsof -n -i:4001 | grep LISTEN should return nothing.

• Check hosts file grep glific /etc/hosts

  if returns nothing
  then make sure hosts file has those names added
  `sudo bash -c 'echo "127.0.0.1 glific.test api.glific.test" >> /etc/hosts'`
  

For Windows the steps is as follows:

• Install mkcert (https://github.com/FiloSottile/mkcert)

• Run the following command to install the local CA certificates: mkcert --install

• mkcert glific.test api.glific.test

• mkdir priv/cert

• move glific.test* priv/cert

• cd priv/cert

• dir Check that glific.test+1-key.pem and glific.test+1.pem exists

  if not then copy any certificate found in there to the correct names
  for example if I see:
  

      ❯ dir
      glific.test+*-key.pem
      glific.test+*.pem
      glific.test+*-key.pem
      glific.test+*.pem
      ❯ cp glific.test+*-key.pem glific.test+1-key.pem
      ❯ cp glific.test+*.pem glific.test+1.pem

  And check again

      ❯ dir
      glific.test+*-key.pem
      glific.test+*.pem
      glific.test+*-key.pem
      glific.test+*.pem
      glific.test+*-key.pem
      glific.test+*.pem

• Check port 4001 netstat -ano | findstr :4001 should return nothing.

• Check hosts file bytype %SystemRoot%\System32\drivers\etc\hosts | findstr glific

  if returns nothing
  then make sure hosts file has those names added
  127.0.0.1 glific.test
  127.0.0.1 api.glific.test      
  

7. Backend - Config

• Copy the file: cp config/dev.secret.exs.txt config/dev.secret.exs or simply rename config/dev.secret.exs.txt to config/dev.secret.exs

• Edit config/dev.secret.exs file and add your Gupshup API key and app name gupshup: [api_key: "your_api_key", app_name: "your_app"]

• Copy the file: cp config/.env.dev.txt config/.env.dev or simply rename config/dev.secret.exs.txt to config/dev.secret.exs

  You may leave this file as it is, unless you have different DATABASE_URL or any other configuration

• Run source config/.env.dev

• Run mix deps.get if this fails try first mix local.hex --force then mix deps.get

  if you see this error, then Oban key is wrong or failing. Check step 5. Or contact Oban.

  ❯ mix deps.get Failed to fetch record for 'hexpm:oban/oban_pro' from registry (using cache instead) This could be because the package does not exist, it was spelled incorrectly or you don't have permissions to it Failed to fetch record for 'hexpm:oban/oban_web' from registry (using cache instead) This could be because the package does not exist, it was spelled incorrectly or you don't have permissions to it ** (Mix) Unknown package oban_pro in lockfile

• Run mix setup

• Run iex -S mix phx.server

• Inside the iex (you might need to hit enter/return to see the prompt)

  • Update HSM templates by running the following command:
  • Glific.Templates.sync_hsms_from_bsp(1)

Now you can visit localhost:4000 from your browser.

For Windows the steps is as follows:

• Copy the file: cp config/dev.secret.exs.txt config/dev.secret.exs and edit

• Copy the file: cp config/.env.dev.txt config/.env.dev and edit

• Run this on command prompt:

  cd <path-to-glific-backend>
  set /p=DUMMY < config\.env.dev
  

  Replace with the actual path to the glific_backend directory. This will load the environment variables from the .env.dev file.

• Run mix deps.get if this fails try first mix local.hex --force then mix deps.get

  if you see this error, then Oban key is wrong or failing. Check step 5. Or contact Oban.

  ❯ mix deps.get Failed to fetch record for 'hexpm:oban/oban_pro' from registry (using cache instead) This could be because the package does not exist, it was spelled incorrectly or you don't have permissions to it Failed to fetch record for 'hexpm:oban/oban_web' from registry (using cache instead) This could be because the package does not exist, it was spelled incorrectly or you don't have permissions to it ** (Mix) Unknown package oban_pro in lockfile

• Run mix setup

• Run iex -S mix phx.server

• Inside the iex (you might need to hit enter/return to see the prompt)

  • Update HSM templates by running the following command:
  • Glific.Templates.sync_hsms_from_bsp(1)

Now you can visit localhost:4000 from your browser.

8. Frontend - Install glific frontend

You cannot do much from the glific backend unless you are an API developer. To see Glific in its glory, please install Glific Frontend

Front end credentials

• Phone 917834811114
• Password secret1234

Optional - Using NGROK

• Install ngrok
• Start ngrok to proxy port 4000:
  • Start the backend server: mix phx.server
  • $ ngrok http 4000 --host-header=localhost:4000 (do this in a new window))
  • Remember the URL it assigns you, something like: https://9f6a7c7822d2.ngrok.io
• Goto the Settings Page
• On that page, Search for Manage your Template messaging settings and enable it
• On same page, Search for Callback URL / Link your Bot
• Enter your callback URL that ngrok gave you, add: /gupshup to the end. Something like: https://9f6a7c7822d2.ngrok.io/gupshup/
• Click Set. It should give you a Callback set successfully message. If not, check the above steps.

Updating your instance

For v0.x releases, we will be resetting the DB and not saving existing state. Run the following commands to update your codebase from the glific repository.

• Ensure you are in the top level directory of the glific api code.
• Get the latest code from master: git switch master && git pull
• Ensure you have not modified any files in this directory, by running: git status
• Run the setup command: mix setup

Documentation

• User Guide
• API docs (Postman)
• API docs (Slate)
• Code Documentation
• Recipes - Code smaples for some common use cases in glific.

Learn more

Glific

• Demo Video
• One Pager
• Product Features
• Glific Blogs
• Google Drive

Chat with us

• Chat on Discord

Funders

Thanks to our generous funders over the past few years who have funded this project:

• Project Tech4Dev
• The Agency Fund
• Cisco
• Omidyar Network India
• FOSS United