Quickstart

This quickstart guide provides the first steps to get RacksDB up and ready!

Installation

Several installation methods are supported for RacksDB. It is recommended to use Deb or RPM packages repositories (depending on your Linux distribution) for more integration with your system. Installation from PyPI repository is also available as an alternative. The method to install RacksDB from sources is also documented but it more intended to developers or early testers.

Distribution Packages

Deb (Debian, Ubuntu)

First download packages repository signing key:

# curl -sS https://pkgs.rackslab.io/keyring.asc | gpg --dearmor | tee /usr/share/keyrings/rackslab.gpg > /dev/null

Create /etc/apt/sources.list.d/rackslab.sources with this content:

Debian 12 « bookworm »
Debian 13 « trixie »
Debian unstable « sid »
Ubuntu 24.04 LTS

Types: deb
URIs: https://pkgs.rackslab.io/deb
Suites: bookworm
Components: main
Architectures: amd64
Signed-By: /usr/share/keyrings/rackslab.gpg

Types: deb
URIs: https://pkgs.rackslab.io/deb
Suites: trixie
Components: main
Architectures: amd64
Signed-By: /usr/share/keyrings/rackslab.gpg

Types: deb
URIs: https://pkgs.rackslab.io/deb
Suites: sid
Components: main
Architectures: amd64
Signed-By: /usr/share/keyrings/rackslab.gpg

Types: deb
URIs: https://pkgs.rackslab.io/deb
Suites: noble
Components: main
Architectures: amd64
Signed-By: /usr/share/keyrings/rackslab.gpg

Update packages sources metadata:

# apt update

Install RacksDB packages and dependencies:

# apt install racksdb

Optionally, you can also install RacksDB web application to access the REST API:

# apt install racksdb-web

RPM (RHEL, CentOS, Rocky Linux, Fedora)

On RHEL, CentOS and Rocky Linux versions 8 and 9 some dependencies are missing in standard distribution repositories. You must enable EPEL el8 or el9 repositories to get all requirements on these distributions:

# dnf install -y epel-release

Download and save RPM repository kerying:

# curl https://pkgs.rackslab.io/keyring.asc --output /etc/pki/rpm-gpg/RPM-GPG-KEY-Rackslab

Create DNF repository file /etc/yum.repos.d/rackslab.repo:

RHEL8
RHEL9
Fedora 40
Fedora 41

These packages are also compatible with CentOS 8, Rocky Linux 8 and AlmaLinux OS 8.

[rackslab]
name=Rackslab
baseurl=https://pkgs.rackslab.io/rpm/el8/main/$basearch/
gpgcheck=1
enabled=1
countme=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-Rackslab

These packages are also compatible with CentOS 9, Rocky Linux 9 and AlmaLinux OS 9.

[rackslab]
name=Rackslab
baseurl=https://pkgs.rackslab.io/rpm/el9/main/$basearch/
gpgcheck=1
enabled=1
countme=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-Rackslab

[rackslab]
name=Rackslab
baseurl=https://pkgs.rackslab.io/rpm/fc40/main/$basearch/
gpgcheck=1
enabled=1
countme=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-Rackslab

[rackslab]
name=Rackslab
baseurl=https://pkgs.rackslab.io/rpm/fc41/main/$basearch/
gpgcheck=1
enabled=1
countme=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-Rackslab

Install RacksDB packages:

# dnf install racksdb

Optionally, you can also install RacksDB web application to access the REST API:

# dnf install racksdb-web

PyPI

To install RacksDB python package from PyPI repository, you first need to install on your system some development libraries required by RacksDB external dependencies. For example, on Debian/Ubuntu:

$ sudo apt install libcairo2-dev libgirepository1.0-dev

To install RacksDB python package from PyPI repository, run the following command:

$ pip install racksdb

This automatically installs RacksDB Python package and its dependencies.

You can install Python packages with basic user permissions by using a Python virtual environment.

Additional dependencies are required by racksdb-web command and the REST API. These dependencies can be installed with the web extra by this command:

$ pip install racksdb[web]

From Sources

This installation method is not recommended to normal users as it more complex to manage updates. You might also encounter unexpected or undocumented software behaviours. It is more attended for software developers and early testers.

A copy of the source code of RacksDB can be downloaded from GitHub repository.

To get latest development version of the source code, it is possible to clone the Git repository:

HTTPS
SSH

$ git clone https://github.com/rackslab/racksdb.git

$ git clone git@github.com:rackslab/racksdb.git

If you do not need Git repository history, another option is to download the ZIP archive generated by GitHub. For example:

$ wget https://github.com/rackslab/racksdb/archive/refs/heads/main.zip
$ unzip main.zip
$ cd rackslab-main

It is highly recommended to create and activate a Python virtual environment to install RacksDB. This way, installation of the software and all its dependencies can be performed with basic user permissions, without system-wide modifications.

Some development libraries are required to install RacksDB external dependencies from PyPI repository. For example on Debian/Ubuntu, run this command to install you these development libraries:

$ sudo apt install libcairo2-dev libgirepository1.0-dev

To install RacksDB from sources, run this command in the source tree directory:

$ pip install .

To install frontend Web UI from sources, run this command in frontend/ folder to install all the dependencies:

$ npm install

Please refer to the frontend Web UI README for more details.

Bootstrap database

RacksDB provides several fully working examples of databases. When RacksDB is installed with system packages, these examples are available in /usr/share/doc/python3-racksdb/examples/.

It is recommended to use these examples as a starting point to define your own database.

Run this command to copy a complete example database:

$ sudo cp -r /usr/share/doc/python3-racksdb/examples/db/* /var/lib/racksdb/

Explore content

Now that the database is boostraped with fake example data, you can explore its content with all RacksDB interfaces: command line (CLI), Python library and REST API. The following subsections provide usage examples of these interfaces.

CLI

The database can be explored with racksdb command.

Get datacenters information:

$ racksdb datacenters

Get the content of a rack in JSON format:

$ racksdb racks --name R1-A01 --format json

Get the list of compute nodes in an infrastructure:

$ racksdb nodes --infrastructure mercury --tags compute --list

For more details, please refer to racksdb(1) command manpage.

More links

racksdb(1) command manpage

Python Library

RacksDB provides a Python library to explore the content of the database:

>>> from racksdb import RacksDB
>>> db = RacksDB.load()
>>> for infrastructure in db.infrastructures:
...     print(f"{infrastructure.name} ({infrastructure.description}): {infrastructure.tags}")
...
mercury (Mercury HPC cluster): ['hpc', 'cluster']

More links

Python Library reference documentation

REST API

RacksDB includes a web application that provides a REST API. This web application can be launched with racksdb-web command:

$ racksdb-web

The racksdb-web command must be installed with the additional package racksdb-web. Please refer to the installation section for more details.

The REST API can then be requested with any HTTP clients such as curl:

$ curl http://localhost:5000/v0.4.0/infrastructures?list
["mercury"]

More links

Web UI

RacksDB includes a Web UI to explore content of the database. It can be served by launching racksdb-web with this option:

$ racksdb-web --with-ui

The UI is available by pointing web browser at this URL: http://localhost:5000

More links

Define real database

It is time to adapt the content of the database to match your actual infrastructures. For this purpose, you should edit the files in directory /var/lib/racksdb.

The bootstrap example should help you to guess the structure and properties but the database structure reference documentation provides all details.

The racks and equipments positionning How-tos may also help you to define complex layouts.

More links