Bring up a lab core

Bring up the Docker lab — four required network functions plus optional NSSF and SMSF on a single bridge — then verify them and tear the lab down.

The dflux TinyCore lab runs the whole core as containers on one Docker bridge. It is the simplest way to get a working core in front of you, and it is the place NGAP (the gNB-facing N2 interface over SCTP) runs when the host has no kernel SCTP — notably macOS. This tutorial gets the lab up, shows you how to confirm the functions are healthy, and tears everything down again. For what each function does, see Architecture.

What you need

Docker (with the Compose plugin) and the shipped Linux NF binaries (see Installation). The lab packages those binaries into a small Alpine image tagged d3x-core:lab — there is no registry pull.

Compose uses short names; the host does not

Inside the lab image the entrypoint expects the short process names, so deploy/lab/docker-compose.yml starts services with command: ["nrf", "-debug", "-port", "8080", …] (and the same for dpf, upf, dmf, nssf, smsf). Those short names are not the commands you type on a host PATH — native invocations use d3x-core-nrf (or d3x core nrf). Compose service names ( nrf, dmf, …) are also the DNS names on the lab bridge.

1. The topology

Everything lives on the 10.55.0.0/24 bridge. Inside that network, containers reach each other by their Compose service name, so the addresses below are mostly there to make the wiring legible. The shipped compose file starts all six NFs — the four required functions plus optional NSSF and SMSF:

text

Who talks to whom: DPF, NSSF, SMSF, and DMF register with the NRF and use it for discovery. DMF drives the UPF over PFCP (N4) to program packet forwarding, and calls the DPF for authentication and subscriber data. A gNB (real or simulated) connects to DMF on :38412 over SCTP — that is the N2 interface you will exercise in Register a UE and open a session.

The default datapath is a stub

In the lab the UPF runs with -datapath stub: PFCP works end to end, but the forwarder only records calls — it does not move real packets. That keeps the lab privilege-free. To actually forward user-plane traffic, see Forward user-plane traffic.

2. Build the lab image

From the lab bundle directory, produce the d3x-core:lab image that contains the six Linux NF binaries (NRF, DPF, UPF, DMF, NSSF, SMSF). Skip this step if that image is already loaded:

Bash

Architecture

The lab image uses Linux binaries matching the host architecture (Apple Silicon → arm64, x86 → amd64). Make sure the release archive you installed targets the same architecture as the host running the lab.

3. Bring the core up

Bash

Compose starts the six containers in dependency order. The NRF has a health check; DPF, NSSF, SMSF, and DMF wait for it. DMF also waits for DPF, UPF, NSSF, and SMSF. Default container names are tinycore-nrf, tinycore-dpf, tinycore-upf, tinycore-nssf, tinycore-smsf, and tinycore-dmf (the LAB_PREFIX stem; older screenshots may show ftc-*). List them:

Bash

text

The COMMAND column shows the short names because that is what the image entrypoint runs — not d3x-core-nrf.

4. Verify the functions

The Compose file maps no ports to the host — the NFs are reachable only on the 10.55.0.0/24 bridge. So check health from inside the network with docker compose exec. Every NF answers 200 OK on /health once it is listening:

Bash

The NRF additionally has a Compose health check (the wget --spider on /health reported as (healthy) above), which is what gates the other NFs. To confirm the functions are actually wired together, watch the logs — DPF and DMF register with the NRF on boot, and DMF opens its N2/SCTP listener:

Bash

UPF metrics

The UPF also serves Prometheus metrics at :9095/metrics. With the lab freshly up and no sessions yet, upf_sessions_active and upf_associations_active read zero — handy as a baseline before the next tutorials.

5. Tear it down

Stop and remove the containers and the bridge network. Because the stores are in-memory, there is nothing to persist; -v also drops named volumes (including the UPF recovery volume) for a clean slate:

Bash

Where to go next

With the core up you can drive a simulated gNB through it. Register a UE and open a session walks through NGSetup, registration, 5G-AKA, and a PDU session. To make the UPF forward real packets, see Forward user-plane traffic.