Getting Started With Qorus

In this post, you’ll learn how to get Qorus up and running. You’ll get started by learning how to run a Qorus image in a Docker container. Then, you’ll learn how to communicate with remote Qorus instances, and finally, you’ll test your setup by implementing a “Hello, world” example.

Requirements

Running Qorus in Docker</span

1. Clone our qorus-docker repository with
git clone https://git.qoretechnologies.com/qorus/qorus-docker.git
2. Change the directory to get to Qorus’s Docker compose file.
cd qorus-docker/docker
3. Pull and build the Qorus image with:
docker-compose up -d

This will create a PostgreSQL database schema for Qorus, and local volumes for persistent data. Qorus will start with an HTTPS listener on port 8011 with RBAC disabled.

With RBAC disabled, you can connect to Qorus by visiting https://localhost:8011 without authentication. There, you’ll have access to the Qorus dashboard.

ℹ️ Note: Your browser might issue a security warning when trying to reach Qorus at localhost:8011. This is because Qorus is running with a self-signed certificate. You can safely ignore this warning.

Logging With Qorus

Qorus has a robust logging system. By default, the logs are written to the /opt/qorus/log directory in the Docker container. When setting up Qorus 6+ for the first time, schema archiving is set up with a 90-day data retention period and DB purging of older data as well as daily log rotation, bz2 archiving in the arch subdirectory, and 90-day log file retention.  To enable this in a Qorus instance uprgraded from a previous version where schema archiving and log rotation was not enabled, run the schema-tool -m in your Docker container.

The schema-tool script is located in the /opt/qorus/bin directory on the Docker container. You can execute this script from the host machine by:

docker exec [Qorus CONTAINER ID] bash --login -c "schema-tool -m"
You should see the following output after successful execution:

set config item arch.day-interval = 90
activated the qorus-archiver job
activated the qorus-log-rotator job
changes made; DB archiving and log rotation are enabled

Communicating With Remote Qorus Instances

Qorus comes with a Python client package (qorus-remote) for working with remote Qorus instances. qorus-remote provisions the execution of command-line programs on remote Qorus servers and for the output to be displayed locally in real time. The means of this communication are the REST API and the WebSocket protocol. Therefore, you can use the command line as well as the IDE to work with Qorus.

Install qorus-remote with:

pip install qorus-remote

ℹ️ Note: On Linux, sometimes pip installs executables into a custom directory; in these cases, it’s necessary to add $HOME/.local/bin to your path in your setup script – i.e. $HOME/.bashrc, or $HOME/.bash_profile ( if you are using zsh then ~/.zprofile or ~/.zshrc )

Now, configure the .netrc file to provide the login information required to access a Qorus remote server. For a Qorus server located at https://localhost:8011 and using the Qorus user adm, you should have:

machine localhost
port 8011
secure yes
login adm
password adm
timeout 120
verbose no

.netrc files are usually placed in the home directory; therefore, write the above contents to a file and save it at:
On Linux and Mac machines:
~/.netrc-qorus-local
On Windows:
%USERPROFILE%\qorus\netrc-qorus-local

Usage

qorus-remote-commands [-h|--help|--usage] <NETRC-FILE> <COMMAND> [<COMMAND-ARGS> ...]
A few of the commands possible with qorus-remote:
  • oload – loads sources and configuration into the Qorus server.
  • qctl – main interface for the qorus cluster.
  • qrest – the command-line REST API interface.
  • qdp – the command-line interface to the Data Provider API
The complete command list is available in our qorus-remote repository

Aliases

It’s recommended to create aliases for each of the commands, like:

On Windows Command Prompt

  • DOSKEY oload=qorus-remote-commands %USERPROFILE%\qorus\netrc-qorus-local oload $*
  • DOSKEY qctl=qorus-remote-commands %USERPROFILE%\qorus\netrc-qorus-local qctl $*
  • DOSKEY qrest=qorus-remote-commands %USERPROFILE%\qorus\netrc-qorus-local qrest $*
  • DOSKEY qdp=qorus-remote-commands %USERPROFILE%\qorus\netrc-qorus-local qdp $*
On Linux and Mac machines
  • alias oload='qorus-remote-commands ~/.netrc-qorus-local oload $*'
  • alias qctl='qorus-remote-commands ~/.netrc-qorus-local qctl $*'
  • alias qrest='qorus-remote-commands ~/.netrc-qorus-local qrest $*'
  • alias qdp='qorus-remote-commands ~/.netrc-qorus-local qdp $*'

and so on…

After setting aliases, you can test the python client (qorus-remote) by:

  • qctl ps – get a list of cluster processes
  • qctl threads qorus-core – get a list of thread stacks for the qorus-core process
  • oload -Ls – lists the services installed in the database
  • qrest system/instance-key – returns the system instance key name from the REST API (configured in $OMQ_DIR/etc/options – change requires a restart)

ℹ️ Note: $OMQ_DIR refers to the /opt/qorus on the Docker container. On linux/mac host this is (docker compose file directory)/omq/user directory, and on windows host (docker compose file directory)\omq\user directory. docker compose file directory is the directory from which you ran the docker-compose up -d instruction earlier.

Grab your FREE application integrations eBook.
You'll quickly learn how to connect your apps and data into robust processes!