FAQ - Frequently Asked Questions

General

What is DockAI?

DockAI is an AI-powered framework that automatically generates production-ready Dockerfiles for any codebase. It uses Large Language Models (LLMs) and Retrieval-Augmented Generation (RAG) to understand your project and create optimized, secure Dockerfiles.

How is DockAI different from template-based generators?

DockAI doesn’t use templates. Instead, it:

Is DockAI free?

DockAI itself is free and open-source (MIT License). However, you need an API key from an LLM provider:

Typical cost per generation: $0.02 - $0.10 depending on the model.

What languages/frameworks does DockAI support?

DockAI supports virtually any language or framework:

If the project has code, DockAI can dockerize it!

Usage

Can I use DockAI for monorepos or multi-language projects?

Yes! Run DockAI separately for each component:

# Frontend
cd frontend
dockai build .

# Backend
cd ../backend
dockai build .

Each will get a tailored Dockerfile. For true monorepo support (single Dockerfile with multiple services), this is planned for a future release.

Can DockAI update an existing Dockerfile?

Yes! If a Dockerfile already exists, DockAI will:

  1. Read and analyze the existing Dockerfile
  2. Use it as a reference when generating a new one
  3. Preserve good patterns and fix issues

The existing Dockerfile is included in the RAG context automatically.

How do I customize the generated Dockerfile?

You have several options:

1. Custom Instructions (Recommended):

export DOCKAI_GENERATOR_INSTRUCTIONS="Always use Alpine Linux. Pin all versions."
dockai build .

2. Iterative Refinement: Edit the generated Dockerfile, run DockAI again. It will analyze your changes.

3. Custom Prompts (Advanced): Completely replace agent prompts via environment variables or .dockai/prompts/ files.

Can I run DockAI in CI/CD?

Absolutely! DockAI is designed for automation:

GitHub Actions:

- uses: itzzjb/dockai@v4
  with:
    openai_api_key: $

GitLab CI, Jenkins, etc.:

pip install dockai-cli
dockai build .

See GitHub Actions Guide for details.

How long does it take to generate a Dockerfile?

Typical times:

Bottlenecks:

To speed up iteration, skip validation:

export DOCKAI_SKIP_HADOLINT="true"
export DOCKAI_SKIP_SECURITY_SCAN="true"

Technical

What is RAG and why does DockAI use it?

RAG (Retrieval-Augmented Generation) is a technique where relevant context is retrieved from a knowledge base before sending it to the LLM.

Why DockAI uses RAG:

How it works in DockAI:

  1. Index all files with semantic embeddings
  2. When generating, search for files relevant to the task
  3. Send only top-k relevant chunks to the LLM

Can I disable RAG?

Yes, but not recommended:

export DOCKAI_USE_RAG="false"

This falls back to a simple “read all text files until token limit” strategy, which is less efficient and may miss important context.

What embedding model does DockAI use?

Default: all-MiniLM-L6-v2 (sentence-transformers)

Alternatives:

# Higher quality, slower
export DOCKAI_EMBEDDING_MODEL="all-mpnet-base-v2"

# Faster, smaller
export DOCKAI_EMBEDDING_MODEL="paraphrase-MiniLM-L3-v2"

How does DockAI handle secrets?

DockAI never sends your secrets to the LLM:

Best Practice: Use environment variables, not hardcoded secrets.

Can I use a local LLM?

Yes! Use Ollama:

ollama serve
ollama pull llama3.1

export DOCKAI_LLM_PROVIDER="ollama"
export DOCKAI_MODEL_ANALYZER="llama3.1"
export DOCKAI_MODEL_GENERATOR="llama3.1"

dockai build .

Note: Local models (even large ones) are generally less capable than cloud models like GPT-4 or Gemini 1.5 Pro. Expect lower quality.

How much does DockAI cost per run?

Approximate costs (varies by project size):

Provider Model Analyzer Generator Total
OpenAI gpt-4o-mini + gpt-4o $0.01 $0.04 $0.05
Google gemini-1.5-flash + pro $0.002 $0.015 $0.02
Anthropic claude-3-haiku + 3.5-sonnet $0.01 $0.06 $0.07
Ollama llama3.1 $0 $0 $0

Token Usage (Typical):

With retries, expect 1.5-2x tokens.

Does DockAI send my code to third parties?

Yes, if using cloud LLMs (OpenAI, Google, Anthropic, Azure):

No, if using Ollama:

