- GTP5G kernel module: needed to run the UPF
- Docker Engine: needed to run the Free5GC containers
- Docker Compose v2: needed to bootstrap the free5GC stack
Note: AVX for MongoDB: some HW does not support MongoDB releases above
4.4 due to use of the new AVX instructions set. To verify if your CPU is compatible you can check CPU flags by running
grep avx /proc/cpuinfo. A workaround is suggested here.
Because we need to create tunnel interface, we need to use privileged container with root permission.
Pull docker images from Docker Hub
docker compose pull
[Optional] Build docker images from local sources
# Clone the project
git clone https://github.com/free5gc/free5gc-compose.git
# clone free5gc sources
git clone --recursive -j `nproc` https://github.com/free5gc/free5gc.git
# Build the images
docker compose -f docker-compose-build.yaml build
# Alternatively you can build specific NF image e.g.:
docker compose -f docker-compose-build.yaml build free5gc-amf
Dangling images may be created during the build process. It is advised to remove them from time to time to free up disk space.
docker rmi $(docker images -f "dangling=true" -q)
You can create free5GC containers based on local images or docker hub images:
# use local images
docker compose -f docker-compose-build.yaml up
# use images from docker hub
docker compose up # add -d to run in background mode
Destroy the established container resource after testing:
# Remove established containers (local images)
docker compose -f docker-compose-build.yaml rm
# Remove established containers (remote images)
docker compose rm
Sometimes, you need to drop data from DB:
docker exec -it mongodb mongo
> use free5gc
> exit # (Or Ctrl-D)
You can see logs for each service using
docker logs command. For example, to access the logs of the SMF you can use:
docker logs smf
Please refer to the wiki for more troubleshooting information.
Integration with external gNB/UE simulators
This issue provides detailed steps that might be useful.
Integration of WebUI with Nginx reverse proxy
Here you can find helpful guidelines on the integration of Nginx reverse proxy to set it in front of the WebUI: https://github.com/free5gc/free5gc-compose/issues/55#issuecomment-1146648600
Vagrant Box Option
For Linux kernel version below 5.4 you can setup a working environment using a vagrant box: https://github.com/abousselmi/vagrant-free5gc
Please refer to GTP5G kernel module for more information.
You can check the following informations below:
[Optional] Run N3IWUE
If you want use N3IWUE, you need to open your web browser from your host machine, and enter the URL
- On the login page, enter username
- Once logged in, widen the page until you see “Subscribers” on the left-hand side column.
- Click on the
Subscriberstab and then on the
- Scroll down to
Operator Code Typeand change it from "OPc" to "OP".
- Make sure the following config between
Subscriberyou create are the same:
- PLMNID (ex. 208930000001234)
- OP value (choose OP instead of OPC)
- Scroll all the way down and click on
- Scroll down to
Then you can access the N3IWUE container and run N3IWUE using the following commands:
# access N3IWUE bash
docker exec -it n3iwue bash
# run N3IWUE