.. _manage_script:

Management Script Usage
=======================

The ``manage.sh`` script is a utility for controlling the lifecycle of the Calyntro Docker containers. It provides simple commands for common operations like starting, stopping, and updating the application.

Usage
-----

To use the script, run it from the root of the project with one of the available commands.

.. code-block:: bash

   ./manage.sh [command]

Available Commands
------------------

Here is a list of the commands supported by the ``manage.sh`` script:

**up**
   Builds the Docker images and starts all services in detached mode.

   .. code-block:: bash

      ./manage.sh up

**down**
   Stops and removes all running containers, networks, and volumes defined in the ``docker-compose.yml`` file.

   .. code-block:: bash

      ./manage.sh down

**import [path]**
   Runs the full data import process for a local repository. This command takes the path to the repository on your host machine, mounts it into the container, and runs both the configuration and analysis import steps.

   If the path is omitted, the script reads the ``repo_path`` from ``config/config.yaml``.

   *Note: After the import is complete, the generated DuckDB database files will be located in the ``data/update_data/`` directory (or as defined by ``db_update_path`` in your ``config.yaml``). Reference the ``config.yaml`` or :ref:`calyntro_config` for more details.*

   .. code-block:: bash

      ./manage.sh import /path/to/your/local/repo

**refresh**
   Automatically swaps the staging database files (from ``db_update_path``) into the production environment (``db_path``). This command requires the ``yq`` utility to be installed on your host machine to parse the configuration file.

   .. code-block:: bash

      ./manage.sh refresh

   The script stops the backend, creates a backup of the current production databases, moves the new files from the staging area to the production area, and restarts the backend. Configuration values (``db_path``, ``db_update_path``, ``db_basename``) are read directly from ``config/config.yaml`` — no additional utilities required.

**update**
   Rebuilds the Docker images and restarts all services. This is useful when you have made changes to the source code.

   .. code-block:: bash

      ./manage.sh update

**logs**
   Streams the logs from all running containers into a file in the ``./logs`` directory. The command runs in the background.

   .. code-block:: bash

      ./manage.sh logs

**pull-latest**
   Pulls the latest Docker images from the GitHub Container Registry (GHCR) and restarts the services. This is the standard update path for self-hosted installations.

   .. code-block:: bash

      ./manage.sh pull-latest

**pull-gitlab**
   Pulls ``:dev`` images from the GitLab registry and retags them to match the ``docker-compose.yml`` image names. Intended for testing pre-release builds. Requires ``GL_REGISTRY_IMAGE`` and ``GL_REGISTRY_TOKEN`` environment variables (or an active ``docker login`` to the registry).

   .. code-block:: bash

      GL_REGISTRY_IMAGE=registry.gitlab.com/youruser/calyntro ./manage.sh pull-gitlab

**debug-path**
   A debugging utility that prints the Python search path (``sys.path``) and lists the contents of the ``/app/src`` directory inside the ``importer`` container. This is useful for diagnosing module import errors.

   .. code-block:: bash

      ./manage.sh debug-path