Installation¶

Downloading Bumblebee¶

Installation files for Bumblebee are provided as a tar archive on the downloads page.

• Select the correct version of the Bumblebee installer from the list and click the download button to access the files

• You will be prompted to verify your SCM username and password. These credentials were provided to you as part of the Bumblebee license. If you are having trouble accessing the downloads, please contact our support team

• You should obtain a bbweb.tar archive containing the web interface installation. You can use your system file explorer to access the files in the archive

  • bbweb.image contains the web interface itself

  • bbweb-kube.yaml is the configuration file for the web interface

  • Bumblebee.pdf contains the offline version of the documentation

Web Interface¶

The web interface is provided as a container application, allowing users to run their own Bumblebee instance on a local system. A container manager is necessary to launch the web interface. The following instructions use Podman.

• Download the Podman Desktop installer and follow the OS-specific instructions on the website to install Podman Desktop

  • On Windows, Podman Setup may ask you to install WSL2. If WSL2 is not detected after installation, you may be required to restart your computer before resuming the setup

  • A Windows Firewall message may pop up, asking whether to allow Podman access to the network. You only need to enable this if you want access to the web interface from other computers

  • Optional: It is recommended to enable the Autostart setting for Podman. This skips having to launch the Podman engine every time you open Podman Desktop. If you want to change this setting later:

    • Go to the Extensions tab

    • Click on the Podman extension

    • Click on the file icon labeled Edit properties of Podman extension

    • Enable/disable autostart

  • On Windows, you will see the message: We could not find any Podman machine. Podman needs to setup a virtual machine in WSL before launching the container:

    • The name does not matter, you may use the default

    • The image path can be left empty

    • Bumblebee does not require a machine with root privileges. It is recommended to keep this setting disabled to improve security

    • User mode networking is disabled by default. This setting is only required when you are connecting through a third-party VPN

• Open Podman Desktop. On the Dashboard page, there should be a Podman widget with the Running status. If this is not the case, follow the instructions in the previous step to set up Podman

• Go to the Images tab in Podman Desktop

• Click the Load button and select the bbweb.image file obtained from the bbweb.tar download

• Go to the Pods tab in Podman Desktop

• Click the button labeled Play Kubernetes YAML and select the bbweb-kube.yaml file obtained from the bbweb.tar download

  • If you encounter an HTTP or server error when playing the YAML file, you may have a firewall enabled, blocking connections to the container registry. Contact your IT department or SCM support to resolve this issue

• Wait until all indicator lights turn green

  • When restarting Podman Desktop, you may need to click on the Start Pod button (indicated by the play icon) before the web interface will load

• Click on the name of the pod (podbbweb)

• Click on the Open button (maximize icon) to launch the web interface

• If this is the first time opening the web interface, you will be prompted to create an admin account. This account is stored locally on your computer and is not shared with SCM

Bumblebee¶

The Bumblebee executable can be obtained from the Downloads tab in the web interface. Clicking on your username will open a menu, from which you can access Downloads.

The Downloads page contains a button to download the binary.

chmod +x bumblebee

./bumblebee --version

export SCMLICENSE=$HOME/license.txt

echo 'export SCMLICENSE=$HOME/license.txt' >> ~/.bashrc

source ~/.bashrc

Connecting to a Server¶

In order to submit calculations automatically through the web interface, a connection must be established with the machine running Bumblebee. This process requires 2 steps:

• Install Bumblebee Bootstrap on the server

• Setup server connection in the web interface

sudo apt install python3 python3-yaml python3-scipy python3-numpy python3-numexpr

cp preprocess/qsub.conf.example preprocess/qsub.conf

bumblebee --version

sudo apt install openssh-server slurm-wlm

sudo gzip -cd /usr/share/doc/slurmd/examples/slurm.conf.simple.gz > /etc/slurm/slurm.conf

HN=$(hostname -s) && sudo sed -i "s|=workstation|=${HN}|g" /etc/slurm/slurm.conf

HN=$(hostname -s) && sudo sed -i "s|=server|=${HN}|g" /etc/slurm/slurm.conf

SC=$(slurmd -C | head -1) && sudo sed -i "s|^NodeName=.*|${SC}|g" /etc/slurm/slurm.conf

sudo systemctl enable slurmd slurmctld

sudo systemctl start slurmd slurmctld

sudo systemctl status slurmd slurmctld

Connection Setup¶

Login Authorization¶

In order to allow Bumblebee to connect to your account, a key-based login must be enabled. On the Server page, click the button Generate New Key Pair. The key that is generated must now be added to the ~/.ssh/.authorized_keys file on the server. For example (adjust this to include your own key):

echo 'ssh-rsa AAAAB3NzaC1yc2= 3d808818-477a-45de-9f66-1e8eb5abd061' >> $HOME/.ssh/.authorized_keys

