OpenCATTUS

OpenCATTUS is a software that guides the user to set up an HPC clustered environment. It asks for specific questions regarding the system to get an HPC cluster up and running as quick as possible. That's OpenCATTUS.

Its goal is to enhance the installation and maintenance experience, making it user-friendly, creating an easy-to-use questionnaire built with a familiar user interface, for gathering and verifying the required cluster information. For experienced users, unattended installation is available through the answerfile workflow.

User documentation

OpenCATTUS does not ship a separate user manual. The TUI and built-in command line help are the primary interface and are expected to be sufficient for normal use.

Architecture

OpenCATTUS is written in modern C++ with some C code for compatibility with newt, that's used as the terminal user interface. The software follows the Object-Oriented Paradigm and implements a simplified architectural pattern based on MVP (Model-View-Presenter) where the components can be easily swapped or expanded in the future if needed.

Dependencies

• OpenCATTUS requires boost C++ libraries.
• External fmt library is required while std::format isn't available in major compilers.
• Logging is available through spdlog.
• magic_enum is used for static enum reflections.
• Adherence with best practices is done with gsl-lite.
• newt for Terminal UI.
• glibmm for Glib bindings to interact with the OS.
• sdbus-cpp for D-Bus IPC communication.
• Testing framework provided by doctest.
• CLI11 to parse command line arguments.

Some libraries must be pre-installed from the OS since they are not available through Conan: newt, glibmm, and libxcrypt. Everything else should be found and installed by Conan during CMake. Our shipped build script should handle this automatically.

Decisions

• OpenCATTUS uses C++23 because it fits the system-level integration work of the project and matches the libraries we rely on. The priority here is correctness and predictable interaction with the operating system, not squeezing out every last unit of performance on the headnode.
• The newt library is chosen since it seems to be the default library to do terminal composing on Linux systems, which is the goal here. We are basically developing this with Red Hat Enterprise Linux, and it's clones in mind, and newt is basically a Red Hat (and Debian) sponsored library. Finally, newt is easier to work than ncurses, so it seems like a good fit.
• We avoid OOP techniques that may add complexity without any visible benefits, such as multiple inheritance. Because in this context they are usually a bad idea. It's not forbidden to use, but it should be used with caution.
• At the current state there's no need for a database since the software is stateless, and in the future configuration will be stored in a single INI style or equivalent configuration file.
• Build system is based on CMake and Conan for package management. It was heavily based on cpp_starter_project with some modifications.
• Expansion and modularity is desired and should be achieved. A daemon compatible with systemd is planned to enable more powerful features like: keeping state, maintenance interface, common housekeeping routines, backups and upgrades.
• We consume a lot of existing software to avoid recreating everything from scratch, most evidently: xCAT and OpenHPC. We also push changes on consumed projects to enhance them, so we directly benefit from those changes.
• OpenCATTUS is not made to run inside a container. It needs bare metal access.

Status

OpenCATTUS is under active development. The interactive cluster bring-up path is the main workflow, while some parts of the project are still evolving. Validate changes in a test environment before relying on them in production.

Building

We recommend to build and run this software in a virtual machine due to its nature and root execution requirements.

Recommended VM settings

• EL8.10, EL9.6, or EL10-based system with minimal package selection
• Half of system CPU cores as vCPU
• At least 4GB of RAM
• 50GB of Disk
• 2 Network Interfaces
  • External Access
  • Internal Management Network
• Disable side channel mitigations (for performance reasons)
• UEFI mode

To compile and run the software, clone this repository and execute the setupDevEnvironment.sh shell script. All dependencies should be installed after its execution and then follow with standard CMake procedure.

All default CMake targets are supported. By default, it builds a Release target that modifies the running OS, so be advised to run the code on a development system only.

Finally, to build the software just run the commands:

 $ cmake -S . -B ./build
 $ cmake --build ./build

The resulting binary will be available under ./build/src in the project root.

As a final warning: running the software without DUMMY option will probably damage the running OS if they run as root. Be advised.

Running tests

To run tests you need to run ctest inside the build directory.

For end-to-end EL9 cluster validation on a real KVM host, use the libvirt harness in testing/libvirt.

Open Source Apache License

OpenCATTUS is made available under the Apache License, Version 2.0.

Developers

Want to help? Feel free to report bugs, issues or open a discussion thread, so we can discuss features and enhancements. Pull requests are greatly appreciated.

Not a developer?

Any feedback is welcome. Feel free to use it, report issues and complain about the software.