Build and deploy the RidgeRun GStreamer Analytics

From RidgeRun Developer Wiki


Follow Us On Twitter LinkedIn Email Share this page





This section describes the requirements, setup, and deployment steps for the system (server and agent). Follow these instructions to prepare your environment and launch the monitoring stack.

Requirements

  • Python3 and pip
  • Docker and Docker Compose
  • Nox (For environment setup)
  • GstShark (For tracers)

Install Dependencies

Python3 and pip

sudo apt update
sudo apt install python3 python3-pip python3-setuptools python3-wheel -y
pip3 --version

json-glib

sudo apt update
sudo apt install libjson-glib-dev -y

Meson

First, make sure ninja is installed

sudo apt-get install ninja-build

Then use pip3 install Meson directly from its repository.

sudo -H pip3 install git+https://github.com/mesonbuild/meson.git

Docker

To run the services you need Docker Engine and the Docker Compose v2 plugin.

Verify Installation

Check if Docker and Docker Compose are already installed: 

sudo docker -v
# Example output:
# Docker version 26.1.3, build 26.1.3-0ubuntu1~20.04.1
sudo docker compose version
# Example output:
# Docker Compose version v2.35.1

If both commands work, you’re good to go, skip the install section.

Install

If not installed, follow the official Docker documentation:

If you see docker-compose version 1.x.x, remove it: 

sudo apt remove -y docker-compose

Then reinstall Docker Compose v2 using the official instructions above.

Run Docker Without sudo

For our helpers to work, you need to run Docker commands without root privileges. Run the following commands to be able to talk with docker without sudo:

1. Check Docker daemon: 

sudo systemctl status docker

If not running: 

sudo systemctl start docker

2. Grant user permissions to talk to Docker 

sudo usermod -aG docker $USER

3. Refresh group membership: 

newgrp docker
# applies immediately to this shell

4. Verify: 

# should include 'docker'
groups | grep docker

# should run without sudo
docker ps

Nox

It is recommended that you create a python virtual environment: 

MY_VENV=python-venv
python3 -m venv $MY_VENV
source $MY_VENV/bin/activate

Install globally with pip: 

pip3 install nox

GstShark

Follow official instructions to install it here: GstShark Getting Started.

Agent Setup

Before starting the agent, prepare host directories and configure the required environment variables. Important: It is required to have the gst-rranalytics source code before proceeding, RidgeRun provides source code with the acquired RidgeRun products.

Prepare Host Directories

The agent requires directories for runtime and logs:

  • /run/ridgerun-metrics
  • /var/log/ridgerun

These must exist at boot with correct ownership.

Use nox helper to create them, open a Linux console and navigate to the gst-rranalytics source code location: 

cd gst-rranalytics
nox -s prep_host_dirs

Override user/group manually if needed: 

nox -s prep_host_dirs -- user=<name> group=<name>

This installs /etc/tmpfiles.d/ridgerun.conf so the directories are created now and at boot.


Note
/run is volatile, if you skip the helper you may need to create the directories at each boot. The helper adds the configuration to create the directories at boot time


Environment Setup

The repository includes a .env file for services configuration. See the Environment Variables section for a detailed explanation of each option.

You can use a nox helper to auto-detect and generate some of the required values: 

nox -s gen_env

This will populate `.env` with automatically detected values as follows:

  • UID and GID (host user/group IDs)
  • RR_SYSTEM_IP (auto-detected system IP): IMPORTANT: do not use localhost or 127.0.0.1 Use the real designated IP address, for example if your system IP is: 192.168.18.25, set the IP address even if localhost of 127.0.0.1 was auto detected.
  • RR_JETSON_BASE_IMAGE (auto-detected ubuntu version)

And ask the user for the following:

  • RR_SYSTEM_NAME (unique system name to identify the device, e.g jetson-orin-0, edge02)
  • RR_SERVER_IP (IP address of the central monitoring server)

Example: 

nvidia@ubuntu:~/gst-rranalytics$ nox -s gen_env
nox > Running session gen_env
nox > Creating virtual environment (virtualenv) using python3 in .nox/gen_env
Detected host IP '192.168.0.152'. Use this for RR_SYSTEM_IP? [Y/n]: 
Enter RR_SYSTEM_NAME [my-system]: jetson-orin-agx
Enter RR_SERVER_IP [localhost]: 192.168.0.70
nox > Updated .env with UID=1000, GID=1000, RR_SYSTEM_IP=192.168.0.152, RR_SYSTEM_NAME=jetson-orin-agx, RR_SERVER_IP=192.168.0.70, RR_JETSON_BASE_IMAGE=ubuntu:22.04
nox > Session gen_env was successful.

Running the Services

Once .env is prepared, you can launch services. Docker Compose automatically loads the variables from your .env file.

Using Nox (Recommended)

You can manage both the server and agent stacks directly via `nox`. This simplifies the commands.

Server

On your central monitoring host, the first time you need to build the images so start the server with 

