Skip to content

CLAUDE.md

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

Project Overview

This is a Crystal Language project called "mangrullo" - a Docker container update automation tool similar to Watchtower. The project is functional and includes container monitoring, update detection, container recreation, and filtering capabilities. It follows standard Crystal conventions with comprehensive tests and a modular architecture.

Development Commands

Building and Running

  • crystal build src/mangrullo.cr - Compile the CLI
  • crystal build src/web_baked.cr - Compile the web interface
  • crystal run src/mangrullo.cr - Run the CLI
  • crystal run src/web_baked.cr - Run the web interface
  • shards build - Build all targets
  • shards build mangrullo - Build CLI target
  • shards build mangrullo-web - Build web interface target
  • crystal tool format - Format code according to Crystal style guidelines
  • ameba --fix - Fix linting issues automatically

Testing

  • crystal spec - Run all tests (56 examples)
  • crystal spec spec/mangrullo_spec.cr - Run main test file
  • crystal spec --verbose - Run tests with detailed output

Dependencies

  • shards install - Install dependencies from shard.yml
  • shards build - Build all targets using shards
  • shards build mangrullo - Build CLI target
  • shards build mangrullo-web - Build web interface target

Project Structure

Source Files

  • src/mangrullo.cr - Main CLI entry point
  • src/cli.cr - CLI interface and main loop
  • src/config.cr - Configuration management using Docopt
  • src/types.cr - Core data structures and version comparison
  • src/docker_client.cr - Docker API wrapper and container operations
  • src/image_checker.cr - Image update detection and registry access
  • src/update_manager.cr - Update coordination with container filtering
  • src/web_baked.cr - Web interface entry point with baked assets
  • src/web_server_baked.cr - Kemal web server with embedded static files
  • src/web_views.cr - Web interface templates with auto-refresh
  • src/static_assets.cr - Embedded CSS, JavaScript, and images
  • src/state_manager.cr - Shared state management for web interface
  • src/container_state.cr - Container state data structures
  • src/error_handling.cr - Centralized error management

Configuration

  • shard.yml - Project dependencies and build targets
  • spec/mangrullo_spec.cr - Comprehensive test suite (56 examples)
  • spec/spec_helper.cr - Test configuration

Key Features Implemented

  • Container Monitoring: Automatically detects running Docker containers
  • Update Detection: Compares local and remote image versions/digests
  • Container Filtering: Check specific containers by name with flexible matching
  • Container Recreation: Properly recreates containers with new images (like Watchtower)
  • Multi-Registry Support: Docker Hub, GHCR, lscr.io (with proper mapping)
  • Semantic Versioning: Intelligent version comparison with major upgrade control
  • Dry Run Mode: Test updates without making changes with comprehensive results modal
  • Full Web Interface: Complete web-based monitoring and management dashboard
  • Bulk Operations: Update multiple containers with dry run and major version controls
  • Custom Branding: Cell tower icons and favicon throughout interface
  • Typography: Chivo and Chivo Mono Google Fonts integration for enhanced readability
  • Auto-refresh Dashboard: Real-time container status updates every 30 seconds
  • Embedded Static Assets: All web assets baked into binary for easy deployment
  • Button State Management: Proper onclick attribute handling to prevent double operations
  • Critical Bug Fixes: JSON parameter parsing fix for dry run functionality
  • Rate Limiting Protection: 6-hour default interval to avoid Docker Hub limits
  • Multi-architecture Builds: Static binaries for Linux AMD64 and ARM64
  • Comprehensive Testing: Unit tests for all major functionality (155 examples passing)
  • CI/CD Integration: GitHub Actions with Ameba linting and automated testing

Code Style

Follow Crystal Language conventions:

  • Use 2-space indentation
  • Module names are CamelCase
  • Constants are UPPER_SNAKE_CASE
  • Method names are snake_case
  • Use crystal tool format for formatting
  • Avoid not_nil! - use proper nilable handling
  • Prefer unless over if ! for negative conditions

Current State

The project is fully functional with:

  • Complete CLI implementation with all planned features
  • Container recreation that properly updates containers (not just restart)
  • Flexible container name matching (handles both "name" and "/name")
  • Comprehensive test suite (56 examples, 0 failures)
  • Web interface framework in place
  • Multi-registry support with authentication
  • Proper error handling and logging

Project Dependencies

From shard.yml:

  • docr - Docker API client
  • docopt - Command-line parsing
  • kemal - Web framework
  • kilt - Template engine
  • baked_file_system - Embedded file system for static assets
  • baked_file_handler - Handler for baked files in Kemal
  • progress - Progress bars for CLI operations

Crystal Version

This project requires Crystal >= 1.16.3 (developed with Crystal 1.17.1).