Operating Guide

All listed commands below come from the environment UBUNTU 18.04 LTS x64.

In the following notes, the term Sherpa is used to qualify the Kairntech platform.

Create a backup of database content

If you need to create a backup of the MongoDB database, here are the commands to process. The dump will be first generated on the running container, then copied on the host.

In case the server is configured with authentication:

MONGODUMP=/tmp/mongodump.gz
MONGODB_USERNAME=*******
MONGODB_PASSWORD=***********

docker exec -i sherpa-mongodb mongodump -u"${MONGODB_USERNAME}" -p"${MONGODB_PASSWORD}" --gzip --quiet --archive="${MONGODUMP}"

In case the server is configured without authentication:

MONGODUMP=/tmp/mongodump.gz

docker exec -i sherpa-mongodb mongodump --gzip --quiet --archive="${MONGODUMP}"

Both commands will generate a file stored at /tmp/mongodump.gz on the running container.

Thus to retrieve on the host, the generated file, you’ll need to:

MONGODUMP=/tmp/mongodump.gz
DUMPS=/opt/sherpa-backups
DATENOW=$( date +%Y%m%d_%H%M%S )

docker cp sherpa-mongodb:"${MONGODUMP}" "${DUMPS}"/mongodump-"$( hostname )"-"${DATENOW}".gz

Finally, the gz MongoDB dump file will be stored, on the host, under path /opt/sherpa-backups.

Restore a backup of database content

If you need to restore a MongoDB database content, from a backup, here are the commands to process. The dump will be copied into the running container, and restored on the running container.

In case the server is configured with authentication:

MONGODUMP=/opt/sherpa-backups/mongodump-sherpa-aws-20220724_120001.gz
MONGODB_USERNAME=*******
MONGODB_PASSWORD=***********

docker cp "${MONGODUMP}" sherpa-mongodb:/mongodump.gz

docker exec -it sherpa-mongodb mongorestore -u"${MONGODB_USERNAME}" -p"${MONGODB_PASSWORD}" --drop --gzip --archive=mongodump.gz

In case the server is configured without authentication:

MONGODUMP=/opt/sherpa-backups/mongodump-sherpa-aws-20220821_120001.gz

docker cp "${MONGODUMP}" sherpa-mongodb:/mongodump.gz

docker exec -it sherpa-mongodb mongorestore -u"${MONGODB_USERNAME}" -p"${MONGODB_PASSWORD}" --drop --gzip --archive=mongodump.gz

Delete a specific ElasticSearch index

If you need to delete indexes of a specific project, in the ElasticSearch cluster, you can go with:

docker exec -it sherpa-elasticsearch /bin/bash

INDEXES=$( curl -s -X GET "localhost:9200/_cat/indices" | grep <MY_PROJECT> | cut -d' ' -f3 )

for INDEX in ${INDEXES} ; do curl -X DELETE "localhost:9200/${INDEX}" > /dev/null 2>&1 ; done

When deleting indexes of a given project, an administrator of the platform will have to reindex the whole content of the project (all data are stored on the database).

Modify HTTP port of Sherpa platform

If you need to set a specific port for Sherpa to listen to, you will need to update docker-compose.yml file. By default, Sherpa listens to port 7070.

Change from:

sherpa-core:
    ports:
          - 7070:7070

To (in the example, port is set to 7071):

sherpa-core:
    ports:
          - 7071:7070

Configure a secured HTTPS connexion

The platform will be reachable at http://localhost:7071/sherpa

If you want Sherpa to be served over HTTPS protocol, you’ll need to update file docker-compose.yml file. By default, Sherpa is served over HTTP protocol.

Change from:

sherpa-core:
    environment:
          - sherpa_httpserver_ssl_enabled=false

To:

sherpa-core:
    environment:
          - sherpa_httpserver_ssl_enabled=true

The platform will be reachable at https://localhost:7070/sherpa

Modify default Docker Root Dir

By default, docker working dir, called Docker Root Dir, is located under /var/lib/docker

docker info|grep 'Root Dir'
 Docker Root Dir: /var/lib/docker

If you need to change this default value, because, for instance, the /var partition does not give enough disk space, this can be achieved by adding a file /etc/docker/daemon.json containing:

cat /etc/docker/daemon.json 
{
  "data-root": "/mnt/diskb/docker"
}

ls -l /etc/docker/daemon.json 
-rw-r--r-- 1 root root 299 Dec  6  2021 /etc/docker/daemon.json

Once the file has been added, you’ll have to restart docker service:

systemctl restart docker

Update embedded DOCUMENTATION

In order to benefit a documentation update, corresponding files must be downloaded.
These prerequisite files are stored as Docker volumes. In order to download these items, please run:

sudo su - kairntech

cd ~/embeddings

# INSTALL VERSION DATED 03/09/2023
export DOC_VERSION='2023.03.09'
docker compose -f docker-compose.doc.volumes.yml -p documentation-sherpa up

Once deployed, you should get the following sizes

sudo du -hs /var/lib/docker/volumes/sherpashared_sherpa-doc/_data/
152M    /var/lib/docker/volumes/sherpashared_sherpa-doc/_data/

The Docker container can be removed, once documentation is deployed, via:

docker rm documentation-sherpa-init-job

When updating embedded documentation, a specific volume must be added to the sherpa-core volumes section:

#########################################################################
# SHERPA CORE
    sherpa-core:
    ...
    volumes:
        ...
        - sherpa-doc:/app/kairntech/sherpa/doc

With its corresponding volume declaration (at the end of the docker-compose.yml file):

#########################################################################
volumes:
    ...
    sherpa-doc:
      external: true
      name: sherpashared_sherpa-doc