Docs: Fix CLI overriding Dockerfile BEAM_DOTNET_VERSION with hardcoded alpine tag

docs/cli/commands/cli-command-reference/deployment/plan.md

@@ -1,18 +1,80 @@
-
-
 ```shell
 beam deployment plan [options]
-```
-
-## About
-Plan a deployment for later release
-
-
-
-## Options
-
-|Name|Type|Description|
-|-|-|-|
+```
+
+## About
+Plan a deployment for later release
+
+## Container base image configuration
+
+The CLI automatically determines the Docker base image tag for your microservices by reading MSBuild properties from each service's `.csproj` file during the build phase of deployment:
+
+- **`TargetFramework`**: Extracts the .NET version (e.g., `net8.0` becomes `8.0`)
+- **`ContainerFamily`**: Specifies the base image family (defaults to `alpine`)
+
+### Why this matters
+
+Services requiring Ubuntu-specific packages (like `apt-get install git`, `curl`, or system libraries available through `apt`) would fail during deployment when using Alpine Linux base images. Alpine uses `apk` as its package manager and has a different filesystem structure. This configuration resolves compatibility issues by allowing services to use Ubuntu Noble base images that support standard Ubuntu packages and tooling.
+
+### Supported container families
+
+| Family | Description | Package manager | Use case |
+|--------|-------------|----------------|----------|
+| `alpine` | Alpine Linux-based images (default) | `apk` | Smaller image size, minimal footprint |
+| `noble` | Ubuntu Noble-based images | `apt-get` | Ubuntu packages, broader compatibility, system libraries |
+
+### Configuration
+
+Add to your service's `.csproj`:
+
+```xml
+<PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <ContainerFamily>noble</ContainerFamily>
+</PropertyGroup>
+```
+
+This generates the Docker build argument `--build-arg BEAM_DOTNET_VERSION=8.0-noble`, using the base image `mcr.microsoft.com/dotnet/runtime:8.0-noble`.
+
+### Deployment failure scenarios
+
+Without setting `ContainerFamily` to `noble`, services that use Ubuntu packages will fail during the Docker build phase with errors like:
+
+```
+/bin/sh: apt-get: not found
+```
+
+This occurs because Alpine Linux doesn't include `apt-get` - it uses `apk` instead. The deployment will stop at the Docker build step and never reach the running container phase.
+
+### Migration from hardcoded base images
+
+Before this fix, users had to work around the CLI's hardcoded Alpine tag behavior by manually editing their Dockerfiles to specify exact base images (e.g., `FROM mcr.microsoft.com/dotnet/runtime:8.0-noble`). This prevented the CLI from automatically managing .NET version updates and created maintenance overhead.
+
+If you previously worked around this limitation:
+
+1. Set `<ContainerFamily>noble</ContainerFamily>` in your `.csproj`
+2. Change your Dockerfile back to `FROM mcr.microsoft.com/dotnet/runtime:${BEAM_DOTNET_VERSION}`
+3. The CLI will automatically pass the correct tag during deployment
+
+### Performance and security considerations
+
+- **Image size**: Alpine images are typically 5-10MB smaller than Ubuntu Noble images
+- **Security**: Alpine has a smaller attack surface due to fewer installed packages by default
+- **Compatibility**: Noble provides broader package availability and compatibility with Ubuntu-based tooling
+- **Build time**: Noble images may have slightly longer pull times due to larger base size
+
+Choose `alpine` for minimal production services with no special dependencies, and `noble` when you need Ubuntu packages or broader system library support.
+
+### Impact on existing services
+
+- **Existing deployed services**: No change. They continue running with their current base images.
+- **New deployments**: Only services that explicitly set `ContainerFamily` will use different base images.
+- **Default behavior**: Unchanged. Services without `ContainerFamily` still use Alpine images.
+
+## Options
+
+|Name|Type|Description|
+|-|-|-|
 |--comment|String|Associates this comment along with the published Manifest. You'll be able to read it via the Beamable Portal|
 |--service-comments|String[]|Any number of strings in the format BeamoId::Comment<br>Associates each comment to the given Beamo Id if it's among the published services. You'll be able to read it via the Beamable Portal|
 |--from-manifest|String|A manifest json file to use to create a plan|
@@ -49,10 +111,8 @@ Plan a deployment for later release
 |--dotnet-path|String|a custom location for dotnet|
 |--version|Boolean|Show version information|
 |--help|Boolean|Show help and usage information|
-
-
-
-### Parent Command
-[deployment](./deployment.md)
-
-
+
+
+
+### Parent Command
+[deployment](./deployment.md)

docs/cli/commands/cli-command-reference/project/new/service.md

@@ -1,23 +1,28 @@
-
-
 ```shell
 beam project new service <name> [options]
-```
-
-## About
-Create a new microservice project
-
-## Arguments 
-|Name|Type|Description|
-|-|-|-|
+```
+
+## About
+Create a new microservice project
+
+When creating a microservice, you can configure the Docker base image by setting MSBuild properties in the generated `.csproj`. The CLI reads these properties during deployment to determine the appropriate base image:
+
+- **`ContainerFamily`**: Choose between `alpine` (default) or `noble` base images
+- **`TargetFramework`**: Determines the .NET runtime version
+
+The CLI combines these to form the Docker base image tag. For example, `<ContainerFamily>noble</ContainerFamily>` with `<TargetFramework>net8.0</TargetFramework>` results in `mcr.microsoft.com/dotnet/runtime:8.0-noble`.
+
+## Arguments 
+|Name|Type|Description|
+|-|-|-|
 |name|ServiceName|Name of the new project|
-
-
-
-## Options
-
-|Name|Type|Description|
-|-|-|-|
+
+
+
+## Options
+
+|Name|Type|Description|
+|-|-|-|
 |--sln|String|Relative path to the .sln file to use for the new project. If the .sln file does not exist, it will be created. When no option is configured, if this command is executing inside a .beamable folder, then the first .sln found in .beamable/.. will be used. If no .sln is found, the .sln path will be <name>.sln. If no .beamable folder exists, then the <project>/<project>.sln will be used|
 |--service-directory|String|Relative path to directory where project should be created. Defaults to "SOLUTION_DIR/services"|
 |--link-to|Set[String]|The name of the storage to link this service to|
@@ -47,10 +52,8 @@ Create a new microservice project
 |--dotnet-path|String|a custom location for dotnet|
 |--version|Boolean|Show version information|
 |--help|Boolean|Show help and usage information|
-
-
-
-### Parent Command
-[project new](./new.md)
-
-
+
+
+
+### Parent Command
+[project new](./new.md)