Skip to content

CLAUDE.md

Latest commit

 

History

History
113 lines (85 loc) · 4.62 KB

CLAUDE.md

File metadata and controls

113 lines (85 loc) · 4.62 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Gradle plugin repository that provides three Docker-related Gradle plugins:

  • com.method.docker - Build and push Docker images
  • com.method.docker-compose - Generate docker-compose files with resolved dependencies
  • com.method.docker-run - Run, stop, and manage Docker containers

Build Commands

Running Tests

./gradlew check

Running a Specific Test

./gradlew test --tests "com.palantir.gradle.docker.MethodDockerPluginTests"

Building (without tests)

./gradlew build -x test -x check

Publishing

./gradlew publish

Note: publishPlugins task only runs if the current state is a clean tag.

Code Architecture

Plugin Structure

The codebase is organized into three main plugins, each with its own entry point:

  1. MethodDockerPlugin (com.method.docker)

    • Entry point: src/main/groovy/com/palantir/gradle/docker/MethodDockerPlugin.groovy
    • Extension: DockerExtension.groovy
    • Creates tasks: docker, dockerPrepare, dockerClean, dockerTag*, dockerPush*, dockerfileZip
    • Builds Docker images based on configuration and Dockerfile

  2. DockerComposePlugin (com.method.docker-compose)

    • Entry point: src/main/groovy/com/palantir/gradle/docker/DockerComposePlugin.groovy
    • Extension: DockerComposeExtension.groovy
    • Creates tasks: generateDockerCompose, dockerComposeUp, dockerComposeDown
    • Resolves Docker image dependencies and populates template files

  3. DockerRunPlugin (com.method.docker-run)

    • Entry point: src/main/groovy/com/palantir/gradle/docker/DockerRunPlugin.groovy
    • Extension: DockerRunExtension.groovy
    • Creates tasks: dockerRun, dockerStop, dockerRunStatus, dockerRemoveContainer
    • Manages Docker container lifecycle

Key Implementation Details

  • DockerExtension: Holds configuration for building Docker images (name, dockerfile, tags, buildArgs, labels, pull, noCache, buildx, platform, etc.)
  • CopySpec Pattern: Uses Gradle's CopySpec to collect files for the Docker build context
  • Task Dependencies: The dockerPrepare task copies files into build/docker/ before the docker task runs
  • Tag Management: Supports both deprecated tags() method and newer tag(taskName, tagName) method for creating tagged images
  • Docker Component: Implements a custom Gradle component for Maven publishing of Docker image dependencies

Testing

Tests are located in src/test/groovy/com/palantir/gradle/docker/:

  • AbstractPluginTest.groovy - Base test class with helper methods
  • MethodDockerPluginTests.groovy - Tests for main Docker plugin
  • DockerComposePluginTests.groovy - Tests for compose plugin
  • DockerRunPluginTests.groovy - Tests for run plugin

Tests use GradleTestKit and Spock framework. The AbstractPluginTest provides utilities like with() for running Gradle tasks and exec() for executing shell commands.

Gradle Configuration

  • Java Target: Library targets Java 21
  • Daemon Target: JDK 21 for Gradle daemon
  • Test Gradle Versions: Tests run against Gradle 8.14.3
  • Parallel Builds: Enabled via org.gradle.parallel=true
  • Dependency Management: Uses com.palantir.consistent-versions plugin with versions defined in versions.props

Palantir Infrastructure Plugins

This project uses several Palantir infrastructure plugins:

  • com.palantir.baseline - Code quality and formatting standards
  • com.palantir.java-format - Java code formatting (native formatter enabled)
  • com.palantir.git-version - Version from git tags
  • com.palantir.external-publish - Publishing configuration
  • com.palantir.failure-reports - Test failure reporting
  • com.palantir.jdks - JDK provisioning and management

CI/CD

GitHub Actions is configured with a modular workflow structure:

Workflow Structure

  • Entry Point Workflows:

    • pr-review.yml - Runs on pull requests and pushes to develop/main branches
    • publish.yml - Runs on merge to develop branch and on tags (publishing step currently disabled)

  • Reusable Workflows:

    • reusable-check.yml - Runs ./gradlew check (tests, checkstyle, etc.) with parallel execution
    • reusable-build.yml - Runs ./gradlew build -x test -x check to compile and package

Key Features

  • Uses Amazon Corretto JDK 21
  • Gradle caching is enabled for faster builds
  • Enforces that no git-tracked files are modified during the build process
  • Uploads test results and build artifacts for inspection
  • Publishes test results directly to PR for easy review