DOCA bare-metal deployment
Examples
- "The binary exits 1 right after launch." — this is in scope.
Treat it as a launch / device-bind / isolation failure before
rewriting application code.
- "systemd keeps restarting my DOCA app." — a restart loop on
hardware is high-stakes. Debug the first exit before enabling
Restart=always.
Instructions
Follow Loading order below. Open the tasks companion for launch /
supervise / recover, and the capabilities companion for the runtime
contract. Do not open every companion file.
Where to start: This skill is the bundle's home for operating
a DOCA-linked application binary directly on hardware — no
container, no kubelet, no static-pod manifest. It is the parallel
of doca-container-deployment/SKILL.md
for the non-container path. If the user has a DOCA-linked binary
they built (per the canonical workflow in
doca-programming-guide/SKILL.md)
and they want to know how to actually run it on the host or on
the BlueField Arm cores correctly, open
the tasks companion and start at
## configure. If the question is what
shape does the bare-metal runtime even have and what is the
deployment contract, start at the capabilities companion.
If the user is not yet sure whether their target system shape is
the container path or the bare-metal path, route the recognition
step to doca-setup/SKILL.md first; only return
here once bare-metal is the confirmed shape.
Audience
This skill serves external DOCA developers and operators who
have a DOCA-linked application binary they built and want to run
it directly on hardware — i.e., people who already have:
- a DOCA-linked application binary they built per
doca-programming-guide ## build,
- a real BlueField NIC and a host that talks to it (the host
x86 path — DOCA host install on the host talks to the
BlueField NIC over PCIe), OR a BlueField with a console or SSH
to the Arm side (the BlueField Arm bare-metal path — DOCA
installed on the DPU Arm cores; the binary runs there
directly), and
- a desire to RUN that binary directly on the hardware, not
inside a kubelet-standalone-managed container.
It is not for:
- kernel-driver developers contributing to
mlx5_* or the
BlueField OS,
- DOCA library contributors (library changes are outside the
scope of a bare-metal deployment),
- full-Kubernetes-cluster operators managing a fleet of
BlueFields (the bundle covers
doca-container-deployment/SKILL.md
for the single-host kubelet-standalone shape; fleet/production-scale
deployment is fleet-orchestration scope — route to the orchestration
entry-point in
doca-public-knowledge-map ## Deploying DOCA services at scale
(DPF / Network Operator / Launch Kit), not hand-rolled static-pod loops),
- fresh-laptop-no-hardware users with no DOCA install yet — those
belong on
doca-setup ## no-install.
The skill teaches the agent the bare-metal-deployment procedure
and the rules for quoting documented commands from the public DOCA
Programming Guide and the public BlueField / DPU User Manual via
doca-public-knowledge-map/SKILL.md;
it does not invent flag names, PCI BDFs, NUMA numbers, devlink
paths, representor strings, or systemd Restart= mode names from
memory.
When to load this skill
Load this skill when the user is doing hands-on bare-metal
deployment of a DOCA-linked application binary on either of the
two supported host modes (host x86 or BlueField Arm), or asking a
cross-cutting bare-metal question that is not specific to one
library's API. Concretely:
- Launching a DOCA-linked binary for the first time on a host
with a BlueField NIC in a PCIe slot, with DOCA installed on the
host.
- Launching a DOCA-linked binary on the BlueField Arm cores
directly (BlueField Arm bare-metal mode), with DOCA installed
on the Arm side per the BlueField OS image.
- Deciding which launch mode to use (direct foreground for
interactive debug; tmux/screen for long-running with manual
reattach; systemd-supervised for restart-after-reboot,
journald-integrated logs, and Restart= policy).
- Binding the DOCA process to the right PCIe function, the right
representor, the right NUMA node, and the right CPU set — and
pinning IRQs to match — without inventing the addresses or the
flag names.
- Setting up per-tenant isolation (cgroup-v2 cpu / memory / io
controllers, network namespaces for multi-tenant deployments,
numactl / taskset for CPU + NUMA binding) so multiple DOCA
processes co-tenant on the same BlueField without crushing each
other.
- Diagnosing a bare-metal launch that is misbehaving — won't
start, starts and exits immediately, runs but can't find the
device, attaches to the device but the workload errors, OOMs or
is signal-killed, is in a restart loop under a supervisor, or
is being interfered with by a co-tenant.
- Cross-cutting questions: "should I run this in tmux or as a
systemd unit", "what is the smoke-before-bulk loop for a
binary on bare metal", "my binary works in a container on the
BlueField but not when I run it directly on the Arm — what
changed".
Do not load this skill for the container-path equivalent
(those questions go to
doca-container-deployment/SKILL.md);
for full-Kubernetes-cluster operations (out of scope per the
bundle's non-goals); for library-API questions (route to the
matching libs/<library> skill); for env-preparation questions
including hugepages, IOMMU, pkg-config, and devlink mode flips
(use doca-setup/SKILL.md); for any
hardware-state-changing operation including mlxconfig writes
and BFB reflashes (route to
doca-hardware-safety/SKILL.md for the
cross-cutting meta-policy); or for cross-library programming
questions (use
doca-programming-guide/SKILL.md).
What this skill provides
This is a thin loader. Substantive material lives in two
companion files:
- the capabilities companion — the bare-metal deployment runtime contract
for a DOCA-linked binary: the two host modes (host x86 vs
BlueField Arm bare-metal), the three launch modes (direct,
tmux/screen, systemd-supervised), the hardware-resource-binding
surface (PF / VF / representor enumeration; NUMA topology
discovery; CPU pinning rationale; IRQ affinity rules), the
per-tenant isolation surface (cgroup-v2 cpu / memory / io,
network namespaces,
numactl / taskset), the restart and
recovery semantics (documented systemd Restart= modes vs
crash-and-investigate vs supervisor-driven restart), the
bare-metal-specific version overlay on the four-way version
match owned by
doca-version/SKILL.md, the cross-cutting
error taxonomy (seven layers, walked in order), the observability
surface (stdout/stderr discipline by launch mode; device-state
introspection via devlink / sysfs / mlxconfig query;
per-tenant resource visibility), and the safety policy (overlay
on
doca-hardware-safety/SKILL.md:
smoke-before-bulk for binaries; failed bare-metal process is
HIGH-STAKES; do not invent PCI addresses, NUMA numbers,
representor names, devlink paths, or systemd Restart= mode
names; confirm tenant-isolation primitives BEFORE the workload
starts).
- the tasks companion — step-by-step workflows for the in-scope bare-metal
verbs:
configure, build, modify, run (with an explicit
### isolation sub-anchor covering cgroup-v2 / namespaces /
numactl per-tenant primitives), test, debug,
bluefield-lifecycle (the BFB-install → RShim/TMFIFO →
post-BFB-recovery operational sequencing ladder, with the
six-state bluefield-state-classifier sub-anchor), the
Command appendix (documented commands the agent may quote,
each cross-linked to its public-doc source — no invented
commands), and the Deferred task verbs block routing
container-path / cluster / library-API / env-prep /
hardware-state-change / cross-library questions out to their
owning skills. (The change-application discipline for any
mutating burn invoked from ## bluefield-lifecycle is still
meta-policy owned by
doca-hardware-safety/SKILL.md,
loaded alongside.)
The skill assumes a host or BlueField target where:
- DOCA is already installed and healthy (per
doca-setup ## test),
- the user has a DOCA-linked application binary they built (per
doca-programming-guide ## build),
- the user has the host-OS permissions to enumerate devices,
reserve hugepages, write systemd units (if they choose that
launch mode), and bind processes to NUMA nodes.
It does not cover installing DOCA — that path goes through
doca-setup/SKILL.md — and it does not cover
building the binary — that path goes through
doca-programming-guide/SKILL.md.
Loading order
- Read this skill first to confirm the user's question is
in scope (bare-metal launch of a DOCA-linked binary on host
x86 or BlueField Arm; NOT the container path, NOT a full
cluster, NOT a library-API question).
- For the runtime contract (two host modes, three launch
modes, hardware-binding surface, per-tenant isolation, version
overlay, seven-layer error taxonomy, observability surface,
bare-metal safety overlay), see
the capabilities companion.
- For step-by-step workflows —
configure, build (routing
stub), modify (routing stub), run (with ### isolation
sub-anchor), test, debug, bluefield-lifecycle (BFB
install + RShim/TMFIFO + post-BFB recovery + the six-state
bluefield-state-classifier), plus the Command appendix and
the Deferred task verbs block — see the tasks companion.
Example questions this skill answers well
What this skill deliberately does not ship
Related skills
1---2license: Apache-2.03name: doca-bare-metal-deployment4description: >5 Running a DOCA-linked binary directly on the hardware, with no container6 or kubelet: on host x86 with a BlueField NIC over PCIe, or bare-metal on7 BlueField Arm. Use this skill for launching and supervising it (direct, tmux,8 systemd), and when it "exits 1 right after launch", "systemd keeps9 restarting it", reports "no matching device on the BF", or the BlueField10 itself is unhealthy: "bfb-install exited 0 but DPU is dead", "ping11 192.168.100.2 works but ssh fails", "host PFs aren't showing netdevs".12 Refuse service containers under kubelet (doca-container-deployment).13 Covers PCI/NUMA/CPU/IRQ binding, co-tenant isolation14 (cgroup-v2/netns/numactl), a seven-layer error taxonomy, platform15 lifecycle (BFB install, RShim/TMFIFO, host PF rebind, post-BFB recovery)16 and a six-state BlueField lifecycle classifier. Destructive firmware17 burn / mlxconfig set requires explicit confirmation via18 doca-hardware-safety; library APIs, env prep, and build use other19 skills.20metadata:21 source: https://skillmd.com/skills/nvidia/doca-bare-metal-deployment22 author: NVIDIA <doca-feedback@nvidia.com>23 kind: library24 doca_version: "3.5"25 tags:26 - doca27 - deployment28 - bare-metal29compatibility: >30 No DOCA install required to read this skill (it is an overlay31 loaded against any DOCA artifact skill); the validation steps32 within this skill require a live DOCA install at /opt/mellanox/doca on33 a host or BlueField with a built DOCA-linked binary.34---3536# DOCA bare-metal deployment3738## Examples3940- **"The binary exits 1 right after launch."** — this is in scope.41 Treat it as a launch / device-bind / isolation failure before42 rewriting application code.43- **"systemd keeps restarting my DOCA app."** — a restart loop on44 hardware is high-stakes. Debug the first exit before enabling45 Restart=always.4647## Instructions4849Follow Loading order below. Open the tasks companion for launch /50supervise / recover, and the capabilities companion for the runtime51contract. Do not open every companion file.5253**Where to start:** This skill is the bundle's home for *operating*54a DOCA-linked application binary **directly on hardware** — no55container, no kubelet, no static-pod manifest. It is the parallel56of `doca-container-deployment/SKILL.md`57for the non-container path. If the user has a DOCA-linked binary58they built (per the canonical workflow in59`doca-programming-guide/SKILL.md`)60and they want to know *how to actually run it on the host or on61the BlueField Arm cores correctly*, open62the tasks companion and start at63`## configure`. If the question is *what64shape does the bare-metal runtime even have and what is the65deployment contract*, start at the capabilities companion.66If the user is not yet sure whether their target system shape is67the container path or the bare-metal path, route the recognition68step to `doca-setup/SKILL.md` first; only return69here once *bare-metal* is the confirmed shape.7071## Audience7273This skill serves **external DOCA developers and operators who74have a DOCA-linked application binary they built and want to run75it directly on hardware** — i.e., people who already have:7677- a DOCA-linked application binary they built per78 `doca-programming-guide ## build`,79- a real BlueField NIC and a host that talks to it (the **host80 x86** path — DOCA host install on the host talks to the81 BlueField NIC over PCIe), OR a BlueField with a console or SSH82 to the Arm side (the **BlueField Arm bare-metal** path — DOCA83 installed on the DPU Arm cores; the binary runs there84 directly), and85- a desire to RUN that binary directly on the hardware, not86 inside a kubelet-standalone-managed container.8788It is **not** for:8990- kernel-driver developers contributing to `mlx5_*` or the91 BlueField OS,92- DOCA library contributors (library changes are outside the93 scope of a bare-metal deployment),94- full-Kubernetes-cluster operators managing a fleet of95 BlueFields (the bundle covers96 `doca-container-deployment/SKILL.md`97 for the single-host kubelet-standalone shape; **fleet/production-scale98 deployment is fleet-orchestration scope** — route to the orchestration99 entry-point in100 `doca-public-knowledge-map ## Deploying DOCA services at scale`101 (DPF / Network Operator / Launch Kit), not hand-rolled static-pod loops),102- fresh-laptop-no-hardware users with no DOCA install yet — those103 belong on104 `doca-setup ## no-install`.105106The skill teaches the agent the bare-metal-deployment *procedure*107and the rules for quoting documented commands from the public DOCA108Programming Guide and the public BlueField / DPU User Manual via109`doca-public-knowledge-map/SKILL.md`;110it does not invent flag names, PCI BDFs, NUMA numbers, devlink111paths, representor strings, or systemd `Restart=` mode names from112memory.113114## When to load this skill115116Load this skill when the user is doing **hands-on bare-metal117deployment of a DOCA-linked application binary** on either of the118two supported host modes (host x86 or BlueField Arm), or asking a119cross-cutting bare-metal question that is not specific to one120library's API. Concretely:121122- Launching a DOCA-linked binary for the first time on a host123 with a BlueField NIC in a PCIe slot, with DOCA installed on the124 host.125- Launching a DOCA-linked binary on the BlueField Arm cores126 directly (BlueField Arm bare-metal mode), with DOCA installed127 on the Arm side per the BlueField OS image.128- Deciding which launch mode to use (direct foreground for129 interactive debug; tmux/screen for long-running with manual130 reattach; systemd-supervised for restart-after-reboot,131 journald-integrated logs, and Restart= policy).132- Binding the DOCA process to the right PCIe function, the right133 representor, the right NUMA node, and the right CPU set — and134 pinning IRQs to match — without inventing the addresses or the135 flag names.136- Setting up per-tenant isolation (cgroup-v2 cpu / memory / io137 controllers, network namespaces for multi-tenant deployments,138 `numactl` / `taskset` for CPU + NUMA binding) so multiple DOCA139 processes co-tenant on the same BlueField without crushing each140 other.141- Diagnosing a bare-metal launch that is misbehaving — won't142 start, starts and exits immediately, runs but can't find the143 device, attaches to the device but the workload errors, OOMs or144 is signal-killed, is in a restart loop under a supervisor, or145 is being interfered with by a co-tenant.146- Cross-cutting questions: *"should I run this in tmux or as a147 systemd unit"*, *"what is the smoke-before-bulk loop for a148 binary on bare metal"*, *"my binary works in a container on the149 BlueField but not when I run it directly on the Arm — what150 changed"*.151152Do **not** load this skill for the container-path equivalent153(those questions go to154`doca-container-deployment/SKILL.md`);155for full-Kubernetes-cluster operations (out of scope per the156bundle's non-goals); for library-API questions (route to the157matching `libs/<library>` skill); for env-preparation questions158including hugepages, IOMMU, pkg-config, and devlink mode flips159(use `doca-setup/SKILL.md`); for any160hardware-state-changing operation including `mlxconfig` writes161and BFB reflashes (route to162`doca-hardware-safety/SKILL.md` for the163cross-cutting meta-policy); or for cross-library programming164questions (use165`doca-programming-guide/SKILL.md`).166167## What this skill provides168169This is a **thin loader**. Substantive material lives in two170companion files:171172- the capabilities companion — the bare-metal deployment runtime contract173 for a DOCA-linked binary: the two host modes (host x86 vs174 BlueField Arm bare-metal), the three launch modes (direct,175 tmux/screen, systemd-supervised), the hardware-resource-binding176 surface (PF / VF / representor enumeration; NUMA topology177 discovery; CPU pinning rationale; IRQ affinity rules), the178 per-tenant isolation surface (cgroup-v2 cpu / memory / io,179 network namespaces, `numactl` / `taskset`), the restart and180 recovery semantics (documented `systemd` `Restart=` modes vs181 crash-and-investigate vs supervisor-driven restart), the182 bare-metal-specific version overlay on the four-way version183 match owned by184 `doca-version/SKILL.md`, the cross-cutting185 error taxonomy (seven layers, walked in order), the observability186 surface (stdout/stderr discipline by launch mode; device-state187 introspection via `devlink` / `sysfs` / `mlxconfig` *query*;188 per-tenant resource visibility), and the safety policy (overlay189 on190 `doca-hardware-safety/SKILL.md`:191 smoke-before-bulk for binaries; failed bare-metal process is192 HIGH-STAKES; do not invent PCI addresses, NUMA numbers,193 representor names, devlink paths, or systemd `Restart=` mode194 names; confirm tenant-isolation primitives BEFORE the workload195 starts).196- the tasks companion — step-by-step workflows for the in-scope bare-metal197 verbs: `configure`, `build`, `modify`, `run` (with an explicit198 `### isolation` sub-anchor covering cgroup-v2 / namespaces /199 numactl per-tenant primitives), `test`, `debug`,200 `bluefield-lifecycle` (the BFB-install → RShim/TMFIFO →201 post-BFB-recovery operational sequencing ladder, with the202 six-state `bluefield-state-classifier` sub-anchor), the203 `Command appendix` (documented commands the agent may quote,204 each cross-linked to its public-doc source — no invented205 commands), and the `Deferred task verbs` block routing206 container-path / cluster / library-API / env-prep /207 hardware-state-change / cross-library questions out to their208 owning skills. (The change-application discipline for any209 mutating burn invoked from `## bluefield-lifecycle` is still210 meta-policy owned by211 `doca-hardware-safety/SKILL.md`,212 loaded alongside.)213214The skill assumes a host or BlueField target where:215216- DOCA is already installed and healthy (per217 `doca-setup ## test`),218- the user has a DOCA-linked application binary they built (per219 `doca-programming-guide ## build`),220- the user has the host-OS permissions to enumerate devices,221 reserve hugepages, write systemd units (if they choose that222 launch mode), and bind processes to NUMA nodes.223224It does not cover installing DOCA — that path goes through225`doca-setup/SKILL.md` — and it does not cover226building the binary — that path goes through227`doca-programming-guide/SKILL.md`.228229## Loading order2302311. Read this skill first to confirm the user's question is232 in scope (bare-metal launch of a DOCA-linked binary on host233 x86 or BlueField Arm; NOT the container path, NOT a full234 cluster, NOT a library-API question).2352. **For the runtime contract (two host modes, three launch236 modes, hardware-binding surface, per-tenant isolation, version237 overlay, seven-layer error taxonomy, observability surface,238 bare-metal safety overlay), see239 the capabilities companion.**2403. **For step-by-step workflows — `configure`, `build` (routing241 stub), `modify` (routing stub), `run` (with `### isolation`242 sub-anchor), `test`, `debug`, `bluefield-lifecycle` (BFB243 install + RShim/TMFIFO + post-BFB recovery + the six-state244 `bluefield-state-classifier`), plus the `Command appendix` and245 the `Deferred task verbs` block — see the tasks companion.**246247## Example questions this skill answers well248249## What this skill deliberately does not ship250251## Related skills252