README.md and docs/:

- Project README.md
- docs/ with FAQS and configuration explained

README.md

@@ -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.

docs/FAQ.md

@@ -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
+```

docs/configuration.md

@@ -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
+    ...
+```