If the .authorized_keys file did not previously exist, make sure that the file permissions are set to mode 600.

chmod 600 ~/.ssh/authorized_keys

Warning

Both the public and private keys generated by Bumblebee are stored in a user-accessible folder inside the container.

For WSL users: note that files stored under WSL are exposed to the Windows user account. While access protection still applies by default, administrative privileges on the Windows account-level can be used to override these restrictions.

If you believe your private key may have been compromised:

• Remove the old key from the authorized_keys on the server

• Generate a new key in the web interface

• Authorize the new key on the server to re-establish the connection. You can confirm the connection status in the server settings of the web interface

Connection Settings¶

In the Bumblebee web interface, go to the Settings menu and select the Server tab.

Click on the Add Server button to configure a new connection.

• Choose any server name. This is the name that will be shown in the web interface when selecting the server for job submission

• Enter the hostname of the login node of your server

  • If you are running Bumblebee on the same computer as the web interface, you may use host.containers.internal instead

• Select an open port for ssh connections to the server. (The default is port 22. If your server login requires a specific port, adjust as needed.)

• The username must be set to your login name on the server

• Folder should be the path to the folder containing the Bootstrap scripts (relative to the Home directory on the login node)

• The backend should be set to remote

• Set the name of the job submission queue on the cluster

• Click the Check Connection button to test your connection. A check mark should appear to indicate a successful setup

If there is a problem with the connection, a warning symbol will appear. Hover over the symbol to view the error message.

• If a connection could not be made:

  • Check that your computer is connected to the network

  • Check that the server is connected to the network

  • Check that the hostname is correct

ping hostname

• If the connection was refused:

  • Check that your username is correct

  • Check that incoming ssh connections on the server are allowed on the selected port

ssh -p 22 username@hostname

• If the Bootstrap version could not be verified:

  • Check that the Folder has been set correctly

    • Navigate to the Bootstrap folder

    • Run the pwd command to obtain the absolute path

    • Copy the absolute path to the Folder

  • Check that the public key has been added to the authorized_keys

  • The authorized_keys file must have its permissions set to 600

  • The ~/.ssh folder must have its permissions set to 700

  • Check that you have executable permissions on the login node

  • If Bootstrap is installed on NFS, make sure that the NSF is mounted with executable permissions

  • To confirm that you have the correct path and permissions, navigate to the Folder on the cluster. You should be able to run the following command:

./preprocess/bumblebee-bootstrap-version -l

• If there are dependency issues:

  • Make sure that Python is installed on the cluster

  • Check that all of the required Python packages are installed

  • Your Python version may be incompatible with Bootstrap

    • Install a different Python version

    • Install the required packages for the new Python version

    • Make the new Python version the default when using Bumblebee

  • If Bootstrap files have been deleted, re-install Bootstrap by downloading the files from the web interface

Testing the Installation¶

See the Tutorials page in the web interface to setup your first simulation. The simulation status should change to submitted to indicate that your job is now running on the server.

You can go to the Jobs page in the web interface to see the status of your ongoing simulations.

FAQ¶

If job submissions fail to run, this indicates a server-side issue.

• First verify that the server connection is still active by checking the server status on the Settings page of the web interface

• The pod may not have network access. On some operating systems, Podman disables pod connections if your machine does not have network access when starting Podman. This error can occur even when running Bumblebee locally. Re-start the pod to resolve this issue

• The partition selected in the web interface server settings may not exist, or is currently DOWN. Login to the server and run the sinfo command to check the partition status

• Key-based login may be disabled on the server. Contact your server administrator if this is the case

• Check the simulation output for error information. You can access these files by logging in to the server and navigating to the job folder, or through the web interface by selecting the Simulation and navigating to the Files tab. You may need to click the Refresh button to load the files

  • error.log files document error messages from the server

  • std.err files report on error messages from Bumblebee. These errors include issues with your input settings or SCM License

  • std.out reports the output of the Bumblebee simulation

If your jobs are successfully submitted, then immediately exit:

• Check the simulation output for error information, as detailed above

• You may have incorrectly set the SCMLICENSE location in the preprocess/bumblebee.qsub file. Check the output.log file to see the license configuration

• Your license may have expired. On the server, run the following command to check for license errors:

./bumblebee --version

• Necessary SBATCH settings may be missing from the qsub.conf file. Check the std.err file for Slurm messages

• Bumblebee may not be in the PATH on the server. Check the output.log file to see if the executable could be found

• .bashrc settings may not be loaded automatically when submitting jobs through the web interface, as the session is non-interactive. Either adjust the .bashrc file to enable settings for non-interactive login, or add necessary calls to the preprocess/bumblebee.qsub file