JuART

Jülich Advanced Reconstruction Toolbox

Onboarding

Install Required Software

To set up your development environment, install the following:

• VS Code – Code editor with DevContainer support.
• Podman Desktop – GUI for managing Podman containers.

Note: After installing Podman Desktop, enable the Docker compatibility option in Settings > Experimental. Restart any open VS Code instances to apply the changes.

Install the Dev Containers extension in VS Code:

1. Open VS Code.
2. Go to Extensions (Ctrl+Shift+X).
3. Search for Dev Containers.
4. Install the extension from Microsoft or visit the repo.

Configure VS Code for Podman

Set the VS Code setting for Dev Containers > Containers: Docker Path path to podman. This can also be done in the user settings JSON by adding the following line:

"dev.containers.dockerPath": "podman"

Clone the Repository

Ensure you have Git installed, then clone the repository:

git clone git@github.com:inm-4/juart.git
cd juart

Sharing Git Credentials with the Container

To authenticate with Git inside the container, install Git and SSH on your host machine:

git config --global user.name "Your Name"
git config --global user.email "your.email@address"

Ensure your SSH agent is running and your key is added:

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_rsa

For persistent SSH authentication, consider adding this to your ~/.bashrc or ~/.zshrc:

if [ -z "$SSH_AUTH_SOCK" ]; then
    eval "$(ssh-agent -s)"
    ssh-add ~/.ssh/id_rsa
fi

More details: Sharing Git Credentials with Containers.

Open the Project in a DevContainer

1. Open VS Code.
2. Press Ctrl+Shift+P and select Dev Containers: Open Folder in Container….
3. Choose the cloned QRAGE project folder.
4. Wait for the container to build and start.

Once started, you're ready to code inside the containerized development environment.

Additional Configuration

Settings Configuration

To ensure that your local extensions are automatically installed inside a development container, you can configure the settings.json file of the Dev Containers extension. This approach ensures that all developers have the necessary extensions available without manual installation.

To configure this, follow these steps:

1. Open Visual Studio Code.
2. Open the command palette (Ctrl+Shift+P or Cmd+Shift+P).
3. Type Preferences: Open Settings (JSON) and select it.
4. Add the following configuration to your settings.json file:

{
    "remote.containers.defaultExtensions": [
        // Add your extensions here, for example:
        // "continue.continue",
        // "GitHub.copilot",
        // ...
    ]
}

For more details: VS Code Dev Containers Documentation

Setting Up Pre-Commit Hooks

To ensure consistency, we use pre-commit hooks for automatic linting and formatting before committing changes. Open a terminal inside VS Code. Make sure that the directory path is pointing to /workspaces/juart

Set up the pre-commit hook:

pre-commit install

From now on, every time you commit code, pre-commit will automatically check and format files according to our rules.

For manual checks, you can run:

pre-commit run --all-files

To verify if the pre-commit hook is active, run:

ls -l .git/hooks/pre-commit

Sharing S3 Credentials with the Container

To authenticate with an S3 storage, you need to create a folder on the host machine containing the corresponding credentials. This folder should be located at ~/.aws/credentials.

The credentials file should be formatted as follows:

[default]
aws_access_key_id = YOUR_ACCESS_KEY_ID
aws_secret_access_key = YOUR_SECRET_ACCESS_KEY

Replace YOUR_ACCESS_KEY_ID and YOUR_SECRET_ACCESS_KEY with your actual AWS credentials.

Issues

Files Showing as Modified in Git

After opening the repository in the DevContainer, all files may appear as modified due to file mode changes:

diff --git a/<filename> b/<filename>
old mode 100644
new mode 100755

To prevent this issue, we use the following setting in devcontainer.json:

"postCreateCommand": "git config core.fileMode false"

For more details, see the related discussion: VS Code Remote Issue #1134.

Third-Party Licenses

This project uses third-party software. The licenses for these dependencies are included in the THIRD_PARTY_LICENSES.txt file.

• Third-Party Licenses