=========================
J.U.S.T. Docker Functions
=========================

.. default-domain:: bash

.. file:: just_docker_functions.bsh

.. function:: docker-compose_restore_from_cache

:Arguments: - ``$1`` - Docker compose filename
            - ``$2`` - Main service name to restore and rebuild. This needs to be the last (unnamed) stage
            - ``[$3...]`` - Addition services based on same dockerfile to restore and rebuild
:Parameters: - ``JUST_DOCKER_COMPOSE_CACHE_REPO`` - Default value: ``vsiri/ci_cache``
             - ``JUST_DOCKER_COMPOSE_PULL`` - Pulls images to use. Default: 1 (true).
             - ``JUST_DOCKER_COMPOSE_BUILD`` - Builds images after pulling cache. Default: 1 (true).
             - ``JUST_DOCKER_COMPOSE_PUSH`` - Pushes images when done. Default: 1 (true).

Restores image from cached images downloaded from the registry.

This is done in three steps:

1. First, the images are pulled from ``JUST_DOCKER_COMPOSE_CACHE_REPO``, if available.
2. Next, the images are built against the Dockerfiles using the downloaded cache.
3. Lastly, the images are pushed back to ``JUST_DOCKER_COMPOSE_CACHE_REPO`` to keep them up to date.

- Every stage is backed up as long as it is given a name. It must have a name because without one, it cannot be targeted using the ``docker`` cli or ``docker-compose``. These stages are named: ``${JUST_DOCKER_COMPOSE_CACHE_REPO}:${main_service_name}_${stage_name}``
- The final stage is tagged as: ``${JUST_DOCKER_COMPOSE_CACHE_REPO}:final_${main_service_name}``
- Any VSI recipes used are also identified and tagged: ``${JUST_DOCKER_COMPOSE_CACHE_REPO}:recipe_${main_service_name}_${recipe_name}``. The recipes contain "ONBUILD" commands that are different images than the ``${JUST_DOCKER_COMPOSE_CACHE_REPO}:${main_service_name}_${stage_name}`` version of them.

Even though all the stages are restored, only the services specified (``$2`` ...) are retagged so that they can be used. If you need more than one service's images restored, you will need to specify them all. If multiple services use the same image tag, they do not need to be specified. For example, service ``foo`` uses image ``stuff:foo``, service ``bar`` uses image ``stuff:bar``, and service ``car`` uses image ``stuff:bar`, only services ``foo`` and ``bar`` need to be passed in.

.. function:: get_docker_recipes

:Arguments: ``$1...`` - Dockerfiles to search for recipes
:Parameters: ``JUST_RECIPE_REPO`` - Name of recipe image to look for. Default: ``${VSI_RECIPE_REPO}``
:Output: **stdout** - Newline separated list of the tags of the recipes

Looks for recipes that are used in the Dockerfiles.

.. function:: docker_defaultify

.. command:: build_recipes

:Arguments: [``$1``]... - Recipe names to run
:Parameters: ``JUST_RECIPE_BUILDARGS`` - Array of build args to be added to every recipe (e.g. ``FOO=BAR``).

Runs ``docker compose build`` for the docker recipes. Useful command to call before ``docker build`` on your own project that uses recipes in vsi_common, to keep them synced with your build.

.. command:: build_recipes-auto

:Arguments: ``$1``... - Dockerfiles to parse

Scans Dockerfiles for ``vsiri/recipe:`` images, and calls :cmd:`build_recipes` on the recipes discovered. Accepts multiple files and ``-`` for stdin

.. command:: log

:Arguments: [``$1``]... - Service names

Show logs from all service containers. Optionally specify service names to only log specific containers.

.. warning::

  Does not pick up containers that didn't exist when starting ``just`` log

Override the log target in your ``Justfile`` and call ``__docker-compose_log`` if you need to set other parameters.

.. command:: docker_clean

:Arguments: ``$1`` - Volume to be removed

Runs ``docker volume rm`` on the specified volume. If the volume is in use, there are four strategies to handle this:

1. ``ask`` - (default) Interactively asks you if you want to use the stop, delete, or error strategy.
2. ``stop`` - Attempts to stop the containers with a 30 second timeout and then forcefully remove the current containers mounting the volume, without prompting
3. ``delete`` - Mounts the volume and deletes all of the files. May not work when a container is running a database, or the volume is modified by the entrypoint, e.g. by adding user permissions.
4. ``error`` - Errors out instead of cleaning the volume

The action for a specific volume is specified by setting the label ``com.vsi.just.clean_action``.

For example, in a ``docker-compose.yaml`` file:

.. code-block:: yaml

  volumes:
    venv:
      labels:
        com.vsi.just.clean_action: ask

delete
------

In the case of the ``delete`` strategy, an optional label, ``com.vsi.just.clean_setup``, can be specified to designate what just target to run to repopulate a volume. Typically this just target should run ``sh -c ":"`` or similar. This allows the entrypoint or another command to properly setup the volume, and set permissions, etc...

.. command:: docker-compose_debug

:Arguments: ``$1`` - service name to build.
            [``$2``] - Stages to disable caching on. See [here](https://docs.docker.com/reference/cli/docker/buildx/build/#no-cache-filter) for the syntax

This will use information from ``docker-compose config`` to craft a ``docker buildx debug build`` command with the invoke command to help debug a failing build. As this is an experimental command, support is fairly limited:

* Always uses /usr/bin/bash
* Requires docker buildx 0.12
* Any complicated build args (spaces and special characters) will likely fail
* Uses ``.`` as the build context