- Pre-requisites
- External Services
- Clone Backend Repository
- Install Frontend
- Unit Testing
- Optional - Setup HSM Messaging
- Optional - Using NGROK
- Updating Your Instance
- Documentation
- Learn More
- Chat With Us
- Funders
Install Elixir using asdf
(check package versions below).
For Ubuntu users, you also need to install the inotify-tools
package:
sudo apt install inotify-tools
We tested and developed against the following versions (please check .tool-versions
in the repository for the latest version we are using):
- erlang : 27.3.3
- elixir : 1.18.3-otp-27
After installing the asdf
core, install the Erlang and Elixir plugins:
asdf plugin add erlang https://github.com/asdf-vm/asdf-erlang.git
asdf plugin add elixir https://github.com/asdf-vm/asdf-elixir.git
Install all required versions listed in .tool-versions
by
asdf install
If you get any warnings for missing packages, just install them using apt
and try again.
Note: It is important to use
asdf
to install Erlang and Elixir.
Note: Windows users should use WSL (Windows Subsystem for Linux) to install and manage Elixir and Erlang via asdf
Install from PostgreSQL official site
Tested with Postgres versions:
- v13.x
- v14.x
- v17.x
git clone git@github.com:glific/glific.git
Before completing the install, you need to create an SSL cert. Go to the glific folder in the terminal console, and: Install from mkcert GitHub repo
To generate a certificate:
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 exist
Check port 4001:
sudo lsof -n -i:4001 | grep LISTEN
should return nothing.
Check host file
:
grep glific /etc/hosts
If it returns nothing, add these 3 lines to the hosts file:
127.0.0.1 glific.test
127.0.0.1 api.glific.test
127.0.0.1 postgres
mkcert --install
mkcert glific.test api.glific.test
mkdir priv/cert
mv glific.test* priv/cert
cd priv/cert
dir # Check that glific.test+1-key.pem and glific.test+1.pem exist
Check port 4001:
netstat -ano | findstr :4001
should return nothing.
Check host file by type
:
%SystemRoot%\System32\drivers\etc\hosts | findstr glific
If it returns nothing, add these 3 lines to the hosts file:
127.0.0.1 glific.test
127.0.0.1 api.glific.test
127.0.0.1 postgres
Gupshup is a messaging platform that enables bots and businesses to communicate with users over WhatsApp and other channels. In Glific, we use Gupshup to send and receive WhatsApp messages via API integration.
- Register: Gupshup Developer
- Create an app and select Access API
- You can name it NewNameHere "GlificTest <-- Bot Name is already in use, then use another one"
- Run the following command cp config/dev.secret.exs.txt config/dev.secret.exs
- Now, in Gupshup, 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 using any text editor.
Oban is a job processing library for Elixir. It supports features like background jobs and scheduled tasks (cron-style). Oban is required before running mix for Glific to operate.
For contributors on social impact projects (including NGOs):
Please get in touch with the team on Discord and request a limited-time Oban Pro key. Once provided, run the following command to add the Oban repository with your credentials:
mix hex.repo add oban https://getoban.pro/repo --fetch-public-key SHA256:4/abc/edf/gef+aIWPc --auth-key abcdefghi
For others, if you want to use the free Oban solution People have contributed code changes to allow Glific to work with the free version of Oban. You can view the details here: #2391
For production use:
*You must purchase a license for Oban Pro to use advanced features in production.
*Note: Oban Web is now open source and does not require a license.
*If you're using Oban Pro, after purchasing the license:
Go to your Oban account dashboard.
Run the following command inside your glific_backend directory:
mix hex.repo add oban https://getoban.pro/repo --fetch-public-key SHA256:4/abc/edf/gef+aIWPc --auth-key abcdefghi
where public key "SHA256:4/abc/edf/gef+aIWPc" is replaced by your public key and auth key "abcdefghi" is replaced by your auth key.
Make sure your key is in the list:
mix hex.repo list
Name URL Public key Auth key
hexpm https://repo.hex.pm SHA256:abc/edf/gef+aIWPc
oban https://getoban.pro/repo SHA256:4/abc/edf/gef+aIWPc abdedcqweasdj__KEY_AUTH__asdafasdf
If you see two Auth key entries - caused by Oban moving from a public to a private repository - it will fail. This is what 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. When you run mix deps.get as is, it will try to fetch from the public repository instead of the private one and fail. Simply follow the instructions below to remove the public key:
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
-
Run:
cp config/.env.dev.txt config/.env.dev
-
Run
mix deps.get
if this fails trymix local.hex --force
followed bymix deps.get
if you see the error below, then your 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
At this point, you may get an error sayingpassword authentication failed for user "postgres"
, in which case, you need to configure the postgres server properly:
createuser postgres -s # needed for more recent versions of postgres on MacOS
sudo -u postgres psql
ALTER USER postgres WITH PASSWORD 'postgres';
Exit the PostgreSQL terminal by typing \q
and pressing Enter. Run mix setup
again.
- Run
iex -S mix phx.server
Now you can visit https://glific.test:4001
from your browser.
For Windows the steps is as follows:
-
Copy the file:
cp config/dev.secret.exs.txt config/dev.secret.exs
-
Copy the file:
cp config/.env.dev.txt config/.env.dev
. You may not need to edit the default values for DB URL and hostnames in this file if they look suitable for your needs. -
Run this on the 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 trymix local.hex --force
followed bymix deps.get
if you see the error below, then your 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 https://glific.test:4001
from your browser.
- Phone:
917834811114
- Password:
Secret1234!
After setting up both backend and frontend repositories, you need to sync the Gupshup settings:
- Login to the frontend using the credentials provided above
- Go to Settings -> Gupshup Settings
- Click on "Save" button
- Wait for confirmation that settings were synced successfully.
This step is crucial as it fetches and stores your Gupshup app_id
in the database, which is required for proper functioning of various APIs including the wallet API.
Execute All Tests with:
mix test_full
To run Specific test File
mix test Path_to_the_specific_test_file_you_want_to_run.
- Add ISV credentials in the database
- Sync HSMs:
Glific.Templates.sync_hsms_from_bsp(1)
- Download: ngrok
- Run:
ngrok http 4000 --host-header=glific.test:4000
- Set webhook in Gupshup app settings to
https://<ngrok-url>/gupshup
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 deps.get, compile, ecto.migrate
Thanks to our funders for supporting Glific: