This tool is designed to integrate seamlessly into existing HPC infrastructures. The following sections provide information on how to install and configure xbat.
When considering xbat for your cluster, make sure the following prerequisites are met:
- Slurm (other schedulers are not supported)
- Root access to the cluster
- Docker or Podman (compose) on the management node (compute nodes do not require Docker/Podman)
- User Management System (LDAP, IPA or PAM)
The main service of xbat (xbat.service) is typically installed on a login or management node of the cluster and contains all relevant services, including the databases, in a docker-compose infrastructure (see here for more details). In case your are using a diskless image for this node, consider deploying the databases on a separate node to prevent data loss (use --no-db during installation and deploy databases manually).
Users can submit jobs for xbat via the CLI or the web interface. While the latter provides additional features like support for parameter studies and more control over the job submission, it also requires access to the users home directories. Make sure the home directories are accessible from the management node and can be mounted into the xbat.service containers.
Start by cloning the xbat repository and navigate to the root directory of the project.
git clone https://github.com/MEGWARE-HPC/xbat
cd xbat
git checkout <branch> # optionally check out certain branch, default is 'master'
A setup.sh file is provided for the installation, upgrading and removal of xbat. The same script can also be used to validate your configuration, manage database migrations and generate the xbatd configuration files.
./setup.sh (install|remove|validate|migrate|generate-xbatd-conf)
Actions:
install Install XBAT with configuration options below
remove Remove XBAT installation
validate Validate configuration file
migrate Manage database migrations
generate-xbatd-conf Generate xbatd configuration file
Install configuration options:
[--help|-h] Print this message
[--executor (docker|podman)] Container executor (default: podman)
[--home-mnt <path>] Mount home directory path
[--port <port>] Frontend port (default: 7000)
Note: Auxiliary ports count up from frontend port (+1 to +4)
[--frontend-network <ip>] Bind frontend network (default: 0.0.0.0)
[--no-db] Deploy without databases
[--clickhouse-host <host>] Clickhouse hostname or IP (required with --no-db)
[--mongodb-host <host>] MongoDB hostname or IP (required with --no-db)
[--expose-databases] Expose database ports (for development purposes)
[--workers <count>] Number of workers (default: 8)
[--certificate-dir <dir>] Certificates directory (default: /etc/xbat/certs)
[--user <user>] System user to run xbat (default: xbat)
Migration commands:
./setup.sh migrate [status] Check for pending database migrations (default)
./setup.sh migrate up Apply all pending migrations
./setup.sh migrate down Rollback last migration
Generate xbatd configuration commands:
./setup.sh generate-xbatd-conf Generate config to /etc/xbat/xbatd.conf
./setup.sh generate-xbatd-conf --stdout Print config to stdout
Examples:
./setup.sh install --port 8080 --workers 4
./setup.sh migrate status
./setup.sh validate
./setup.sh generate-xbatd-conf --stdout
The minimum installation command requires specifying the home directory mount point. All other parameters are optional and have default values (see --help for details).
./setup.sh install --home-mnt /home/
On systems with where SELinux is in "enforcing mode" (when getenforce returns 1) problems might arise with the docker infrastructure trying to access mounted directories. To prevent this, set SELinux to "permissive mode" or adjust the SELinux policies accordingly.
# this will reset after a reboot
setenforce 0
# to persist this setting, edit /etc/selinux/config and set
SELINUX=permissive
During the initial installation a system account called xbat is created. All configuration and database related files are owned by this user. The name of this user can be changed by specifying the --user option during installation.
The tool is installed as a systemd-service called xbat.service - usual systemd-commands apply. Start xbat.service and continue with the initial database setup.
systemctl start xbat.service
After configuring both databases, adjust /etc/xbat/xbat.conf accordingly. Restart xbat.service after every change to the configuration file.
Validating xbat Configuration
You can validate yourxbat.conf configuration file with the following command:./setup.sh validate
This will check for the validity of the configuration file and return any errors or warnings. The output might look like this:
xbat Configuration Validation
Configuration file: /etc/xbat/xbat.conf
================================================
=== General Configuration ===
✓ log_level is set
WARNING: [general] 'cli_interval' is missing from configuration file, will default to '5' - consider adding it to /etc/xbat/xbat.conf
✓ log_level has valid value: debug
=== MongoDB Configuration ===
✓ address is set
✓ database is set
✓ user is set
✓ password is set
WARNING: [mongodb] 'address' has been changed from docker-compose default - only change this value if you are deploying with --no-db
# <output shortened> #
================================================
Validation Summary
✓ All required variables are present
Found 9 warnings
✓ Configuration validation passed
Updating xbat is as straight forward as the initial installation. Just execute the setup.sh script with the same parameters as before.