How to Install Exalate for Zendesk on Docker

You can host Exalate for Zendesk on your own server. To do so, you need to install Exalate on Docker.

How to Install Exalate for Zendesk on Docker

1. Create directory and create docker-compose.yml file

Create a directory to hold the docker-compose file:

cd ~
mkdir exalate-zendesknode

Create or download a docker-compose.yml file

services:
  database:
    restart: unless-stopped
    image: postgres:15.12
    volumes:
      - ./persist/db:/var/lib/postgresql/data
      - ./createdb.sh:/docker-entrypoint-initdb.d/init-user-db.sh
    environment:
      - POSTGRES_PASSWORD=exalate
      - DB_NAME=zendesknode
      - DB_USER=exalate
      - DB_PASS=exalate
    networks:
      - dbnet

  zendesknode:
    restart: unless-stopped
    ports:
      - 9000:9002

    #
    # Change the image tag to the required version
    # Check Release History on docs.exalate.com for an overview
    #
    image: idalko/zendesknode:5.23.0
    depends_on:
      - database #wait for postgres to be started, not for ready
    volumes:
      - ./persist/home:/opt/zendesknode/data
    environment:
      # Add your environment settings here
      - ZENDESKNODE_PG_HOST=database
      - ZENDESKNODE_PG_DB=zendesknode?gssEncMode=disable
      - ZENDESKNODE_PG_USER=exalate
      - ZENDESKNODE_PG_PWD=exalate
      - ZENDESKNODE_PORT=9002


     #As part of the security improvements, Exalate 5.6.0 and above validates the origin header
     #that the browser is sending upon every request to Exalate.
     #In order to validate the origin header, Exalate needs to know what is the URL 
     #leading to it.
     #When you deploy Exalate onto a server, you configure a DNS rule such that 
     #whenever people navigate to foo.com, they reach your server's Exalate. 
     #You set up SSL so that https://foo.com leads to your Exalate on your server. once this is      done you need to set an environment variable NODE_SELF_URL=https://foo.com 
     #for your Exalate docker container.
      
      - NODE_SELF_URL=https://foo.com
     
     # You can use following variables to link the node with nginx proxy
     # Replace exa-zd.exalate.biz with the appropriate FQDN
     # - LETSENCRYPT_HOST=exa-zd.exalate.biz
     # - VIRTUAL_HOST=exa-zd.exalate.biz
     # - VIRTUAL_PORT=9002
     # To hanlde SSL termination we suggest following this article https://docs.exalate.com/docs/scripts-how-to-bring-up-a-reverse-proxy-using-the-jwildernginx-proxy
      
     # CACHE_EXPIRY_DURATION_HOURS variable defines how long the cache will remain in the app.
     # The default value of 8 hours can be changed by specifying the number of hours.
     # - CACHE_EXPIRY_DURATION_HOURS=20

    networks:
      - dbnet
      - default

networks:
  dbnet:
    driver: bridge
  default:
    driver: bridge

Note: the - ZENDESKNODE_PG_DB= and - DB_NAME= must match in order to start the db correctly.

Connecting to Postgres 10 or Higher

For unencrypted connections from Exalate to a Postgres version 10 or higher, you need to disable gssEncMode with the following setting:

# exalate is the name of the database on the postgres instance
#
ZENDESKNODE_PG_DB=exalate?gssEncMode=disable

2. Ensure that a correct database is setup using a createdb.sh

Create or download a createdb.sh file (referenced from docker-compose.yml):

The file must be executable (you can use the command: chmod +x createdb.sh to make the file executable)and should contain the following information:

#!/bin/bash
  
TEST=`psql -U postgres <<-EOSQL
   SELECT 1 FROM pg_database WHERE datname='$DB_NAME';
EOSQL`
  
echo "******CREATING DOCKER DATABASE******"
if [[ $TEST == "1" ]]; then
    # database exists
    # $? is 0
    exit 0
else
psql -U postgres <<-EOSQL
   CREATE ROLE $DB_USER WITH LOGIN ENCRYPTED PASSWORD '${DB_PASS}' SUPERUSER;
EOSQL
  
psql -U postgres <<-EOSQL
   CREATE DATABASE $DB_NAME WITH OWNER $DB_USER ENCODING 'UNICODE' LC_COLLATE 'C' LC_CTYPE 'C' TEMPLATE template0;
EOSQL
  
psql -U postgres <<-EOSQL
   GRANT ALL PRIVILEGES ON DATABASE $DB_NAME TO $DB_USER;
EOSQL
fi
  
echo ""
echo "******DOCKER DATABASE CREATED******"

Ensure that the volumes are included in your backup strategy:

• persist

3. Set Environment Variables if necessary

Below, you can find the environment variables used for the app container. All of them are optional, and in the given example, we've overridden ZENDESKNODE_PG_DB, ZENDESKNODE_PG_USER, and ZENDESKNODE_PG_PWD just to show how to pass different credentials to the Exalate application.

    ports:
      - 9000:9000

    ports:
      - 8080:8080

Using a Proxy for Outgoing Connections

Whenever the Exalate node needs to use a proxy to establish outgoing connections, use the following parameters in the environment (naming should be obvious):

• PROXY_HTTP_HOST
• PROXY_HTTP_PORT
• PROXY_HTTPS_HOST
• PROXY_HTTPS_PORT

4. Start the Application

cd ~/exalate-zendesknode
docker-compose up -d

Verify the installation

After performing the aforementioned steps and checking that the container is up, you should be able to access the Exalate console via http://localhost:9302

5. Register the Node

To be able to fully use the functionality of your new node, it needs to be registered on the mapper.  This mapper acts as a DNS server, mapping tracker URLs to node URLs.

Please raise a ticket on the support portal providing the following:

• URL of the Zendesk instance.
• URL of the Exalate node which has been deployed on-premise.

How to Manage the Application on Docker

Run Queries to the Application's Database

cd ~/exalate-zendesknode
docker exec -it exalate-zendesknode_database_1 bash
su postgres
psql -A $DB_NAME

You can find all tables using PSQLs \dt+ command:

\dt+

All the Postgres SQL queries are permitted

To exit the application's DB:

\q
# \q exits the psql 
exit
# exits the postgres user session
exit
# exits the exalate-zendesknode_database_1 bash session

Inspect the Application's Filesystem

cd ~/exalate-zendesknode
docker exec -it exalate-zendesknode_zendesknode_1 bash

Remove the application

cd ~/exalate-zendesknode
docker-compose rm

Remove the application data

cd ~/exalate-zendesknode
# docker volume ls | grep exalate-zendesknode_vol |  awk '{ print $2 }' | xargs docker volume rm
docker volume rm exalate-zendesknode_voldatabase
docker volume rm exalate-zendesknode_volzendesknode

Issues during the installation of the Exalate server for Zendesk

If you have issues during the installation of the Exalate app for Zendesk, you can find logs describing possible problems inside /tmp.

The name for the file is generated randomly and automatically by the OS, but you can find the file by the creation date.

Issues while running the Exalate server for Zendesk

Logs are generated under the directory: /opt/zendesknode/data/logs.

Refer to these logs to get more information about possible issues and communicate with our support if you need any assistance.

Support

Please read our Support options.