justfile

Overview

The justfile is a task runner script that defines several command-line tasks, primarily for managing a Docker Compose environment related to a lightweight gossip network setup. It leverages the just command, which is a modern alternative to make, to simplify and automate common Docker Compose operations such as stopping containers, building and running services, and viewing logs.

Each task in this file is a shell script snippet that sets the COMPOSE_FILE environment variable to a specific Docker Compose configuration file (./docker/lite-gossip-3.compose.yaml) and then runs the appropriate Docker Compose command. This file centralizes Docker Compose operations for the litenode service, facilitating consistent environment setup and management.

Tasks

help

Description:
Displays the list of available tasks defined in this justfile.

Functionality:
Runs the command just --list to print all defined tasks.

Usage example:

just help

stop

Description:
Stops all running containers defined in the Docker Compose file lite-gossip-3.compose.yaml.

Implementation Details:

• Uses a bash shebang and set -ex for debugging and error handling.

• Exports the COMPOSE_FILE environment variable to point Docker Compose to the correct file.

• Executes docker compose stop to stop the containers gracefully.

Usage example:

just stop

litenode

Description:
Stops any running containers (by depending on the stop task), rebuilds the Docker images, and starts the containers in detached mode.

Implementation Details:

• The task depends on the stop task, ensuring containers are stopped before rebuilding.

• Sets the same COMPOSE_FILE.

• Runs docker compose build to build images.

• Runs docker compose up -d to start containers in the background.

Usage example:

just litenode

logs

Description:
Follows the logs of the litenode service, showing the last 100 lines and continuously streaming new output.

Implementation Details:

• Sets COMPOSE_FILE.

• Runs docker compose logs -f -n 100 litenode to tail logs.

Usage example:

just logs

litedc +TASK

Description:
Runs an arbitrary Docker Compose command ({{TASK}}) using the lite-gossip-3.compose.yaml file.

Parameters:

• TASK (string): The Docker Compose subcommand and options to execute (e.g., up -d, ps, down).

Implementation Details:

• Uses a placeholder {{TASK}} to dynamically insert the task.

• Sets the environment variable COMPOSE_FILE.

• Runs docker compose {{TASK}}.

Usage example:

just litedc up -d
just litedc ps

Implementation Details and Algorithms

• Task Dependency:
  The litenode task depends on the stop task, ensuring that the environment is clean before rebuilding and starting containers. This dependency is declared by placing stop before the task body.

• Environment Variable for Compose File:
  Each task exports COMPOSE_FILE with the path to the specific Docker Compose YAML configuration. This makes the Docker Compose commands operate on the intended environment without specifying the file in every command.

• Shell Script Execution:
  Each task is implemented as an inline shell script with #!/bin/bash and set -ex. The set -e option causes the script to exit immediately on error, while set -x enables command tracing for easier debugging.

Interaction with Other System Components

• Docker and Docker Compose:
  All tasks interface directly with Docker Compose to manage container lifecycle and logs.

• Docker Compose File:
  The file ./docker/lite-gossip-3.compose.yaml defines the services and configuration for the gossip node infrastructure. This justfile acts as a wrapper to execute commands against that compose file consistently.

• Task Runner (just):
  This file is executed by the just command-line tool, which interprets the tasks and runs the embedded shell scripts.

Visual Diagram

flowchart TD
Help["help\n(just --list)"]
Stop["stop\n(docker compose stop)"]
Litenode["litenode\n(stop -> build -> up -d)"]
Logs["logs\n(docker compose logs -f -n 100 litenode)"]
Litedc["litedc\n(docker compose {{TASK}})"]
Litenode --> Stop
subgraph Docker Compose Commands
Stop
Litenode
Logs
Litedc
end
Help -->|Lists| Docker Compose Commands

The diagram shows the relationship between tasks, highlighting that litenode depends on stop, and all tasks invoke Docker Compose commands using the specified compose file.

This file is a utility script that simplifies interaction with Docker Compose for managing a lightweight gossip node environment. It provides clear, reusable commands for stopping, building, running, and logging containerized services. The use of task dependencies and environment variable configuration ensures consistent execution and ease of maintenance.