Recommendation: Use cloud LLMs for public/open-source projects. Use Ollama for proprietary code if you have concerns.

Troubleshooting

Why does DockAI keep failing on my project?

Common reasons:

  1. Unusual project structure: DockAI works best with conventional layouts (e.g., package.json at root for Node.js)
  2. Missing dependencies: Ensure requirements.txt, package.json, go.mod, etc. are present
  3. Complex build process: Multi-step builds, custom scripts may confuse the AI
  4. Max retries reached: Try increasing MAX_RETRIES

Debugging:

dockai build . --verbose

Look at the reflection output (🤔 stage) to see what the AI identified as the issue.

Why is the generated Dockerfile huge?

Possible causes:

  1. Base image choice: AI selected a large base image (e.g., ubuntu:latest instead of alpine)
  2. Unnecessary dependencies: Installing dev tools in production stage

Solutions:

# Guide the AI
export DOCKAI_GENERATOR_INSTRUCTIONS="Use Alpine Linux. Multi-stage build. Minimal dependencies."
dockai build .

# Or set size limit
export DOCKAI_MAX_IMAGE_SIZE_MB="200"

DockAI generated a Dockerfile but it doesn’t work when I run it manually

This usually means the validation passed but there’s a runtime issue not caught by health checks.

Common issues:

Debug:

docker build -t myapp .
docker run -it --rm myapp  # Interactive mode to see errors

Can DockAI generate Dockerfiles for Lambdas/serverless?

Not optimally. DockAI is designed for containerized applications (web apps, APIs, background workers).

For AWS Lambda, use the AWS-provided base images and tools. DockAI might generate a working Dockerfile, but it won’t be optimized for Lambda’s specific requirements.

Why does RAG indexing take so long?

RAG indexing uses CPU-based embeddings, which can be slow for very large projects.

Solutions:

  1. Use a faster model: 
    export DOCKAI_EMBEDDING_MODEL="paraphrase-MiniLM-L3-v2"

  2. Reduce file count: Add more patterns to .gitignore or .dockerignore

  3. Disable RAG (not recommended): 
    export DOCKAI_USE_RAG="false"

Typical indexing times:

How do I report a bug?

  1. Check existing issues: GitHub Issues
  2. Run with verbose logging: 
    dockai build . --verbose > debug.log 2>&1
  3. File a new issue with:
    • Project type (language, framework)
    • Generated Dockerfile (if applicable)
    • Error logs from debug.log
    • DockAI version (dockai version)

Best Practices

  1. Initial Generation: 
    dockai build .

  2. Review the Dockerfile: Understand what was generated and why

  3. Test locally: 
    docker build -t myapp .
docker run -p 3000:3000 myapp
  4. Iterate with instructions if needed: 
    export DOCKAI_GENERATOR_INSTRUCTIONS="Use Node 20. Add health check timeout of 10s."
dockai build .

  5. Commit to version control

  6. Automate in CI/CD (optional)

Should I commit the generated Dockerfile?

Yes! The Dockerfile is source code. Commit it to version control.

Benefits:

Can I use DockAI for production?

Yes, with review! DockAI generates production-ready Dockerfiles, but:

  1. Always review the generated Dockerfile
  2. Test thoroughly in staging
  3. Monitor in production (resource usage, security)
  4. Understand what was generated (don’t blindly trust AI)

DockAI is a tool to accelerate development, not replace engineering judgment.

How do I keep my Dockerfiles up to date?

Re-run DockAI periodically:

# Every few months, or when you upgrade dependencies
dockai build .

DockAI will incorporate the existing Dockerfile and suggest improvements.

Automation idea: Run DockAI in CI, create a PR if the Dockerfile changes.

Advanced

Can I extend DockAI with custom agents?

Not currently in v4.0, but this is planned for a future release.

Workaround: Use custom prompts to completely override agent behavior.

Can I use DockAI to generate docker-compose.yml?

Not yet. DockAI v4.0 only generates Dockerfile.

Planned for v4.1:

How does DockAI decide when to reanalyze vs. retry?

The Reflector agent uses reasoning to decide:

Retry (generate_node):

Reanalyze (analyze_node):

Give Up:

Can I contribute to DockAI?

Absolutely! DockAI is open-source.

Ways to contribute:

What’s next for DockAI?

Roadmap for v4.1 - v5.0:

Follow progress on GitHub.

Have a question not answered here? Ask in GitHub Discussions