paulmataruso/docker-open5gs-Borjis
1
0
Fork 0
mirror of https://github.com/Borjis131/docker-open5gs.git synced 2025-11-02 04:43:14 +00:00
Code Issues Packages Projects Releases Wiki Activity

README.md and docs/:

Browse Source 
- Project README.md
- docs/ with FAQS and configuration explained
This commit is contained in:
Borjis131
2023-02-08 14:51:15 +01:00
parent 5a947e8462
commit 25c59a5249
3 changed files with 188 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

72
README.md Normal file
View File

@@ -0,0 +1,72 @@
# Open5GS 5G Core in Docker
Open5GS 5G Core Network Functions images ready for Docker.
This repository contains the Dockerfiles and docker compose files used to deploy a configurable 5G Core.
## Use it
All the images depend on the base image. So first, update the `.env` file with the desired values to use:
`OPEN5GS_VERSION` is the version of Open5GS to use.
- Accepted values are the tags, branches or commit IDs used in the Open5GS project
- Default value: v2.5.6
- Tested values: v2.5.5, v2.5.6
`UBUNTU_VERSION` is the version of the ubuntu Docker image used as base for the containers.
- Accepted values are the tags used by Ubuntu in Docker Hub
- Default value: focal
- Tested values: focal
`MONGODB_VERSION` is the version of the mongo Docker image used as database for Open5GS.
- Accepted values are the tags used by MongoDB in Docker Hub
- Default value: The one specified in the `.env` file
- Tested values: 3.6.8, 4.2
`DOCKER_HOST_IP` is the IP address of the host running Docker. This modifies the `advertise` field in the `upf.yaml` config file for this to work when exposing the Docker containers network.
## Build it
To create the base image run:
```bash
make
```
This will take a while, after this you will have the base image, tagged with the `OPEN5GS_VERSION` selected.
After this you can run the following to create the Network Functions images:
```bash
# Example using the basic deployment with docker compose (v2)
docker compose -f compose-files/basic-v3/docker-compose.yaml --env-file=.env up -d
# or
# Example using the basic deployment with docker-compose (v1)
docker-compose -f compose-files/basic-v2/docker-compose.yaml up -d
```
## Use it
```bash
# Run the basic deployment with docker compose (v2)
docker compose -f compose-files/basic-v3/docker-compose.yaml --env-file=.env up -d
# Tear down the basic deployment with docker compose (v2)
docker compose -f compose-files/basic-v3/docker-compose.yaml --env-file=.env down
# or
# Run the basic deployment with docker-compose (v1)
docker-compose -f compose-files/basic-v2/docker-compose.yaml up -d
# Tear down the basic deployment with docker-compose (v1)
docker-compose -f compose-files/basic-v2/docker-compose.yaml down
```
### Repository contents
- `compose-files/` directory contains different docker compose deployments.
- `configs/` directory contains the Open5GS configuration files for each docker compose deployment.
- `docs/` directory contains the documentation for this project.
- `images/` directory has each Network Function Dockerfile.
Check `docs/` to see the documentation.

36
docs/FAQ.md Normal file
View File

@@ -0,0 +1,36 @@
# Frequently Asked Questions
## Docker compose volume warning
It is normal to see:
```bash
WARN[0297]
volume "open5gs_db_data" already exists but was not created for project "<deployment_name>".
volume "open5gs_db_config" already exists but was not created for project "<deployment_name>".
```
It is only a warning, telling you that the Docker volume exists.
## No connectivity to an external network
Run in the host:
```bash
sudo sysctl -w net.ipv4.conf.all.forwarding=1
sudo iptables -P FORWARD ACCEPT
# Extracted from:
# enable forwarding from Docker containers to the outside world
# https://docs.docker.com/network/bridge/#enable-forwarding-from-docker-containers-to-the-outside-world
```
## Environment variables not expanding
If you are seeing an error related to the environment variables in Docker compose not expanding, check where the `.env` file is located. To avoid errors, it is easier to specify the path using the `--env-file` command option (even though, if you are using v1 format with `docker-compose`, it is not needed).
```bash
# Example using the basic deployment with docker compose (v2)
docker compose -f compose-files/basic/docker-compose.yaml --env-file=.env up -d
# Example using the basic deployment with docker-compose (v1)
docker-compose -f compose-files/basic/docker-compose.yaml --env-file=.env up -d
```

