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.list with this content:

  • Debian 12 « bookworm »

  • Debian 13 « trixie »

  • Debian unstable « sid »

  • Ubuntu 22.04 LTS « jammy »

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: ubuntu22.04
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 RHEL8, CentOS 8 and Rocky Linux 8 some dependencies are missing in standard distribution repositories. You must enable EPEL el8 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

  • Fedora 38

  • Fedora 39

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
[rackslab]
name=Rackslab
baseurl=https://pkgs.rackslab.io/rpm/fc38/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/fc39/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, 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.

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

$ pip install .

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/rackslab/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/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

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

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/infrastructures?list
["mercury"]
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