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

The easiest way to get started is to use the generate_config.sh script. It scans your Git repository and automatically generates a draft config.yaml with:

Users: All commit authors and their email aliases.
Components: Automatically detected source-code directories.
Exclusions: Folders and file extensions that typically do not contain source code.

Run the following command (requires Docker):

./scripts/generate_config.sh /path/to/your/repository -o config/config.yaml

Alternatively, you can manually create your config.yaml using an example template provided in the release.

Ensure you review the generated file to refine components, teams, and exclusions. 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:8765 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.