Get Started using CHORAS#

In your terminal:

git clone <repository-link>
cd CHORAS

This repository includes three submodules:

frontend-v2
backend
simulation-backend

If you only want to use the Docker setup (recommended for running CHORAS locally), you do not need to touch these submodules manually. In that case, just follow the Docker-based instructions.

If you want to:

Explore the underlying code, or
Run simulations on the cloud

then initialize the submodules:

git submodule update --init --recursive

Cloud Connection Setup#

Note

This step is only required if you want to offload heavy simulations to HPC clusters (e.g., SURF Cloud). You can skip this section if you do not have cloud access yet. If you gain access later, come back and complete these steps.

SSH Key Setup#

Generate and configure an SSH key on your machine following the GitHub guide: Generating a new SSH key and adding it to the ssh-agent

In the root directory of the CHORAS repository, open docker-compose.yml. Add the path to your local SSH key directory in volumes of backend:

platform: linux/amd64
build:
  context: . # root of CHORAS
  dockerfile: backend/Dockerfile
ports:
  - "5001:5001"
env_file:
  - .env.api
depends_on:
  - db_service
  - redis
volumes:
  - /var/run/docker.sock:/var/run/docker.sock
  - ./uploads:/app/uploads
  - ./simulation-backend:/app/simulation-backend
  - <absolute-path-to-ssh-directory>/.ssh:/root/.ssh:ro # Add this line

Cloud Configuration Variables#

After SSH is configured and you receive your cloud access details (IP address, username, etc.):

Go to the backend submodule:
```
cd backend
```

Open config.py and update the CloudConfig class at the end of the file:

class CloudConfig:
    """
    Cloud Configuration
    """
    CLOUD_EXECUTOR_HOST = "<cloud-ip>"           # ← Update with your cloud IP
    CLOUD_EXECUTOR_USER = "<cloud-user>"         # ← Update with your username
    CLOUD_EXECUTOR_KEY_PATH = f"{Path.home()}/.ssh/id_ed25519"
    CLOUD_EXECUTOR_DIRECTORY = f"/data/storage/{CLOUD_EXECUTOR_USER}"

In the CloudConfig class, update:
- The IP address of the cloud
- The username
with the values provided by your cloud/HPC provider (e.g., SURF).

Note

For Cloud/HPC, Singularity should be installed on it.

Running CHORAS#

From the root directory of the CHORAS repository:

Make sure Docker Desktop is running.
In a terminal, run:
```
./CHORAS_BUILD.sh
```
This script builds and starts all required containers.
Once the build completes, open your browser and go to: http://localhost:5173/

You should now see the CHORAS user interface.