nox -s server -- up --build

Start the server with: 

nox -s server -- up

Stop the server and remove services, run only if it is required to stop the service: 

nox -s server -- down

Or start the server in foreground, run only if it is required to run service in foreground: 

nox -s server -- up foreground

Check server status: 

nox -s server -- ps

Agent

Warning
The server services must be running before starting the agents for proper registration
Info
  • Ensure the .env file has been generated/edited before running these commands.
  • The agent uses the values in env (such as RR_SERVER_IP, RR_SYSTEM_NAME, and RR_SYSTEM_IP) to connect correctly to the server.
  • For Jetson devices, confirm that /usr/bin/tegrastats and /sys are available so Jetson metrics can be collected.

On each monitored system, the first time you need to build the images so start the agent with 

nox -s agent -- up --build

For Jetson devices: 

nox -s agent -- up jetson --build

Start the agent: 

nox -s agent -- up

For Jetson devices, start the agent with Jetson support: 

nox -s agent -- up jetson

Stop the agent and remove services, run only if required to stop the service: 

nox -s agent -- down

Or start the agent in foreground, run only if required to run the service in foreground: 

nox -s agent -- up foreground

Check agent status: 

nox -s agent -- ps

Using Docker Compose (Alternative)

If you prefer to use Docker Compose directly, you can run the following commands instead.

Server

Start the server: 

docker compose -f docker-compose.server.yml up -d

Agent

Start the agent: 

docker compose -f docker-compose.agent.yml up -d

Start the agent with Jetson support: 

docker compose -f docker-compose.agent.yml -f docker-compose.jetson.yml up -d

Build Tracers

Build GStreamer tracers for the agent, this directory is included in the gst-rranalytics source code, navigate to the agent directory from the gst-rranalytics root: 

cd agent/gst
meson setup builddir --prefix /usr
meson compile -C builddir

Install the tracers 

sudo meson install -C builddir

And verify that you have the analytics tracers: 

gst-inspect-1.0 | grep analyticstracers

rranalyticstracers:  rrlogtracer (GstTracerFactory)
rranalyticstracers:  rrpipelinebitrate (GstTracerFactory)
rranalyticstracers:  rrpipelineframerate (GstTracerFactory)
rranalyticstracers:  rrpipelineruntime (GstTracerFactory)
rranalyticstracers:  rrproccpuusage (GstTracerFactory)
rranalyticstracers:  rrprociousage (GstTracerFactory)
rranalyticstracers:  rrprocmemusage (GstTracerFactory)

Environment Variables

The .env file is used only by the Agent to configure paths, ports, and integration points. You should adjust these values to match your host system and network setup. The nox -s gen_env task can also auto-generate some values (UID, GID, RR_SYSTEM_IP).

Variable Description Default
RR_SYSTEM_NAME Friendly name of the system/device being monitored. Appears in Grafana dashboards. my-system (change to your system name e.g ridgerun0)
RR_SERVER_IP IP or hostname of the monitoring server (where Prometheus, Loki, Consul run). <change with server-ip>" (change to actual server IP e.g 192.168.0.70)
RR_METRICS_DIR Runtime directory for metrics sockets and files (volatile, under /run). Must exist on host. /run/ridgerun-metrics
RR_METRICS_SOCKET Path to Unix domain socket used by the metrics service. /run/ridgerun-metrics/metrics.sock
RR_METRICS_INTERVAL Collection interval for system metrics, in seconds. 1
RR_LOG_DIR Directory where logs are written before being forwarded to Loki. /var/log/ridgerun
RR_LOKI_URL Push endpoint for Loki log aggregation, using the server IP. http://${RR_SERVER_IP}/loki/api/v1/push
RR_GST_LOG_PATTERN File pattern for GStreamer filtered logs that should be picked up. gst-*-filtered.log
RR_CONSUL_SERVER URL of the Consul service discovery server. http://${RR_SERVER_IP}/:8500
RR_EXPORTER_PORT Port where the Prometheus exporter exposes metrics. 6000
RR_LOGGER_PORT Port used by the logger agent for structured logs. 6001
RR_LOGGER_SOCKET Unix domain socket path for the logger agent. /run/ridgerun-metrics/logger-agent.sock
RR_JETSON_INTERVAL Interval (seconds) for Jetson-specific metrics collection. 1
RR_JETSON_BASE_IMAGE Base Docker image for Jetson agent builds. ubuntu:22.04 (Must match the version of the Jetson Ubuntu)
UID User ID of the host user running the agent containers. Auto-generated by nox gen_env e.g 1001
GID Group ID of the host user running the agent containers. Auto-generated by nox gen_env e.g 1001
RR_SYSTEM_IP IP address of the agent system. Auto-generated by nox gen_env e.g 192.168.0.71



Retrieved from "https://developer.ridgerun.com/wiki/index.php?title=RidgeRun_GStreamer_Analytics/Getting_Started/Build_and_deploy&oldid=72314"