hidra

README

Hidra

Hidra allows you to monitor the status of your services without headaches.

Installation

Website monitoring with Hidra: A step-by-step guide

Precompiled binaries

Precompiled binaries for released versions are available in the release section on GitHub. Using the latest production release binary is the recommended way of installing Hidra. You can find latest release here

Docker images

Docker images are available on GitHub Container Registry.

Package repositories

If you want to install Hidra easily, please use the package repositories.

# Debian/Ubuntu
curl https://repo.hidra.cloud/apt/gpg.key | sudo apt-key add -
echo "deb [trusted=yes] https://repo.hidra.cloud/apt /" | sudo tee /etc/apt/sources.list.d/hidra.list
apt update
apt install -y hidra

# RedHat/CentOS
curl https://repo.hidra.cloud/rpm/gpg.key | sudo rpm --import -
echo "[hidra]" | sudo tee /etc/yum.repos.d/hidra.repo
echo "name=Hidra" | sudo tee -a /etc/yum.repos.d/hidra.repo
echo "baseurl=https://repo.hidra.cloud/rpm/" | sudo tee -a /etc/yum.repos.d/hidra.repo
echo "enabled=1" | sudo tee -a /etc/yum.repos.d/hidra.repo
echo "gpgcheck=1" | sudo tee -a /etc/yum.repos.d/hidra.repo

yum install -y hidra

After installing Hidra, test the installation by running:

hidra version

By default, Hidra will install one systemd unit for running hidra exporter, disabled by default. You can enable it by running:

systemctl enable hidra_exporter --now

You can modify the behaviour of exporter by editing the file /etc/hidra_exporter/config.yml, and you can add samples directly to /etc/hidra_exporter/samples/ folder, and after adding them, you can reload the service by running:

systemctl reload hidra_exporter

Using install script

You can use the install script to install Hidra on your system. The script will download the latest release binary and install it in your system. You can find the script here.

sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/hidracloud/hidra/main/install.sh)"

Build from source

To build Hidra from source code, you need:

• Go version 1.19 or greater.
• Goreleaser

To build Hidra, run the following command:

goreleaser release --snapshot --rm-dist

You can find the binaries in the dist folder.

Usage

Exporter

Hidra has support for exposing metrics to Prometheus. If you want to use Hidra in exporter mode, run:

hidra exporter /etc/hidra/exporter.yml

You can find an example of the configuration file here

Grafana

You can find a Grafana dashboard here

Test mode

Hidra has support for running in test mode. Test mode will allow you to run one time a set of samples, and check if the results are as expected. If you want to use Hidra in test mode, run:

hidra test sample1.yml sample2.yml ... samplen.yml

If you want to exit on error, just add the flag --exit-on-error.

Sample examples

You can find some sample examples here

Compose

You can find an example of a Compose file here

Samples

Samples are the way Hidra knows what to do. A sample is a YAML file that contains the information needed to run a test. You can find some sample examples here. You can also find a sample example below:

# Description of the sample
description: "This is a sample to test the HTTP plugin"
# Tags is a key-value list of tags that will be added to the sample. You can add here whatever you want.
tags:
  tenant: "hidra"
# Interval is the time between each execution of the sample.
interval: "1m"
# Timeout is the time that Hidra will wait for the sample to finish.
timeout: "10s"
# Steps is a list of steps that will be executed in order.
steps:
    # Plugin is the name of the plugin that will be used to execute the step.
  - plugin: http
    # Action is the action that will be executed by the plugin.
    action: request
    # Parameters is a key-value list of parameters that will be passed to the plugin.
    parameters:
      url: https://google.com/
  - plugin: http
    action: statusCodeShouldBe
    parameters:
      statusCode: 301

You can find more information about plugins in next section.

Plugins

• browser
• dns
• ftp
• http
• icmp
• tcp
• tls
• udp
• string

Development

Directory structure

The project follows the de facto standard Go project layout with the additions below:

• Containerfile, compose.yml, Makefile, .dockerignore and .env.example contain the configuration and manifests that define the development and runtime environments with OCI containers and Compose.
• .github holds the GitHub Actions CI/CD pipelines.

Getting started

This project comes with a containerized environment that has everything necessary to work on any platform without having to install dependencies on the developers' machines.

TL;TR

make

Requirements

Before starting using the project, make sure that the following dependencies are installed on the machine:

• Git.
• An OCI runtime, like Podman Desktop or Docker Desktop.
• Compose.

It is necessary to install the latest versions before continuing. You may follow the previous links to read the installation instructions.

Initializing

First, initialize the project and run the environment.

make

Then, download third-party dependencies.

make deps

You may stop the environment by running the following command.

make down

Usage

Commands must be run inside the containerized environment by starting a shell in the main container (make shell).

Running the development server

Run the following command to start the development server:

make run

Note that Git is not available in the container, so you should use it from the host machine. It is strongly recommended to use a Git GUI (like VS Code's or Fork) instead of the command-line interface.

Running tests

To run all automated tests, use the following command.

make test

Debugging

It is possible to debug the software with Delve. To run the application in debug mode, run the command below.

make debug

For more advanced scenarios, such as debugging tests, you may open a shell in the container and use the Delve CLI directly.

make shell
dlv test --listen=:2345 --headless --api-version=2 <package>