feat: add Podman support as Docker alternative (#34)

Add container runtime abstraction so mxcli works with both Docker and
Podman 4.7+. Auto-detects the runtime on PATH, with MXCLI_CONTAINER_CLI
env var as explicit override. Adds --container-runtime flag to mxcli init
and a Podman-in-Podman devcontainer config.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: ako

.claude/skills/mendix/docker-workflow.md

@@ -14,18 +14,27 @@ Use this when:
 
 The devcontainer created by `mxcli init` includes:
 - **JDK 21** (Adoptium temurin-21-jdk) — required by MxBuild
-- **Docker-in-Docker** — Docker daemon running inside the devcontainer
+- **Docker-in-Docker** (or **Podman-in-Podman**) — container runtime inside the devcontainer
 - **Port forwarding** — ports 8080 (app) and 8090 (admin) auto-forwarded
 
+### Podman Support
+
+mxcli auto-detects Docker or Podman. To force Podman:
+```bash
+export MXCLI_CONTAINER_CLI=podman
+```
+
+When using `mxcli init`, pass `--container-runtime podman` to generate a devcontainer with Podman-in-Podman instead of Docker-in-Docker. Requires Podman 4.7+ (ships `podman compose` natively).
+
 ## Architecture
 
 ```
 Host machine (browser at localhost:8080)
-  └── Docker (host daemon)
+  └── Docker or Podman (host daemon)
       └── Devcontainer (VS Code)
           ├── mxcli, JDK 21, project files
-          └── Docker daemon (docker-in-docker)
-              └── docker compose stack
+          └── Docker/Podman daemon (docker-in-docker or podman-in-podman)
+              └── docker/podman compose stack
                   ├── mendix container (8080, 8090)
                   │     └── /mendix ← volume mount from .docker/build/
                   └── postgres container (5432)
@@ -392,7 +401,7 @@ All defaults can be overridden in `.docker/.env`.
 
 | Problem | Solution |
 |---------|----------|
-| `docker: command not found` | Rebuild devcontainer — docker-in-docker feature needs rebuild to activate |
+| `docker: command not found` | Rebuild devcontainer — docker-in-docker feature needs rebuild to activate. Or use Podman: `export MXCLI_CONTAINER_CLI=podman` |
 | `mxbuild not found` | Run `mxcli setup mxbuild -p app.mpr` to download from CDN |
 | `JDK 21 not found` | Rebuild devcontainer — JDK 21 should be pre-installed |
 | Build fails with version error | Requires Mendix >= 11.6.1 for PAD support |

.devcontainer/podman/devcontainer.json

@@ -0,0 +1,44 @@
+{
+  "name": "Mendix Model SDK Go (Podman)",
+  "build": {
+    "dockerfile": "../Dockerfile"
+  },
+  "features": {
+    "ghcr.io/devcontainers/features/podman-in-podman:1": {},
+    "ghcr.io/devcontainers/features/github-cli:1": {}
+  },
+  "forwardPorts": [8080, 8090, 5432],
+  "portsAttributes": {
+    "8080-8099": { "onAutoForward": "silent" },
+    "5432-5499": { "onAutoForward": "silent" }
+  },
+  "containerEnv": {
+    "MXCLI_CONTAINER_CLI": "podman"
+  },
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "golang.go",
+        "ms-vscode.makefile-tools",
+        "anthropic.claude-code",
+        "mike-lischke.vscode-antlr4"
+      ],
+      "settings": {
+        "go.toolsManagement.autoUpdate": true,
+        "go.useLanguageServer": true,
+        "go.lintTool": "golangci-lint",
+        "editor.formatOnSave": true,
+        "[go]": {
+          "editor.defaultFormatter": "golang.go"
+        }
+      }
+    }
+  },
+  "postCreateCommand": "curl -fsSL https://claude.ai/install.sh | bash && go mod download",
+  "remoteUser": "vscode",
+  "remoteEnv": {
+    "CGO_ENABLED": "0",
+    "LANG": "en_US.UTF-8",
+    "LC_ALL": "en_US.UTF-8"
+  }
+}

cmd/mxcli/docker.go

@@ -32,7 +32,11 @@ Requirements:
   - Mendix 11.6.1 or later
   - MxBuild (auto-downloaded from CDN if not found)
   - JDK 21 (installed in devcontainers created by 'mxcli init')
-  - Docker with Compose V2
+  - Docker with Compose V2, or Podman 4.7+ with podman compose
+
+Podman Support:
+  mxcli auto-detects the container runtime (Docker or Podman).
+  Override with: export MXCLI_CONTAINER_CLI=podman
 
 Examples:
   # One command to setup, build, and start

cmd/mxcli/docker/m2ee.go

@@ -163,7 +163,7 @@ func callM2EEViaDocker(opts M2EEOptions, dockerDir string, action string, params
 	)
 
 	composePath := filepath.Join(dockerDir, "docker-compose.yml")
-	cmd := exec.Command("docker", "compose", "-f", composePath, "exec", "-T", "mendix", "sh", "-c", curlCmd)
+	cmd := exec.Command(ContainerCLI(), "compose", "-f", composePath, "exec", "-T", "mendix", "sh", "-c", curlCmd)
 
 	var stdout, stderr bytes.Buffer
 	cmd.Stdout = &stdout

cmd/mxcli/docker/runtime.go

@@ -15,6 +15,25 @@ import (
 	"time"
 )
 
+// ContainerCLI returns the container runtime binary ("docker" or "podman").
+// Resolution order:
+//  1. MXCLI_CONTAINER_CLI env var (explicit override)
+//  2. "docker" if available on PATH
+//  3. "podman" if available on PATH
+//  4. "docker" as fallback (will fail with a clear error at exec time)
+func ContainerCLI() string {
+	if cli := os.Getenv("MXCLI_CONTAINER_CLI"); cli != "" {
+		return cli
+	}
+	if _, err := exec.LookPath("docker"); err == nil {
+		return "docker"
+	}
+	if _, err := exec.LookPath("podman"); err == nil {
+		return "podman"
+	}
+	return "docker"
+}
+
 // RuntimeOptions configures docker runtime commands.
 type RuntimeOptions struct {
 	// ProjectPath is the path to the .mpr file.
@@ -85,7 +104,7 @@ func WaitForReady(opts RuntimeOptions, timeout time.Duration) error {
 	ctx, cancel := context.WithTimeout(context.Background(), timeout)
 	defer cancel()
 
-	cmd := exec.CommandContext(ctx, "docker", "compose", "logs", "--follow", "--no-log-prefix", "--since", "1s", "mendix")
+	cmd := exec.CommandContext(ctx, ContainerCLI(), "compose", "logs", "--follow", "--no-log-prefix", "--since", "1s", "mendix")
 	cmd.Dir = dockerDir
 
 	stdout, err := cmd.StdoutPipe()
@@ -205,7 +224,7 @@ func Status(opts RuntimeOptions) error {
 	}
 
 	// Get JSON output from docker compose ps
-	cmd := exec.Command("docker", "compose", "ps", "--format", "json")
+	cmd := exec.Command(ContainerCLI(), "compose", "ps", "--format", "json")
 	cmd.Dir = dockerDir
 
 	output, err := cmd.Output()
@@ -261,7 +280,7 @@ func Shell(opts RuntimeOptions, execCmd string) error {
 		args = []string{"exec", "-it", "mendix", "sh"}
 	}
 
-	cmd := exec.Command("docker", append([]string{"compose"}, args...)...)
+	cmd := exec.Command(ContainerCLI(), append([]string{"compose"}, args...)...)
 	cmd.Dir = dockerDir
 	cmd.Stdin = os.Stdin
 	cmd.Stdout = opts.Stdout
@@ -278,7 +297,7 @@ func Shell(opts RuntimeOptions, execCmd string) error {
 
 // runCompose executes a docker compose command in the given directory.
 func runCompose(dockerDir string, opts RuntimeOptions, args ...string) error {
-	cmd := exec.Command("docker", append([]string{"compose"}, args...)...)
+	cmd := exec.Command(ContainerCLI(), append([]string{"compose"}, args...)...)
 	cmd.Dir = dockerDir
 	cmd.Stdout = opts.Stdout
 	if cmd.Stdout == nil {

cmd/mxcli/init.go

@@ -17,9 +17,10 @@ import (
 )
 
 var (
-	initTools     []string
-	initAllTools  bool
-	initListTools bool
+	initTools            []string
+	initAllTools         bool
+	initListTools        bool
+	initContainerRuntime string
 )
 
 var initCmd = &cobra.Command{
@@ -57,6 +58,10 @@ Supported Tools:
   - vibe        Mistral Vibe CLI agent with skills
 
 All tools receive universal documentation in AGENTS.md and .ai-context/
+
+Container Runtime:
+  --container-runtime docker   Use Docker-in-Docker (default)
+  --container-runtime podman   Use Podman-in-Podman
 `,
 	Args: cobra.MaximumNArgs(1),
 	Run: func(cmd *cobra.Command, args []string) {
@@ -445,7 +450,7 @@ All tools receive universal documentation in AGENTS.md and .ai-context/
 		if err := os.MkdirAll(devcontainerDir, 0755); err != nil {
 			fmt.Fprintf(os.Stderr, "Error creating .devcontainer directory: %v\n", err)
 		} else {
-			dcJSON := generateDevcontainerJSON(projectName, mprFile)
+			dcJSON := generateDevcontainerJSON(projectName, mprFile, initContainerRuntime)
 			if err := os.WriteFile(devcontainerJSON, []byte(dcJSON), 0644); err != nil {
 				fmt.Fprintf(os.Stderr, "  Error writing devcontainer.json: %v\n", err)
 			}
@@ -1252,4 +1257,5 @@ func init() {
 	initCmd.Flags().StringSliceVar(&initTools, "tool", []string{}, "AI tool(s) to configure (claude, opencode, cursor, continue, windsurf, aider)")
 	initCmd.Flags().BoolVar(&initAllTools, "all-tools", false, "Initialize for all supported AI tools")
 	initCmd.Flags().BoolVar(&initListTools, "list-tools", false, "List supported AI tools and exit")
+	initCmd.Flags().StringVar(&initContainerRuntime, "container-runtime", "docker", "Container runtime for devcontainer (docker or podman)")
 }

cmd/mxcli/testrunner/runner.go

@@ -13,6 +13,8 @@ import (
 	"path/filepath"
 	"strings"
 	"time"
+
+	"github.com/mendixlabs/mxcli/cmd/mxcli/docker"
 )
 
 // RunOptions configures the test runner.
@@ -310,7 +312,7 @@ func captureRuntimeLogs(dockerDir string, timeout time.Duration, w io.Writer, ve
 	ctx, cancel := context.WithTimeout(context.Background(), timeout)
 	defer cancel()
 
-	cmd := exec.CommandContext(ctx, "docker", "compose", "logs", "--follow", "--no-log-prefix", "--since", "1s", "mendix")
+	cmd := exec.CommandContext(ctx, docker.ContainerCLI(), "compose", "logs", "--follow", "--no-log-prefix", "--since", "1s", "mendix")
 	cmd.Dir = dockerDir
 
 	stdout, err := cmd.StdoutPipe()
@@ -442,7 +444,7 @@ func findMxcli() (string, error) {
 
 // runCompose executes a docker compose command in the given directory.
 func runCompose(dockerDir string, args ...string) error {
-	cmd := exec.Command("docker", append([]string{"compose"}, args...)...)
+	cmd := exec.Command(docker.ContainerCLI(), append([]string{"compose"}, args...)...)
 	cmd.Dir = dockerDir
 	cmd.Stdout = os.Stdout
 	cmd.Stderr = os.Stderr

cmd/mxcli/tool_templates.go

@@ -270,22 +270,30 @@ recognize:
 `, projectName, mprFile, mprFile, mprFile)
 }
 
-func generateDevcontainerJSON(projectName, mprPath string) string {
+func generateDevcontainerJSON(projectName, mprPath, containerRuntime string) string {
+	feature := `"ghcr.io/devcontainers/features/docker-in-docker:2": {}`
+	containerEnv := `"PLAYWRIGHT_CLI_SESSION": "mendix-app"`
+	if containerRuntime == "podman" {
+		feature = `"ghcr.io/devcontainers/features/podman-in-podman:1": {}`
+		containerEnv = `"PLAYWRIGHT_CLI_SESSION": "mendix-app",
+    "MXCLI_CONTAINER_CLI": "podman"`
+	}
+
 	return fmt.Sprintf(`{
   "name": "%s",
   "build": {
     "dockerfile": "Dockerfile"
   },
   "features": {
-    "ghcr.io/devcontainers/features/docker-in-docker:2": {}
+    %s
   },
   "forwardPorts": [8080, 8090, 5432],
   "portsAttributes": {
     "8080-8099": { "onAutoForward": "silent" },
     "5432-5499": { "onAutoForward": "silent" }
   },
   "containerEnv": {
-    "PLAYWRIGHT_CLI_SESSION": "mendix-app"
+    %s
   },
   "postCreateCommand": "curl -fsSL https://claude.ai/install.sh | bash && if [ -f ./mxcli ] && ! file ./mxcli | grep -q Linux; then echo '⚠ ./mxcli is not a Linux binary. Replace it with the linux-amd64 or linux-arm64 build.'; fi",
   "customizations": {
@@ -300,7 +308,7 @@ func generateDevcontainerJSON(projectName, mprPath string) string {
   },
   "remoteUser": "vscode"
 }
-`, projectName)
+`, projectName, feature, containerEnv)
 }
 
 func generateDockerfile(projectName, mprPath string) string {

docs-site/src/tools/devcontainer.md

@@ -57,9 +57,11 @@ mxcli init -p app.mpr
 # - VS Code MDL extension (auto-installed)
 ```
 
-## Docker-in-Docker
+## Container Runtime (Docker or Podman)
 
-For `mxcli docker build`, `mxcli docker run`, and `mxcli test` (which require Docker), the dev container must have Docker-in-Docker support enabled. This is typically configured in `devcontainer.json`:
+For `mxcli docker build`, `mxcli docker run`, and `mxcli test` (which require a container runtime), the dev container must have Docker-in-Docker or Podman-in-Podman support enabled.
+
+### Docker-in-Docker (default)
 
 ```json
 {
@@ -69,6 +71,23 @@ For `mxcli docker build`, `mxcli docker run`, and `mxcli test` (which require Do
 }
 ```
 
+### Podman-in-Podman
+
+For organizations that cannot use Docker Desktop due to licensing:
+
+```json
+{
+  "features": {
+    "ghcr.io/devcontainers/features/podman-in-podman:1": {}
+  },
+  "containerEnv": {
+    "MXCLI_CONTAINER_CLI": "podman"
+  }
+}
+```
+
+When running `mxcli init`, use `--container-runtime podman` to generate this configuration automatically. Requires Podman 4.7+ (ships `podman compose` with Docker Compose V2 compatibility).
+
 ## Typical Dev Container Workflow
 
 1. Open the project in VS Code

docs-site/src/tools/docker-run.md

@@ -17,7 +17,7 @@ mxcli docker run -p app.mpr
 
 ## Prerequisites
 
-- Docker must be installed and running
+- Docker (or Podman 4.7+) must be installed and running
 - The project must be buildable (no errors in `mxcli docker check`)
 - A PostgreSQL database must be available (Docker can provide one)