= Quickstart
:venv-doc: https://docs.python.org/3/tutorial/venv.html

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

[#install]
== Installation

Several installation methods are supported for RacksDB. It is recommended to use
xref:#deb[Deb] or xref:#rpm[RPM] packages repositories (depending on your Linux
distribution) for more integration with your system. Installation from
xref:#pypi[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

[#apt]
==== APT (Debian, Ubuntu)

First download packages repository signing key:

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

Create [.path]#`/etc/apt/sources.list.d/rackslab.sources`# with this content:

[tabs]
======
Debian 12 _« bookworm »_::
+
====
[source]
----
Types: deb
URIs: https://pkgs.rackslab.io/deb
Suites: bookworm
Components: main
Architectures: amd64
Signed-By: /usr/share/keyrings/rackslab.gpg
----
====

Debian 13 _« trixie »_::
+
====
[source]
----
Types: deb
URIs: https://pkgs.rackslab.io/deb
Suites: trixie
Components: main
Architectures: amd64
Signed-By: /usr/share/keyrings/rackslab.gpg
----
====

Debian 14 _« forky »_::
+
====
[source]
----
Types: deb
URIs: https://pkgs.rackslab.io/deb
Suites: forky
Components: main
Architectures: amd64
Signed-By: /usr/share/keyrings/rackslab.gpg
----
====

Debian unstable _« sid »_::
+
====
[source]
----
Types: deb
URIs: https://pkgs.rackslab.io/deb
Suites: sid
Components: main
Architectures: amd64
Signed-By: /usr/share/keyrings/rackslab.gpg
----
====

Ubuntu 24.04 LTS::
+
====
[source]
----
Types: deb
URIs: https://pkgs.rackslab.io/deb
Suites: ubuntu24.04
Components: main
Architectures: amd64
Signed-By: /usr/share/keyrings/rackslab.gpg
----
====

Ubuntu 26.04 LTS::
+
====
[source]
----
Types: deb
URIs: https://pkgs.rackslab.io/deb
Suites: ubuntu26.04
Components: main
Architectures: amd64
Signed-By: /usr/share/keyrings/rackslab.gpg
----
====
======

Update packages sources metadata:

[source,console]
----
# apt update
----

Install RacksDB packages and dependencies:

[source,console]
----
# apt install racksdb
----

Optionally, you can also install RacksDB web application to access the
xref:#restapi[REST API]:

[source,console]
----
# apt install racksdb-web
----

[#dnf]
==== DNF (RHEL, CentOS, Rocky Linux, Fedora)

[NOTE]
====
On RHEL, CentOS and Rocky Linux versions 8, 9 and 10 some dependencies are
missing in standard distribution repositories. You must enable
https://docs.fedoraproject.org/en-US/epel/[EPEL] _el8_, _el9_ or _el10_
repositories to get all requirements on these distributions:

[source,shell]
----
# dnf install -y epel-release
----
====

Download and save RPM repository kerying:

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

Create DNF repository file [.path]#`/etc/yum.repos.d/rackslab.repo`#:

[tabs]
======
RHEL8::
+
====

NOTE: These packages are also compatible with https://www.centos.org/[CentOS 8],
https://rockylinux.org/[Rocky Linux 8] and
https://almalinux.org/[AlmaLinux OS 8].

[source]
----
[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
----
====

RHEL9::
+
====

NOTE: These packages are also compatible with https://www.centos.org/[CentOS 9],
https://rockylinux.org/[Rocky Linux 9] and
https://almalinux.org/[AlmaLinux OS 9].

[source]
----
[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
----
====

RHEL10::
+
====

NOTE: These packages are also compatible with https://www.centos.org/[CentOS 10],
https://rockylinux.org/[Rocky Linux 10] and
https://almalinux.org/[AlmaLinux OS 10].

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

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

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

Install RacksDB packages:

[source,console]
----
# dnf install racksdb
----

Optionally, you can also install RacksDB web application to access the
xref:#restapi[REST API]:

[source,console]
----
# dnf install racksdb-web
----

[#zypper]
==== Zypper (SLES, openSUSE)

This procedure works on
https://www.suse.com/products/server/[SUSE Linux Entreprise Server (SLES)] and
https://www.opensuse.org/[openSUSE LEAP].

Import RPM siging key:

[source,console]
----
# rpm --import https://pkgs.rackslab.io/keyring.asc
----

Run this command to add package repositories:

[tabs]
======
SLES 15::
+
====
NOTE: This package repository is also compatible with
https://www.opensuse.org/[openSUSE Leap 15].

[source,console]
----
# zypper addrepo --check --gpgcheck-allow-unsigned-repo --refresh \
  https://pkgs.rackslab.io/rpm/suse15/main/x86_64 rackslab-main
----
====

SLES 16::
+
====
NOTE: This package repository is also compatible with
https://www.opensuse.org/[openSUSE Leap 16].

[source,console]
----
# zypper addrepo --check --gpgcheck-allow-unsigned-repo --refresh \
  https://pkgs.rackslab.io/rpm/suse16/main/x86_64 rackslab-main
----
====
======

Install RacksDB packages:

[source,console]
----
# zypper install racksdb
----

Optionally, you can also install RacksDB web application to access the
xref:#restapi[REST API]:

[source,console]
----
# zypper install racksdb-web
----

[#pypi]
=== PyPI

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

include::partial$pip-deps.adoc[]

To install RacksDB python package from https://pypi.org/[PyPI repository], run
the following command:

[source,console]
----
$ pip install racksdb
----

This automatically installs RacksDB Python package and its dependencies.

TIP: You can install Python packages with basic user permissions by using a
{venv-doc}[Python virtual environment].

Additional dependencies are required by
xref:usage:racksdb-web.adoc[`racksdb-web` command] and the
xref:usage:rest.adoc[REST API]. These dependencies can be installed with the
`web` extra by this command:

[source,console]
----
$ pip install racksdb[web]
----

[#sources]
=== From Sources

CAUTION: 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
https://github.com/rackslab/racksdb[GitHub repository].

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

[tabs]
======
HTTPS::
+
====
[source,console]
----
$ git clone https://github.com/rackslab/racksdb.git
----
====

SSH::
+
====
[source,console]
----
$ 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:

[source,console]
----
$ wget https://github.com/rackslab/racksdb/archive/refs/heads/main.zip
$ unzip main.zip
$ cd rackslab-main
----

NOTE: It is highly recommended to create and activate a
https://docs.python.org/3/tutorial/venv.html[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 https://pypi.org/[PyPI repository]. For example on Debian/Ubuntu, run this
command to install you these development libraries:

include::partial$pip-deps.adoc[]

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

[source,console]
----
$ pip install .
----

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

[source,console]
----
$ npm install
----

NOTE: Please refer to the
https://github.com/rackslab/RacksDB/blob/main/frontend/README.md[frontend Web UI
README] for more details.

[#examples]
== Bootstrap database

RacksDB provides several fully working examples of databases. When RacksDB is
installed with system packages, these examples are available in
[.path]#`/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:

[source,console]
----
$ 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 xref:usage:racksdb.adoc[`racksdb`] command.

* Get datacenters information:

[source,console]
----
$ racksdb datacenters
----

* Get the content of a rack in JSON format:

[source,console]
----
$ racksdb racks --name R1-A01 --format json
----

* Get the list of compute nodes in an infrastructure:

[source,console]
----
$ racksdb nodes --infrastructure mercury --tags compute --list
----

For more details, please refer to xref:usage:racksdb.adoc[`racksdb`(1) command
manpage].

[sidebar]
--
.More links
* xref:usage:racksdb.adoc[`racksdb`(1) command manpage]
--

=== Python Library

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

[source,python]
----
>>> 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']
----

[sidebar]
--
.More links
* xref:usage:lib.adoc[Python Library reference documentation]
--

[#restapi]
=== REST API

RacksDB includes a web application that provides a REST API. This web
application can be launched with xref:usage:racksdb-web.adoc[`racksdb-web`]
command:

[source,python]
----
$ racksdb-web
----

CAUTION: The `racksdb-web` command must be installed with the additional package
`racksdb-web`. Please refer to the xref:#install[installation section] for more
details.

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

[source,console,subs=attributes]
----
$ curl http://localhost:5000/{api-version}/infrastructures?list
["mercury"]
----

[sidebar]
--
.More links
* xref:usage:racksdb-web.adoc[`racksdb-web`(1) command manpage]
* xref:usage:rest.adoc[REST API reference documentation]
--

[#webui]
=== Web UI

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

[source,console]
----
$ racksdb-web --with-ui
----

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

[sidebar]
--
.More links
* xref:usage:racksdb-web.adoc[`racksdb-web`(1) command manpage]
* xref:usage:ui.adoc[Web UI user guide]
--

== 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
[.path]#`/var/lib/racksdb`#.

The bootstrap example should help you to guess the structure and properties but
the xref:db:structure.adoc[database structure reference documentation] provides
all details.

The xref:db:positioning-racks.adoc[racks] and
xref:db:positionning-equipements[equipments] positionning How-tos may also help
you to define complex layouts.

[sidebar]
--
.More links
* xref:db:structure.adoc[Database structure reference documentation]
* xref:db:positioning-racks.adoc[Racks positionning How-to]
* xref:db:positionning-equipements[Equipments positionning How-to]
--
