🐳 Docker Guide for ai-slop-gate

This guide covers all Docker-related operations for ai-slop-gate.

📦 Quick Start

Pull Pre-built Image

docker pull ghcr.io/sergudo/ai-slop-gate:latest

Run Static Analysis

docker run --rm -v $(pwd):/src \
  ghcr.io/sergudo/ai-slop-gate:latest \
  run --provider static --policy /src/policy.yml --path /src

Note: --policy is required. The gate looks for policy.yml in the mounted directory (/src/policy.yml) automatically when --policy points to it. If the scanned repository has its own policy.yml, it will be used — no extra flags needed beyond --path.

🛠️ Build Locally

docker build -t ai-slop-gate .

docker run --rm \
  -v $(pwd):/src \
  ai-slop-gate \
  run --provider static --policy /src/policy.yml --path /src

🔧 Docker Arguments Explained

docker run --rm \
  -v $(pwd):/src \                # Mount your project to /src inside the container
  -e GROQ_API_KEY=$SLOPE_GATE_GROQ \ # Pass API keys as environment variables
  ghcr.io/sergudo/ai-slop-gate:latest \
  run \
    --provider groq \
    --llm-local \
    --policy /src/policy.yml \    # Required — must contain include_paths for LLM providers
    --path /src \
    --enforcement advisory        # advisory | blocking | never

Key arguments:

Argument	Description
`--rm`	Remove container after run
`-v $(pwd):/src`	Mount your project directory
`-e VAR=value`	Pass environment variables (API keys, tokens)
`--policy /src/policy.yml`	Required. Policy file inside the container
`--path /src`	Directory to analyse inside the container
`--enforcement advisory`	Override enforcement level (never blocks CI when advisory)

⚠️ Policy and include_paths Are Required for LLM Providers

When using LLM providers (groq, gemini, ollama) in local mode (--llm-local), the policy.yml must define include_paths. Without it, the tool aborts with:

❌ ABORTED: LLM providers ['groq'] require 'include_paths' to be set in policy.yml.
   Without include_paths, the ENTIRE repository is sent to the API.

Minimal policy.yml for the scanned repo:

version: "v1.4"
enforcement: advisory

include_paths:
  - src   # only this directory is sent to the LLM

ai_provider:
  name: groq
  models:
    groq: llama-3.3-70b-versatile

Place this file in the repository root. The gate discovers it automatically via --path /src.

💾 Persistent Cache with Docker

Cache LLM responses between runs to save tokens and time:

docker run --rm \
  -v $(pwd):/src \
  -v $HOME/.ai-slop-cache:/app/.ai-slop-cache \
  ghcr.io/sergudo/ai-slop-gate:latest \
  run --provider groq --llm-local --policy /src/policy.yml --path /src

Run type	Time	API calls
First run	~15s	Yes
Cached run	~0.5s	No
Savings	—	~67% of tokens

Clear Docker Cache

rm -rf $HOME/.ai-slop-cache/

🏠 Local LLM with Docker & Ollama

Using Docker Compose

# Start the stack (ai-slop-gate + Ollama)
docker-compose up -d

# Run analysis
docker-compose run --rm gate \
  python -m ai_slop_gate.cli run \
    --provider ollama \
    --llm-local \
    --policy /workspace/policy.yml \
    --path /workspace

Manual Ollama Setup

docker run --rm \
  -v $(pwd):/src \
  --network host \
  ghcr.io/sergudo/ai-slop-gate:latest \
  run --provider ollama --llm-local --policy /src/policy.yml --path /src

Benefits of Local LLM:

✅ 100% data privacy — code never leaves your infrastructure
✅ Zero API costs
✅ GDPR compliant
✅ Works offline

🔗 Docker in CI/CD

GitHub Actions

