Install and Set Up Scarabaeus#

Last revised by M. Pugliatti on 2025 FEB 4

Prerequisites#

There are a few additional tools that must be intalled before installing Scarabaeus.

Python#

Python is a high-level, general-purpose programming language. Its design philosophy emphasizes code readability with the use of significant indentation.

Install the recomemended version of Python - 3.11.9

Git#

Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency. Install Git if your machine does not already have it. Most Mac and Linux machines will have Git already installed.

Install Git - Git Download

Integrated Development Environment (IDE)#

Use any IDE or text editor you like. We encourage the use of an IDE that has add-ons to make development a bit easier. Most developers on the team use VSCode for its large ecosystem of powerful extensions. For SCB, we recommend using VSCode as your IDE, with the following extensions:

Clone Scarabaeus Repository#

Clone the Scarabaeus repository to your local machine. You will need to setup some form of secure access between your machine and Gitlab before you are able to do this. The options for secure access are below. We highly recommend using SSH.

To setup a secure access method:

  • SSH - Recommended:

    • On Gitlab, go to your Preferences. This can be done by clicking on your user icon in the top right corner, and the selecting Preferences.

    • Navigate to the menu on the far left of the screen and click on the SSH Keys option. This will have a key icon to the left of the text.

    • Follow the instructions on this page for adding an SSH key. The page contains links to documentation for how to set up the private and public key pair. We understand this process can be somewhat confusing so if you have any trouble please reach out to a fellow developer for assistance.

    • General GitLab SSH documentation can be found on the GitLab SSH Docs

Alternatively:

  • HTTPS - Not Recommended:

    • This process involves generating Gitlab Tokens. If you would like to use this method please reference the Gitlab documentation for a how-to.

Once you have a secure access method set up you can clone the Scarabaeus repository. You may do this via a terminal or your IDE. We recommend using your IDE as it makes things slightly simpler but this is up to you. The following instructions will be for cloning via SSH.

Cloning via VSC:

  • Navigate to the Scarabaeus project on Gitlab and click on the Clone button shown in the image below.

  • Copy the link under “Clone with SSH” (the one that starts with git@).

  • Now navigate to VSCode, open a new window, and clock on the Clone Git Repository… option under the Start menu (center left of the window). Your screen should look like the image below.

  • Next, paste the link you copied from Gitlab into the bar at the top of the VSCode window. From there follow the prompts to clone the repository.

pic1 pic2

Cloning via Command Line:

In the terminal type:

git clone git@orccagitlab.colorado.edu:javi9068/scarabaeus.git

Refer to GitLab CLI Cloning Guide for extra documentations on cloning via command line.

Add Scarabaeus Package to Python Path#

Steps to add the scarabaeus/src folder path to the Python path for both macOS and Windows.

Steps for macOS

  1. Open Terminal.

  2. Run the following command to edit your .zshrc file:

    sudo nano ~/.zshrc

    • Enter your PC’s password

  3. In the .zshrc file, add the following line to set the Python path:

    export PYTHONPATH=$PYTHONPATH:/path/to/scarabaeus/src

    • Replace /path/to/scarabaeus/src with the absolute path of the src folder (e.g., /Users/yourusername/path/to/scarabaeus/src).

  4. Press Ctrl + O and press Enter, then Ctrl + X to exit the editor and save the changes.

  5. Apply the changes by running:

    source ~/.zshrc

  6. Close this terminal and connect to the LASP VPN.

  7. Make sure to add the db_config.json file to the config folder (It contains the DB Credentials - DB Name, HostName, URI, Port Number).

Steps for Windows

  1. Press Win + R to open the Run dialog.

  2. Type sysdm.cpl and press Enter to open the System Properties window.

  3. In the System Properties window, click on the “Advanced” tab.

  4. Click on the “Environment Variables” button at the bottom.

  5. In the Environment Variables window, under the “User variables” section, click on “New…” to create a new environment variable.

  6. In the “Variable name” field, enter PYTHONPATH.

  7. In the “Variable value” field, enter the absolute path of the src folder (e.g., C:\path\to\SCB\src).

  8. Click OK to save the new environment variable.

  9. Close the remaining windows by clicking OK.

Creating a Virtual Environment#

To create a virtual environment (venv) you have two options:

From Terminal#

python -m venv .venv
.venv\Scripts\activate  # On Windows
source .venv/bin/activate  # On macOS/Linux

To deactivate:

deactivate

In VSC#

  • Go to the search bar on top and click it

  • Select Show and Run Commands >

  • Select Python: Create Environment…

  • Select Venv

  • Either Use Existing or Delete and Recreate

  • Select the python interpreter as Python 3.11.9

  • Select requirements.txt

and the venv will be generated following the list of libraries specified in requirements.txt

Library Installation#

From Terminal#

Install required packages:

pip install -r requirements.txt

In VSC#

Libraries are already installed in the last step of the venv generation.

External#

Additionally, othe rdependencies (DWN, IAS15) needs to be installed manually from terminal

Install IAS15 integrator dependencies:

git submodule update --init
pip install pyasa/.

On Windows, manually copy the shared library:

cp <venv>/Lib/site-packages/bin/pyasalib.dll <venv>/Lib/site-packages/pyasa/

where <venv> is your virtual environment directory.