Skip to content

Docs: Fix CLI overriding Dockerfile BEAM_DOTNET_VERSION with hardcoded alpine tag #47

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
cdhanna wants to merge 2 commits into from
Closed

Docs: Fix CLI overriding Dockerfile BEAM_DOTNET_VERSION with hardcoded alpine tag #47

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7465a66
docs: update for source PR #4539
cdhanna Mar 19, 2026
adf07fd
docs: update for source PR #4539
cdhanna Mar 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
140 changes: 120 additions & 20 deletions docs/cli/commands/cli-command-reference/deployment/plan.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,18 +1,120 @@


```shell
beam deployment plan [options]
```

## About
Plan a deployment for later release



## Options

|Name|Type|Description|
|-|-|-|
```

## About
Plan a deployment for later release

When planning a deployment, the CLI builds Docker images for your services and prepares them for deployment. This process fixes a critical deployment failure scenario where users previously couldn't use non-Alpine base images at all. The build process now automatically configures the appropriate Docker base image based on your service configuration, making Docker overrides work as originally intended.

## Docker base image configuration

During the deployment planning process, the CLI constructs Docker images using base image tags determined by your service's MSBuild properties. This change fixes the previous behavior where the CLI hardcoded Alpine base images regardless of user configuration, causing deployment failures when services required non-Alpine environments.

### Why users care about this change

Previously, the CLI always passed `--build-arg BEAM_DOTNET_VERSION=X.0-alpine` to `docker buildx build`, completely overriding any `ARG BEAM_DOTNET_VERSION` declarations in your Dockerfile. This made it impossible to use Ubuntu-based images or other variants, causing deployment failures when services required packages or tools not available in Alpine Linux.

Error examples that previously occurred even when users tried to override the Dockerfile:
```
/bin/sh: apt-get: not found
Unable to locate package build-essential
rustc: command not found
node: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.XX' not found
```

These errors happened because Alpine uses different package managers (`apk` instead of `apt-get`) and a different C library (musl instead of glibc). The CLI change now makes Dockerfile overrides work as intended.

### ContainerFamily property

The `ContainerFamily` MSBuild property in your service's `.csproj` file controls which Docker base image variant to use:

- **`alpine`** (default): Uses Alpine Linux base images (smaller, security-focused)
- **`noble`**: Uses Ubuntu Noble base images (more packages available, better for complex dependencies)

To configure the container family, add this property to your service's `.csproj` file:

```xml
<PropertyGroup>
<TargetFramework>net8.0</TargetFramework>
<ContainerFamily>noble</ContainerFamily>
</PropertyGroup>
```

### When to use noble instead of alpine

Choose the `noble` container family when your service needs:

- **System packages not available in Alpine**: Many development tools and libraries are only packaged for Ubuntu/Debian
- **glibc compatibility**: Some applications require glibc instead of Alpine's musl libc
- **Complex build dependencies**: Ubuntu's extensive package ecosystem makes it easier to install build tools like Rust, specific compilers, or native libraries
- **Third-party tools during container build**: Tools that expect standard Linux distributions

**Example scenario**: A service that installs Rust during the Docker build would fail with Alpine because `apt-get` commands don't work. The error would look like:
```
/bin/sh: apt-get: not found
```

Switching to `noble` resolves this because Ubuntu Noble provides the `apt-get` package manager.

### Base image tag construction

The CLI automatically constructs the `BEAM_DOTNET_VERSION` Docker build argument by combining:

1. The .NET version extracted from your `TargetFramework` property
2. The `ContainerFamily` value (defaulting to `alpine` if unspecified)

Examples:
- `net8.0` + `alpine` → `8.0-alpine`
- `net10.0` + `noble` → `10.0-noble`
- `net8.0` + (unspecified) → `8.0-alpine`

The version extraction works generically from the Target Framework Moniker (`net10.0` → `10.0`), making it forward-compatible with future .NET versions without requiring hardcoded version lists.

This ensures your Dockerfile receives the correct base image tag via the `BEAM_DOTNET_VERSION` build argument, allowing you to write Dockerfiles that use non-Alpine base images when needed.

### Compatibility with existing setups

**Previous BEAM_DOTNET_VERSION overrides**: If you were previously overriding `BEAM_DOTNET_VERSION` in your Dockerfile, this change now makes that override work as originally intended. Before, the CLI would always pass `--build-arg BEAM_DOTNET_VERSION=X.0-alpine` regardless of your Dockerfile's default value, overriding your customization. Now, the CLI respects your `ContainerFamily` setting and constructs the appropriate tag.

**Migration requirements**: When switching container families:

- **No automatic redeployment**: Services deployed with alpine will continue running alpine until you redeploy them
- **Explicit redeployment needed**: Run `beam deployment plan` followed by `beam deployment release` to deploy with the new base image
- **Dockerfile compatibility**: Your existing Dockerfiles work without modification—the CLI handles base image selection automatically

### Performance and resource implications

| Aspect | Alpine | Noble |
|--------|--------|--------|
| **Image size** | ~80MB smaller | ~240MB larger |
| **Build time** | Faster (fewer layers) | Slower (more system packages) |
| **Security** | Smaller attack surface | Larger attack surface |
| **Package availability** | Limited Alpine packages | Full Ubuntu package ecosystem |
| **glibc compatibility** | Uses musl (compatibility issues) | Standard glibc (broad compatibility) |
| **Development tools** | Minimal, requires apk add | Rich development environment |
| **Resource usage in Beamable Cloud** | Lower memory footprint | Higher memory footprint |
| **Deployment times** | Faster image pulls | Slower image pulls due to size |

The 240MB size difference affects deployment times in the Beamable Cloud environment. Larger images take longer to pull and start, but the impact varies based on your realm's region and current load. Choose Alpine for production services with minimal dependencies. Choose Noble for services requiring extensive build tools, third-party packages, or glibc compatibility.

### Validation behavior

The CLI validates `ContainerFamily` values against supported options (`alpine`, `noble`). If you specify an invalid value:

- **No error is shown**: The CLI silently falls back to `alpine` as the default
- **Build continues normally**: Your deployment will proceed using Alpine Linux base images
- **Log indication**: Check build logs for the actual `BEAM_DOTNET_VERSION` build argument passed to Docker

Users should get a warning about this fallback behavior, but currently the CLI handles validation silently. To verify your container family selection is working, examine the Docker build output for lines like:
```
--build-arg BEAM_DOTNET_VERSION=8.0-noble
```

## 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|
Expand Down Expand Up @@ -49,10 +151,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)
75 changes: 55 additions & 20 deletions docs/cli/commands/cli-command-reference/services/build.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,18 +1,55 @@


```shell
beam services build [options]
```

## About
[REMOVED] Build a set of services into docker images



## Options

|Name|Type|Description|
|-|-|-|
```

