# How to Customize the Base Ubuntu Version (e.g., noble, focal) in LabNow AI Builds

> Easily customize the Ubuntu base image for LabNow AI builds. Override the BASE_IMG argument to use your preferred Ubuntu version like noble or focal for tailored Docker environments.

- Repository: [LabNow.ai/lab-foundation](https://github.com/labnow-ai/lab-foundation)
- Tags: how-to-guide
- Published: 2026-03-05

---

**To customize the Ubuntu base version in LabNow AI builds, override the `BASE_IMG` build argument at build time, which defaults to `ubuntu:noble` in the `docker_atom/Dockerfile`.**

The LabNow AI foundation repository (labnow-ai/lab-foundation) provides containerized environments built on Ubuntu Linux. When you need to customize the base Ubuntu version—whether switching from noble to focal, jammy, or another LTS release—the project exposes a configurable build argument that controls the entire image stack without requiring permanent Dockerfile modifications.

## Understanding the Base Image Configuration

The root of the image hierarchy is defined in `docker_atom/Dockerfile`, where the base Ubuntu version is parameterized through the `BASE_IMG` build argument. According to the source code, this argument defaults to the latest LTS release:

```dockerfile

# latest # default value: Latest LTS version of Ubuntu (https://hub.docker.com/_/ubuntu)

ARG BASE_IMG="ubuntu:noble"
FROM ${BASE_IMG}

```

This design pattern allows the entire LabNow AI stack to inherit from a single, configurable source image.

## Local Build Customization

For local development or testing, you can override the default noble base by passing a specific Ubuntu tag during the Docker build process.

### Overriding BASE_IMG with Docker Build

Use the `--build-arg` flag to inject your preferred Ubuntu version without editing source files:

```bash

# Switch to Ubuntu focal for local testing

docker build \
    --build-arg BASE_IMG=ubuntu:focal \
    -t labnow/atom:focal-custom \
    ./docker_atom

```

## CI/CD and Automated Builds

The GitHub Actions workflow at [`.github/workflows/build-docker.yml`](https://github.com/labnow-ai/lab-foundation/blob/main/.github/workflows/build-docker.yml) supports dynamic base image selection through workflow inputs, enabling automated builds across different Ubuntu versions.

### Configuring GitHub Actions Workflow Dispatch

The workflow accepts a `base_image` input parameter that forwards to the `BASE_IMG` build argument:

```yaml
on:
  workflow_dispatch:
    inputs:
      base_image:
        description: 'Ubuntu base image (e.g. ubuntu:focal)'
        default: 'ubuntu:noble'
        required: false

```

When executed, the workflow passes this value to the Docker build command:

```bash
docker build \
  --build-arg BASE_IMG=${{ inputs.base_image || 'ubuntu:noble' }} \
  -t ${{ env.IMAGE_NAME }} .

```

This configuration supports matrix builds and compatibility testing across multiple Ubuntu LTS releases.

## Propagation Across the Image Stack

The `docker_atom` image serves as the parent for downstream images including `docker_core` and `docker_base`. These child images reference the base through the pattern `FROM ${BASE_NAMESPACE:+$BASE_NAMESPACE/}${BASE_IMG}`, ensuring that modifying the `BASE_IMG` argument in the parent automatically propagates Ubuntu version changes throughout the entire LabNow AI container hierarchy.

## Summary

- The `BASE_IMG` build argument in `docker_atom/Dockerfile` controls the Ubuntu base version, defaulting to `ubuntu:noble`.
- Override locally using `docker build --build-arg BASE_IMG=ubuntu:focal` for immediate testing without code changes.
- The GitHub Actions workflow at [`.github/workflows/build-docker.yml`](https://github.com/labnow-ai/lab-foundation/blob/main/.github/workflows/build-docker.yml) supports version selection via `workflow_dispatch` inputs.
- Child images inherit the base configuration automatically, maintaining consistency across the labnow-ai/lab-foundation stack.

## Frequently Asked Questions

### What is the default Ubuntu version in LabNow AI builds?

The default Ubuntu base version is `ubuntu:noble` (24.04 LTS), defined as the default value for the `BASE_IMG` argument in `docker_atom/Dockerfile`. You can verify this on lines 3-5 of the Dockerfile where `ARG BASE_IMG="ubuntu:noble"` is declared.

### Can I use any Ubuntu tag with the BASE_IMG argument?

Yes, any valid Ubuntu Docker Hub tag will work, including specific point releases like `ubuntu:22.04` or `ubuntu:jammy`. The build argument accepts any string that resolves to a valid base image reference, allowing you to pin to specific LTS versions or use rolling tags.

### Do I need to modify multiple Dockerfiles to change the base version?

No, you only need to override the `BASE_IMG` argument when building the `docker_atom` image. Downstream images in `docker_core`, `docker_base`, and other directories automatically inherit this base through the `${BASE_IMG}` reference pattern, ensuring single-point configuration for the entire stack.

### How do I permanently change the default Ubuntu version?

To permanently change the default, edit line 4 of `docker_atom/Dockerfile` to modify the `ARG BASE_IMG` default value from `"ubuntu:noble"` to your preferred tag (e.g., `"ubuntu:focal"`), then commit and push the change. All subsequent builds will use the new default unless explicitly overridden at build time.