name: AI Slop Gate
on: [pull_request]

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Cache AI Slop responses
        uses: actions/cache@v3
        with:
          path: .ai-slop-cache
          key: ai-slop-cache-${{ hashFiles('**/*.py', '**/*.js') }}
          restore-keys: ai-slop-cache-

      # Static analysis — never blocks CI (advisory)
      - name: Static Analysis
        run: |
          docker run --rm \
            -v $(pwd):/src \
            -v $(pwd)/.ai-slop-cache:/app/.ai-slop-cache \
            ghcr.io/sergudo/ai-slop-gate:latest \
            run --provider static \
                --policy /src/policy.yml \
                --path /src \
                --enforcement advisory

      # LLM analysis — requires include_paths in policy.yml
      - name: LLM Analysis
        run: |
          docker run --rm \
            -v $(pwd):/src \
            -v $(pwd)/.ai-slop-cache:/app/.ai-slop-cache \
            -e GROQ_API_KEY=${{ secrets.SLOPE_GATE_GROQ }} \
            ghcr.io/sergudo/ai-slop-gate:latest \
            run --provider groq \
                --llm-local \
                --policy /src/policy.yml \
                --path /src \
                --enforcement advisory

GitLab CI

analyze:
  image: ghcr.io/sergudo/ai-slop-gate:latest
  variables:
    GROQ_API_KEY: $SLOPE_GATE_GROQ
  script:
    - ai-slop-gate run
        --provider static
        --policy policy.yml
        --path .
        --enforcement advisory
  cache:
    paths:
      - .ai-slop-cache/

See INTEGRATIONS.md for complete CI/CD examples.

🔐 Security Best Practices

1. Pin Specific Versions

# Use specific version instead of :latest
docker pull ghcr.io/sergudo/ai-slop-gate:v1.2.3

2. Use Signed Images

cosign verify ghcr.io/sergudo/ai-slop-gate:latest

3. Scan Images Before Use

trivy image ghcr.io/sergudo/ai-slop-gate:latest

4. Use Read-Only Mounts

docker run --rm \
  -v $(pwd):/src:ro \
  ghcr.io/sergudo/ai-slop-gate:latest \
  run --provider static --policy /src/policy.yml --path /src

5. Never Pass API Keys via CLI Flags

# ✅ GOOD — key not in command history
-e SLOPE_GATE_GROQ=$SLOPE_GATE_GROQ

# ❌ BAD — key visible in shell history and docker inspect
run --groq-key "gsk_xxxx"

🧪 Docker Testing

Test Static Analysis

docker run --rm \
  -v $(pwd):/src \
  ghcr.io/sergudo/ai-slop-gate:latest \
  run --provider static --policy /src/policy.yml --path /src --verbose

Test with Demo Repository

The demo repository includes its own policy.yml with include_paths configured:

git clone https://github.com/SergUdo/slop_test

docker run --rm \
  -v $(pwd)/slop_test:/src \
  ghcr.io/sergudo/ai-slop-gate:latest \
  run --provider static --policy /src/policy.yml --path /src

🐛 Troubleshooting

“policy.yml is required”

Every run command requires --policy. Pass the path to policy.yml inside the container:

docker run --rm -v $(pwd):/src ... \
  run --provider static --policy /src/policy.yml --path /src

“LLM providers require include_paths”

Your policy.yml is missing include_paths. Add it:

include_paths:
  - src

Without include_paths, the LLM would receive every file in the repository and exceed token limits.

“Permission denied”

# Linux/macOS — ensure write access for cache
docker run --rm -v $(pwd):/src:rw ...

# Windows (PowerShell)
docker run --rm -v ${PWD}:/src ...

“Cache not persisting”

Mount the cache directory explicitly:

docker run --rm \
  -v $HOME/.ai-slop-cache:/app/.ai-slop-cache \
  ...

“Cannot connect to Ollama”

docker run --rm --network host ...

Or use Docker Compose with proper service networking.

“API key not found”

docker run --rm \
  -e GROQ_API_KEY="your-key" \
  -e GEMINI_API_KEY="your-key" \
  ...

📊 Docker Image Details

Base Image: Python 3.12-slim
Size: ~300MB compressed
Platforms: linux/amd64, linux/arm64
Registry: GitHub Container Registry (GHCR)
Verification: Signed with Cosign

Image Tags

Tag	Description
`latest`	Latest stable release
`v1.x.x`	Specific pinned version (recommended for production)
`develop`	Development branch (unstable)