Pre-flight: suggest remoteBuild when Docker is missing instead of failing

[spboyer]

Problem

When Docker is not installed or not running, azd deploy/up fails with a dead-end error message that only suggests installing Docker. It does not mention remoteBuild: true — a built-in azure.yaml option that builds containers on Azure and removes the Docker requirement entirely.

Telemetry (rolling 28 days)

Error Code	Count	Users
tool.Docker.missing	2,936	784
tool.docker.failed	4,655	1,024

Current Error Message

required external tools are missing:
 - error checking for external tool Docker: neither docker nor podman is installed.
   Please install Docker: https://aka.ms/azure-dev/docker-install
   or Podman: https://aka.ms/azure-dev/podman-install

No mention of remoteBuild: true as an alternative.

Current Architecture

The tool check chain already detects Docker requirements per-service:

deploy.go → projectManager.EnsureServiceTargetTools()
  → containerHelper.RequiredExternalTools()
    → if remoteBuild: true → [] (no Docker needed!)
    → if remoteBuild: nil/false → [docker] (Docker required)
  → tools.EnsureInstalled(docker) → MissingToolErrors

Key insight: RequiredExternalTools() in pkg/project/container_helper.go:250-260 already skips Docker when remoteBuild: true. The user just does not know this option exists.

Services That Support remoteBuild

Target	Support	Notes
Container Apps	✅	Uses ACR build API
AKS	✅	Uses ACR build API
Function App (Flex)	✅	JS/TS/Python default true
App Service	❌	Local build only
Static Web App	❌	No containers

Proposal: Pre-flight Detection with Actionable Suggestion

When Docker is missing and services support remoteBuild, wrap the error with ErrorWithSuggestion before any other work starts in the chain. The user should see this immediately, not after minutes of provisioning.

Approach

Enhance EnsureServiceTargetTools() in pkg/project/project_manager.go to detect the Docker-missing + remoteBuild-capable scenario and return a richer error:

if toolErr, ok := errors.AsType[*tools.MissingToolErrors](err); ok {
    if slices.Contains(toolErr.ToolNames, "Docker") {
        // Check which services could use remoteBuild
        return &internal.ErrorWithSuggestion{
            Err: toolErr,
            Suggestion: "Your services can build on Azure instead of locally.\n" +
                "Add 'docker: { remoteBuild: true }' to each service in azure.yaml,\n" +
                "or install Docker: https://aka.ms/azure-dev/docker-install",
        }
    }
}

This centralizes the logic in ProjectManager rather than duplicating it in deploy.go, provision.go, and up paths.

Expected Impact

• 2,936 Docker.missing failures/28d get actionable guidance instead of a dead-end error
• 784 users learn about remoteBuild as a zero-install alternative
• Error is surfaced immediately before any provisioning/build work begins

Related Issues

• [Issue] when docker is missing, could azd up suggest to use remoteBuild: true ? #5715 — Original request to suggest remoteBuild (this supersedes it with a concrete implementation plan)
• Operations for a given service (e.g. restore) should only verify presence of dependency tools needed for that service #3533 — Per-service tool validation (good first issue, related but broader scope)
• Feature: Pre-flight auth validation for provision/deploy/up to prevent downstream failures #7234 / PR Add auth pre-flight validation for agents #7236 — Auth pre-flight validation (same pattern: catch before work starts)