Machina Callida

Installation

Docker

1. Install Docker (https://docs.docker.com/engine/install/) and Docker Compose (https://docs.docker.com/compose/install/).

2. Clone the repository: git clone https://scm.cms.hu-berlin.de/callidus/machina-callida.git.

3. Move to the newly created folder: cd machina-callida.

4. Run ./scripts/deploy.sh.

   When using the application for the first time, it may take a few minutes until the container "mc_frontend" has finished compiling the application.

5. Visit http://localhost:8100.

Command line

For installation via command line, see the respective subdirectories (mc_frontend and mc_backend).

Debugging

Access to the Docker container

Use docker compose down to stop and remove the currently running containers.

To access a running container directly, get the container ID via docker ps and connect via docker exec -it CONTAINER_ID bash.

To snapshot a running container, use docker commit CONTAINER_ID. It returns a snapshot ID, which you can access via docker run -it SNAPSHOT_ID.

Models

To generate class structures for this project automatically, run:

./scripts/openapi_generator.sh

Note: If an unused Enum is specified in the API documentation, it will not be generated. To force-generate its model, provide a second, derived schema that relies on the Enum using allOf-inheritance.

Documentation

API

To view the official API documentation, visit https://korpling.org/mc-spec/ .

If you make local changes to the source code, your own API documentation will be published at http://localhost:8080/ . The port (8080) may change depending on your configuration.

Changelog

To update the changelog, use: git log --oneline --decorate > CHANGELOG

Testing

Locally

To test your code locally, run ./scripts/coverage_local.sh (all components) or docker compose run --rm --entrypoint="./coverage_backend.sh" mcserver (only backend).

To test the GitLab CI locally, run gitlab-runner exec docker --docker-privileged JOB_NAME. Do not forget to specify the username and password for your chosen package registry (e.g., Docker). You can do this in the .gitlab-ci.yml variables, or in the GitLab UI, using CI_REGISTRY_USER and CI_REGISTRY_PASSWORD. The JOB_NAME should be replaced by an actual job name from the YAML configuration.