80
docs/configuration.md Normal file
View File

@@ -0,0 +1,80 @@
# Configuration guide
## Common configuration
### Network configuration
All the services are connected using a network called `open5gs` using the bridge driver and IPv4 addresses in the range 10.33.33.0/24. This network is destroyed with the Docker compose down command.
The `basic/` Docker compose deployment exposes three things:
- SCTP port 38412 for NGAP connections to the AMF
- UDP port 2152 for GTP connections to the UPF
- TCP port 27017 for connections to the mongo database
These ports are available in the loopback network of the host running Docker and the host itself exposes these ports for external connections.
### Database configuration
After building, the 5G Core will start without any user configured in the Open5GS mongo database.
The information for the database is kept in Docker volumes named `open5gs_db_config` and `open5gs_db_data`, this way the information added to the database is persistent between restarts.
You can use the Open5GS `open5gs-dbctl` script in the host to add users to the database.
The database Docker volumes are marked with a label `org.open5gs.mongodb_version` indicating the `MONGODB_VERSION` selected in the `.env` file. This marks the version used for the mongo container. This label is needed to debug issues with users changing the mongo container version but keeping the Docker volumes created.
> When upgrading/downgrading the `MONGODB_VERSION` the existing `open5gs_db_config` and `open5gs_db_data` Docker volumes could cause problems/crashing. It is recommended to remove them.
### Network Function configuration
You can override the command being run in the container by using the command section in each service specified in the Docker compose file:
```yaml
nssf:
...
command: "-c /open5gs/config/nssf.yaml"
```
## The `basic` Docker compose deployment
The `configs/basic/` configuration uses Open5GS 5G Network Functions without SCP.
The `configs/basic/upf.yaml` UPF config file is using the _advertise_ option with the `DOCKER_HOST_IP` environment variable present in the `.env` file (it is used through the `docker-host.external-ip` hosts entry). This configures the 5G Core to expect connections from external networks (not the docker network), through the host machine.
The files for the `basic` deployment `compose-files/basic-v2/` and `compose-files/basic-v3/` contains the docker-compose.yaml files to work with docker compose version 2 and version 3 features.
The Network Functions configuration files are mounted using different methods in `compose-files/basic-v2/` and `compose-files/basic-v3/` but the outcome is the same.
`compose-files/basic-v2/` method uses volumes while `compose-files/basic-v3/` method uses configs. In both, the source config file present in `configs/basic/<nf>.yaml` is mounted into the container path `/open5gs/config/<nf>.yaml`. This way you can try different configuration files without the need of rebuilding the Docker image.
## Specific Network Function configuration
### AMF configuration
AMF container lets you choose if you want to enable/disable checksum offloading. Checksum offloading is enabled by default but can be disabled by setting the environment variable `DISABLE_CHECKSUM_OFFLOADING` to TRUE in the Docker compose AMF service:
```yaml
amf:
...
environment:
- DISABLE_CHECKSUM_OFFLOADING=TRUE
...
```
### UPF configuration
UPF container lets you enable/disable NAT in the UPF. NAT in the UPF is enabled by default but can be disabled by setting the environment variable `DISABLE_NAT` to TRUE in the Docker compose UPF service:
```yaml
upf:
...
environment:
- DISABLE_NAT=TRUE
...
```
UPF container reads the subnets specified in the Open5GS config file and setups the network interfaces needed with the addresses specified and the NAT (or not) configuration:
```yaml
upf:
...
subnet:
- addr: 10.45.0.1/16
...
```