## About
[REMOVED] Build a set of services into docker images

**Note**: This command has been deprecated and removed from active CLI usage. For building services as part of deployment, use `beam deployment plan` instead, which provides the same Docker image building functionality with enhanced deployment planning capabilities.

## Docker base image configuration

When building services with this command (when it was active), the CLI automatically determined the appropriate Docker base image tag based on your service's configuration. The base image tag is constructed from:

1. **Target framework**: Extracted from the `TargetFramework` property in your service's `.csproj` file
2. **Container family**: Read from the `ContainerFamily` MSBuild property in your service's `.csproj` file

### ContainerFamily property

The `ContainerFamily` property controls which Docker base image variant to use:

- **`alpine`** (default): Uses Alpine Linux base images (e.g., `mcr.microsoft.com/dotnet/runtime:8.0-alpine`)
- **`noble`**: Uses Ubuntu Noble base images (e.g., `mcr.microsoft.com/dotnet/runtime:8.0-noble`)

To specify a container family, add this property to your service's `.csproj` file:

```xml
<PropertyGroup>
<TargetFramework>net8.0</TargetFramework>
<ContainerFamily>noble</ContainerFamily>
</PropertyGroup>
```

If `ContainerFamily` is not specified or contains an unrecognized value, it defaults to `alpine`.

### Base image tag construction

The CLI constructs the `BEAM_DOTNET_VERSION` build argument by combining the .NET version from your `TargetFramework` with the `ContainerFamily`:

- `net8.0` + `alpine` → `8.0-alpine`
- `net10.0` + `noble` → `10.0-noble`
- `net8.0` + (unspecified) → `8.0-alpine`

This build argument is passed to `docker buildx build` as `--build-arg BEAM_DOTNET_VERSION=<version>-<family>`, allowing your Dockerfile to use the appropriate base image.

### Modern alternative

Since this command is removed, use `beam deployment plan` for building services. The deployment planning process includes the same Docker image building logic with the ContainerFamily property support, plus additional deployment preparation features.

## Options

|Name|Type|Description|
|-|-|-|
|--ids|Set[String]|The list of services to include, defaults to all local services (separated by whitespace). To use NO services, use the --exact-ids flag|
|--exact-ids|Boolean|By default, a blank --ids option maps to ALL available ids. When the --exact-ids flag is given, a blank --ids option maps to NO ids|
|--without-group|Set[String]|A set of BeamServiceGroup tags that will exclude the associated services. Exclusion takes precedence over inclusion|
Expand Down Expand Up @@ -46,10 +83,8 @@ beam services build [options]
|--dotnet-path|String|a custom location for dotnet|
|--version|Boolean|Show version information|
|--help|Boolean|Show help and usage information|



### Parent Command
[services](./services.md)





### Parent Command
[services](./services.md)