Setup & Update Guide

This guide explains how to perform the initial setup of Calyntro and how to update your analysis data during regular operation.

Calyntro uses a staging workflow for data imports. New data is first imported into an “update” database. Once the import is complete, this database is safely swapped into the live environment. This ensures that the dashboard remains available and responsive while heavy analysis tasks run in the background.

Prerequisites:

Docker & Docker Compose must be installed and running.
Python is required on your host machine to execute the management scripts.

Initial Setup

Follow these steps to initialize Calyntro for the first time.

1. Download Container Images

First, pull the latest pre-built Calyntro images from the registry:

./manage.sh pull-latest

2. Prepare Configuration

Navigate to the config directory and set up your config.yaml file. You can usually start by copying an example template provided in the release.

Ensure you configure your modules, teams, and exclusions correctly. For detailed information on all configuration options, please refer to the Configuration Guide.

3. Mount Target Repository

Calyntro needs access to the Git repository you want to analyze. The easiest way to provide this is to create a symbolic link named repo in the Calyntro root directory that points to your local repository folder.

ln -s /path/to/your/target/repository ./repo

4. Run Initial Import

Now, start the importer to analyze the Git history and build the initial staging database.

./manage.sh import repo

Depending on the size of your repository, this step may take some time.

5. Move Database to Runtime

Once the import is complete, the data resides in the staging area. Use the refresh command to move the database to its final location where the backend can read it.

./manage.sh refresh

6. Start Calyntro

Finally, launch the Calyntro backend, frontend, and gateway services.

./manage.sh up

You can now open your browser at http://localhost to explore your dashboard.

Update Process (Operation)

Once Calyntro is running, you will want to periodically update the analysis with the newest commits. The update process is designed to be non-blocking.

1. Incremental Import

Run the import command. The script will automatically detect the existing data, copy the current live database into the staging area, and only analyze the new commits.

./manage.sh import

2. Refresh Live Database

When the import finishes, execute the refresh command to atomically swap the newly updated staging database with the live database.

./manage.sh refresh

This script handles the backup of your old data, gracefully pauses the backend for a split second to release file locks, swaps the files, and resumes the service. Your users will barely notice the update.