Building Yocto directly on a host machine is fragile — dependency mismatches, missing packages, and environment drift can break a build that worked yesterday. A Docker‑based build environment solves this by giving you:

• A clean, reproducible OS
• A known‑good dependency set
• Zero host pollution
• Portability across machines
• Easy integration with CI (Jenkins, GitHub Actions, GitLab CI)

I am using a Ubuntu 24.04 server and to resolve conflicts I will use Docker. Here is a post I made how to install docker if you don’t have it installed it already.

We will use a Beagle Bone Black (BBB) as the hardware. Its easily available and relatively cheap and decently powerful. Its widely available as well.

1. Directory Layout

/<path to your folder>/yocto/
   ├── docker-compose.yml
   ├── downloads/
   ├── sstate-cache/
   └── workspace/
        ├── sources/
        └── build/

mkdir -p yocto/{downloads,sstate-cache,workspace}
cd yocto

2. docker-compose.yml (scarthgap‑ready)

Inside the yocto folder yocto/, lets create a file called “Dockerfile” no file extension is needed.

touch Dockerfile
nano Dockerfile

Inside the Dockerfile lets put all the dependencies and work with the latest Ubuntu available now. This is to create a custom Ubuntu docker with all the build dependencies.

FROM ubuntu:24.04

ENV DEBIAN_FRONTEND=noninteractive

RUN apt-get update && apt-get install -y \
    gawk wget git-core diffstat unzip texinfo gcc-multilib \
    build-essential chrpath socat cpio python3 python3-pip \
    python3-pexpect xz-utils debianutils iputils-ping \
    libsdl1.2-dev xterm locales sudo ccache lz4 zstd file \
    && locale-gen en_US.UTF-8 && apt install -y locales nano

RUN useradd -m yocto && echo "yocto ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers

USER yocto
WORKDIR /workspace

Once you have the content in the file close it by pressing Ctrl + X. Now we can create the custom image with the command below.

docker build -t yocto-bbb .

3. Run the Container With Proper Bind Mounts

Now you can start the docker container by using the command below:

docker run -it --privileged \
  -v $(pwd)/downloads:/downloads \
  -v $(pwd)/sstate-cache:/sstate-cache \
  -v $(pwd)/workspace:/workspace \
  yocto-bbb

Inside the container, you’ll be logged in as the yocto user.

Next time you can use the command below to go to the command terminal.

docker exec -it --privileged yocto-bbb bash

4. Clone Yocto (Scarthgap) and Initialize the Build Environment

Inside the container:

We will set the correct permission to the folders and clone poky scarthgap and initialize the build environment.

sudo chown -R yocto:yocto /workspace
cd /workspace/sources
git clone git://git.yoctoproject.org/poky -b scarthgap
cd poky
source oe-init-build-env ../build

This will create the 2 conf file we need to edit for our setup:

workspace/
└── build/
    ├── conf/local.conf
    └── conf/bblayers.conf

5. Configure Yocto for the BeagleBone Black

Edit conf/bblayers.conf and add the meta‑ti layer:

cd /workspace/sources
git clone https://git.yoctoproject.org/meta-ti -b scarthgap
nano build/conf/bblayers.conf

Add the below script to bblayers.conf:

Code
BBLAYERS += " \
  /workspace/sources/meta-ti \
"

6. Configure Caches and BBB Machine Settings

Edit nano build/conf/local.conf:

Update this Section

MACHINE = "beaglebone"

DL_DIR ?= "/downloads"
SSTATE_DIR ?= "/sstate-cache"

INHERIT += "ccache"
CCACHE_DIR = "/workspace/ccache"

Next lets create the cache directory

mkdir -p /workspace/ccache

7. Build a BBB Image

To build the image we need to run the commands below.

cd /workspace/sources/poky
source oe-init-build-env ../build
bitbake core-image-minimal

We can also build:

• core-image-base
• core-image-full-cmdline
• tisdk-default-image (if using TI SDK layers)

8. Output Artifacts

After the build completes, images will be located in:

workspace/build/tmp/deploy/images/beaglebone/

You will see:

• core-image-minimal-beaglebone.wic.xz
• u-boot-beaglebone.bin
• MLO
• zImage or Image
• DTBs

Flash the .wic.xz to an SD card:

xz -d core-image-minimal-beaglebone.wic.xz
sudo dd if=core-image-minimal-beaglebone.wic of=/dev/sdX bs=4M status=progress
sync

In Jenkins UI:

• Manage Jenkins → Nodes → New Node
• Name: yocto-agent
• Type: “Permanent Agent”
• Remote root dir: /workspace
• Launch method: “Launch agent via execution of command on the controller” or SSH (your choice)
• Label: yocto-bbb

If you use SSH, run an SSH server in the agent container; if you use JNLP, download the agent jar and run it inside the container.

6. Jenkinsfile for BBB + scarthgap

Create a Jenkinsfile in your Yocto platform repo (or a freestyle pipeline using this):

pipeline {
    agent { label 'yocto-bbb' }

    environment {
        YOCTO_TOP = "/workspace"
        BUILD_DIR = "${YOCTO_TOP}/build-bbb"
        MACHINE   = "beaglebone"
        TARGET    = "core-image-minimal"
    }

    stages {
        stage('Env info') {
            steps {
                sh 'uname -a'
                sh 'nproc'
            }
        }

        stage('Prepare build env') {
            steps {
                sh """
                    cd ${YOCTO_TOP}
                    source sources/poky/oe-init-build-env ${BUILD_DIR}
                    bitbake-layers show-layers
                """
            }
        }

        stage('Build image') {
            steps {
                sh """
                    cd ${YOCTO_TOP}
                    source sources/poky/oe-init-build-env ${BUILD_DIR}
                    bitbake ${TARGET}
                """
            }
        }

        stage('Archive artifacts') {
            steps {
                archiveArtifacts artifacts: "${BUILD_DIR}/tmp/deploy/images/${MACHINE}/*", fingerprint: true
            }
        }
    }
}

7. Where your BBB images will land

After a successful build:

/workspace/build-bbb/tmp/deploy/images/beaglebone/

You’ll see .wic, .tar.xz, u-boot, kernel, etc.—ready to flash.