Skip to main content

Contributing Guide

Development Setup​

Getting Started with the Repository​

After joining the GitHub organization, you'll need to clone the specific IMBIT application repository to your local machine using your preferred IDE, such as Visual Studio Code or IntelliJ.

Local vs. AWS Development​

While AWS dev instances were previously used for testing, local development with Docker is now preferred due to its speed, cost efficiency, and simplicity.

x86 and ARM64 Platform​

Our applications in AWS are x86 with the exception of BrillianIDEAS (ARM64). Testing on ARM64 resulted in login issues with BrillianCRM, ICM, and Quiz that require proper debugging. Developers using Macs with M-series chips may experience compatibility issues in their local development environments.

Setting up Docker​

Docker is the best way to develop your apps. If you use Mac or Windows, install Docker Desktop from the Docker website, which also sets up Windows Subsystem for Linux (WSL). If you use Linux, install the Docker Engine and Docker Compose plugin using Docker's official docs.

Each repository comes equipped with:

  • Dockerfiles: These are scripts used by Docker to automatically build image files.
  • docker-compose.yml: A file that defines how Docker containers should be built, configured and run. The container images will be created using the Dockerfiles.
  • docker-compose-AWS.yml: For AWS deployment, instead of building the images from the Dockerfile, it pulls the images from the GitHub repository. See the deployment page for more details.

Docker Commands​

Navigate to the repository directory and use the following commands:

  • To start Docker containers:
docker compose up -d
  • To rebuild the images:
docker compose up -d --build
  • For a complete rebuild (useful when changes are not reflecting):
docker compose up -d --build --force-recreate
  • For locally testing the AWS deployment:
docker compose -f docker-compose-AWS.yml up -d

Alternative Setup Without Docker​

If for any reason you opt not to use Docker, ensure you have Node.js and npm installed for running BrilianQuiz, IMBIT-N3XT, and BrillianDOCS. The typical command to start the applications is:

npm start

Applications like BrillianIDEAS, BrillianCRM, and BrillianICM have been dockerized due to their more complex setups. However if you want to develop without Docker you will need Apache for BrillianIDEAS, and for BrillianCRM/ICM you will requiere a more complex setup involving Java SDK, Tomcat, and Maven.

Contributing​

The power of collaboration lies in your hands! Here's how to get started:

Creating Your Branch​

When you're ready to contribute, create a new branch in the respective repository named firstname_lastname. If you are working on a specific feature name it with the scheme firstname_lastname_feature.

Making a Pull Request (PR)​

After you've made your changes, push your branch, open a pull request and merge it against the main branch. This will trigger the Continuous Deployment (CD) Pipeline, which deploys to AWS (BrillianIDEAS, BrillianQUIZ, BrillianCRM/ICM, IMBIT-N3XT) or GitHub Pages (BrillianDOCS).

Once your contributions have been merged, feel free to delete your branches.

👉 For a visual guide on branching, check out this YouTube tutorial.

GitHub Organization Settings​

Our GitHub organization is set to private, but individual repositories are public. We recommend to future student to rework the GitHub settings, including the integration of Dependabot for dependency updates and enabling security alerts.