Deploy and monitor the free5GC core network and the free-ran-ue gNB / UE simulator, and load-test a 5G core with the Throughput Tester.
fru-lab has two parts:
- fru-lab, the web console (Go backend + React frontend). It deploys free5GC, the gNB and one UE container per subscriber on the host's Docker daemon, manages subscribers through the free5GC webconsole, and shows logs and images.
- fru-tester, the Throughput Tester. It simulates gNBs and tens of thousands of UEs against any 5G core (N2 setup, registration, PDU sessions) and drives GTP-U traffic through it. fru-lab's "Load testing" pages talk to one or more fru-testers over their API.
| DevOpts | Version |
|---|---|
| OS | Ubuntu 25.04 |
| go | 1.26.2 |
| nodejs | v20.20.0 |
| yarn | 1.22.22 |
| Type | Command |
|---|---|
| Make all (backend, frontend, tester) | make |
| Backend | make backend |
| Frontend | make frontend |
| Tester | make tester |
| Run | make run |
| Run tester | make run-tester |
| Test | make test |
| Tidy | make tidy |
| Lint | make lint |
| Clean | make clean |
| Generate frontend openapi | make openapi |
| Generate frontend openapi for free5GC webconsole | make openapi-webconsole |
| Docker images (fru-lab and fru-tester) | make docker |
make run starts fru-lab with ./config.yaml on port 8888. make run-tester loads the sctp kernel module and starts fru-tester with ./tester.yaml under sudo (it needs root to add gNB IPs and open SCTP).
fru-tester is built with make tester and started with make run-tester. fru-lab finds it through backend.tester in config.yaml:
tester:
# fru-tester API (see tester.yaml). Leave url empty to disable the pages.
url: "http://127.0.0.1:9100"
apiToken: "frulab-tester"apiToken must match apiToken in tester.yaml. More testers can be added from the Testers page.
See the fru-lab guide (Chinese) for setting up testers, running tests and reading the results.
The compose file runs two containers: fru-lab and fru-tester. fru-lab deploys free5GC/gNB/UE by talking to the host's Docker daemon, so its container needs the host's Docker socket mounted in, on top of the usual config/db volumes. fru-tester runs on the host network.
-
Download the compose files
git clone https://github.com/free-ran-ue/fru-lab.git cd fru-lab/docker -
Check the config
Admin can modify system settings in
config.yaml(indocker/), e.g. the default login credential:username: "admin" password: "frulab"
For other settings, make sure the change is reflected in
docker-compose.yamltoo. In particular,deploy.workDirhas to stay the exact same path on the host and inside the container (see the comment on that volume indocker-compose.yaml) - fru-lab hands that path to the host's Docker daemon when it deploys free5GC/gNB/UE, so it has to resolve to the same place on both sides.fru-tester's settings are in
tester.yaml. ItsapiTokenmust matchbackend.tester.apiTokeninconfig.yaml. -
Load SCTP on the host (fru-tester needs it)
sudo modprobe sctp
-
Up the compose
docker compose up -d
Open
http://<host IP>:8888. The default db is stored at/var/lib/frulab/dband deploy state at/var/lib/frulab/deploy, both mounted in the compose file. fru-tester keeps its CPU allocation in./frutester-data. -
Down the compose
docker compose down
The chart in helm/ deploys fru-lab and fru-tester to Kubernetes. See helm/README.md.
docs/guide.html is the full user guide (in Chinese; open the file in a browser): deploying the core, subscribers, gNB and UEs, logs and images, and the Throughput Tester from the first run to tuning and troubleshooting.
- Setup Script