dockerfile-assistant 1.3.0
AI-powered Dockerfile generation and analysis
Requires Python: >=3.13
Keywords: dockerfile, docker, ai, assistant, pydantic-ai

# Dockerfile Assistant

AI-powered CLI tool that generates production-ready Dockerfiles and .dockerignore files for Python and Node.js projects.

## Features

- **Multi-Provider LLM Support** - OpenAI, Google (Gemini), Anthropic (Claude), Groq, and Ollama (local)
- **Automatic Stack Detection** - Detects Python/Node.js, package managers, entry points, and ports
- **Production-Ready Templates** - Multi-stage builds, non-root users, health checks
- **Interactive TUI** - Menu-based configuration with persistent settings
- **No .env Required** - Configuration stored in `~/.config/dockerfile-assistant/config.json`

## Installation

```bash
pip install dockerfile-assistant
```

### From Source

```bash
git clone https://github.com/giulianotesta7/dockerfile-assistant.git
cd dockerfile-assistant
pip install -e .
```

## Usage

Navigate to your project directory and run:

```bash
cd /path/to/your/project
dockerfile-assistant
```

On first run, you'll see the configuration menu. Set up your provider, API key, and model before selecting a mode.

### Main Menu

```
╭──────────────────────────────────────────────────────────────────────╮
│            ▓▓                                                        │
│      ▒▒ ▒▒ ▒▒ ▐█▄▄█▌       Provider: Anthropic                       │
│   ░░ ░░ ░░ ░░  ▀██▀        Model: claude-sonnet-4-20250514           │
│  ▟███████████████▛         API Key: Set                              │
│  ████▄█████████▀                                                     │
│  ▜███████████▀                                                       │
│                                                                      │
│ Dockerfile Assistant                                                 │
│ Working on: ~/my-project                                             │
╰──────────────────────────────────────────────────────────────────────╯

┌─ Select a mode ──────────────────────────────────────────────────────┐
│ > Analyze: Reads your project to generate a matching Dockerfile      │
│   Describe: Generates a Dockerfile from your description             │
│   Config: Configure provider, API key and model                      │
└──────────────────────────────────────────────────────────────────────┘
```

### Mode Comparison

| Feature | Analyze | Describe |
|---------|---------|----------|
| Auto-detects stack | Yes | No |
| Auto-detects dependencies | Yes | No |
| Reads project files | Yes | No |
| Saves files to disk | Yes | No |
| User provides project info | Optional | Yes |

### Analyze Mode

The AI automatically:
- Explores your project directory
- Detects stack from file signatures (package.json, requirements.txt, etc.)
- Finds entry points and ports from configuration
- Generates and saves Dockerfile and .dockerignore

Just ask: `"Generate a Dockerfile for my project"`

> **Note:** Requires a model that supports tool/function calling. Small local models (< 30B parameters) may struggle with file exploration.

### Describe Mode

Provide information about:
- Stack (Python or Node.js)
- Package manager (pip, poetry, npm, yarn, pnpm)
- Container port
- Start command

The AI generates a Dockerfile based on your description.

## Configuration

All configuration is stored in `~/.config/dockerfile-assistant/config.json` and managed through the TUI.

### First-Time Setup

1. Run `dockerfile-assistant`
2. Select **Config** from the menu
3. Set your **Provider** (OpenAI, Anthropic, Google, Groq, or Ollama)
4. Set your **API Key** (not required for Ollama)
5. Set your **Model** name
6. Press **Back** to return to the main menu

### Supported Providers

| Provider | Model Examples | Documentation |
|----------|----------------|---------------|
| `openai` | gpt-4o, gpt-4-turbo | [OpenAI Models](https://platform.openai.com/docs/models) |
| `anthropic` | claude-sonnet-4-20250514 | [Anthropic Models](https://platform.claude.com/docs/en/about-claude/models/overview) |
| `google` | gemini-2.0-flash | [Google AI Models](https://ai.google.dev/gemini-api/docs/models) |
| `groq` | llama-3.3-70b-versatile | [Groq Models](https://console.groq.com/docs/models) |
| `ollama` | llama3.1:8b | Run `ollama list` locally |

### Configuration File

Settings are stored in `~/.config/dockerfile-assistant/config.json`:

```json
{
  "provider": "anthropic",
  "model": "claude-sonnet-4-20250514",
  "ollama_base_url": "http://localhost:11434",
  "api_keys": {
    "openai": null,
    "anthropic": "sk-ant-...",
    "google": null,
    "groq": null
  }
}
```

## Generated Dockerfile Features

All generated Dockerfiles include:

- **Multi-stage builds** for optimized image size
- **Non-root user** for security
- **Health checks** for container orchestration
- **Optimized base images** (python:3.12-slim, node:20-alpine)

### Supported Stacks

| Stack | Package Managers |
|-------|------------------|
| Python | pip, poetry |
| Node.js | npm, yarn, pnpm |

## Requirements

- Python 3.13+
- Node.js (only required for Analyze mode - filesystem MCP features)

## Security

- The AI cannot read or write `.env` files - access is blocked for security
- API keys are stored locally in your home directory config file
- In Analyze mode, the AI only has access to the current working directory

## License

MIT License - see [LICENSE](LICENSE) for details.

## Author

Giuliano Testa ([@giulianotesta7](https://github.com/giulianotesta7))

## Acknowledgments

- System prompts were crafted with the assistance of [Claude](https://claude.ai) (Anthropic)
- Built with [Pydantic AI](https://github.com/pydantic/pydantic-ai)