feat(docker): Comprehensive Docker Setup Enhancement with Performance & Security Improvements

[kzndotsh]

Summary by Sourcery

Enhance Docker integration across the project by adding robust security validation, resource cleanup, and new CLI commands, refactoring the Dockerfile for performance and security, updating compose configurations with limits and healthchecks, introducing a unified docker-toolkit script with extensive testing and monitoring capabilities, enriching user documentation, and consolidating GitHub Actions workflows into a streamlined CI/CD pipeline.

New Features:

• Implement allowlist-based Docker command validation and resource name sanitization in the CLI to prevent injection
• Add new docker subcommands (shell, restart, health, test, cleanup) with advanced options for building, testing, monitoring, and safe cleanup
• Provide a unified Bash toolkit script for quick, standard, and comprehensive Docker testing, performance monitoring, and resource management

Enhancements:

• Refactor Dockerfile into multi-stage builds with pinned dependencies, non-root user setup, aggressive virtualenv cleanup, healthcheck, and optimized caching
• Extend existing CLI commands (build, up, down, logs, exec) with additional flags (no-cache, target, watch, tail, volumes, remove-orphans, interactive) and error handling
• Update docker-compose.yml and docker-compose.dev.yml to enforce resource constraints, read-only mounts, new volumes, healthchecks, and logging limits

CI:

• Consolidate and modernize GitHub Actions into ci.yml, docker.yml, security.yml, maintenance.yml, and release workflows with standardized caching, buildx, scanning, and maintenance jobs

Documentation:

• Add DOCKER.md as a comprehensive user guide for Docker setup, testing strategies, performance baselines, and security best practices

[kzndotsh]

@sourcery-ai review

[sourcery-ai]

Hey @kzndotsh - I've reviewed your changes and they look great!

Blocking issues:

• Detected subprocess function 'run' without a static string. If this data can be controlled by a malicious actor, it may be an instance of command injection. Audit the use of this call to ensure it is not controllable by an external resource. You may consider using 'shlex.escape()'. (link)

Here's what I looked at during the review

• 🟡 General issues: 3 issues found
• 🔴 Security: 1 blocking issue
• 🟢 Testing: all looks good
• 🟢 Complexity: all looks good
• 🟢 Documentation: all looks good

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[sourcery-ai]

suggestion (performance): Move allowed_format_strings out of hot path

Extract the set to a module-level constant to avoid recreating it on each function call and improve efficiency.

Suggested implementation:

ALLOWED_DOCKER_FORMAT_STRINGS = {
    "{{.Repository}}:{{.Tag}}",
    "{{.Names}}",
    "{{.Name}}",
    "{{.State.Status}}",
    "{{.State.Health.Status}}",
    "{{.Repository}}",
    "{{.Tag}}",
    "{{.ID}}",
    "{{.Image}}",
    "{{.Command}}",
    "{{.CreatedAt}}",
    "{{.Status}}",
}

def _validate_docker_command(cmd: list[str]) -> bool:
    """Validate that a Docker command contains only allowed components."""
    # Use module-level allowed Docker format strings for security

    allowed_format_strings = ALLOWED_DOCKER_FORMAT_STRINGS

[sourcery-ai]

suggestion: Use a standard short option for interactive flag

Using -it as a short option is non-standard in click; it will be parsed as -i and -t. Prefer -i (or -I) for the interactive flag, with TTY allocation implied when interactive is enabled.

Suggested change

	@click.option("-it", "--interactive", is_flag=True, default=True, help="Keep STDIN open and allocate a TTY.")
	@click.option("-i", "--interactive", is_flag=True, default=True, help="Keep STDIN open and allocate a TTY (implied when interactive).")

[sourcery-ai]

issue: Healthcheck always returns success

The current healthcheck always succeeds, so Docker can't detect actual failures. Use a check that verifies real service health, such as an HTTP request or status command.

[sourcery-ai]

security (dangerous-subprocess-use-audit): Detected subprocess function 'run' without a static string. If this data can be controlled by a malicious actor, it may be an instance of command injection. Audit the use of this call to ensure it is not controllable by an external resource. You may consider using 'shlex.escape()'.

Source: opengrep