Merge branch 'documentation' into 'master'

Documentation

See merge request oai/cn5g/oai-cn5g-fed!2

README.md

@@ -20,6 +20,8 @@ Its main purpose is for Continuous Integration scripting.
 
 It also hosts some tutorials.
 
+* [How to do a container-based simple deployment](docs/DEPLOY_HOME.md).
+
 # Licence info
 
 It is distributed under `OAI Public License V1.1`.

docs/BUILD_IMAGES.md

+<table style="border-collapse: collapse; border: none;">
+  <tr style="border-collapse: collapse; border: none;">
+    <td style="border-collapse: collapse; border: none;">
+      <a href="http://www.openairinterface.org/">
+         <img src="./images/oai_final_logo.png" alt="" border=3 height=50 width=150>
+         </img>
+      </a>
+    </td>
+    <td style="border-collapse: collapse; border: none; vertical-align: center;">
+      <b><font size = "5">OpenAirInterface 5G Core Network Docker Deployment : Building the Images</font></b>
+    </td>
+  </tr>
+</table>
+
+# 1.  Retrieve the proper code version #
+
+At the time of writing (2020 / 09 / 23), this is the current state:
+
+ * Limited attach
+ * We are using our 4G SPGW-U as UPF
+
+**cNF Name** | **Branch Name** | **Commit at time of writing**              | Ubuntu18 | CentOS7 | CentOS8
+------------ | --------------- | ------------------------------------------ | -------- | ------- | -------
+AMF          | `develop`       | `8341c82073923601091f59803fe6c066cd8a68d8` | X        |         |  
+SMF          | `develop`       | `e43b4429ce0eb8e754dd2bfbaa2c620cfa36ac49` | X        |         |  
+SPGW-U-TINY  | `develop`       | `e812920bc48dcedb0e8f3811f3dbbe2ebebeb899` | X        |         |  
+
+```bash
+$ git clone https://gitlab.eurecom.fr/oai/cn5g/oai-cn5g-fed.git
+$ cd oai-cn5g-fed
+$ git checkout master
+$ git pull origin master
+$ ./scripts/syncComponents.sh
+---------------------------------------------------------
+OAI-AMF    component branch : develop
+OAI-SMF    component branch : develop
+OAI-SPGW-U component branch : develop
+---------------------------------------------------------
+....
+```
+
+# 2. Generic Parameters #
+
+Here in our network configuration, we need to pass the "GIT PROXY" configuration.
+
+*   If you do not need, remove the `--build-arg NEEDED_GIT_PROXY=".."` option.
+*   If you do need it, change with your proxy value.
+
+# 3. Build AMF Image #
+
+## 3.1 On a Ubuntu 18.04 Host ##
+
+```bash
+$ docker build --target oai-amf --tag oai-amf:production \
+               --file component/oai-amf/docker/Dockerfile.ubuntu.18.04 \
+               --build-arg NEEDED_GIT_PROXY="http://proxy.eurecom.fr:8080" \
+               component/oai-amf
+$ docker image prune --force
+$ docker image ls
+oai-amf                 production             f478bafd7a06        1 minute ago          258MB
+...
+```
+
+# 4. Build SMF Image #
+
+## 4.1 On a Ubuntu 18.04 Host ##
+
+```bash
+$ docker build --target oai-smf --tag oai-smf:production \
+               --file component/oai-smf/docker/Dockerfile.ubuntu.18.04 \
+               --build-arg NEEDED_GIT_PROXY="http://proxy.eurecom.fr:8080" \
+               component/oai-smf
+$ docker image prune --force
+$ docker image ls
+oai-smf                 production             f478bafd7a06        1 minute ago          274MB
+...
+```
+
+# 5. Build SPGW-U Image #
+
+## 5.1 On a Ubuntu 18.04 Host ##
+
+```bash
+$ docker build --target oai-spgwu-tiny --tag oai-spgwu-tiny:production \
+               --file component/oai-upf-equivalent/ci-scripts/Dockerfile.ubuntu18.04 \
+               --build-arg EURECOM_PROXY="http://proxy.eurecom.fr:8080" component/oai-upf-equivalent
+$ docker image prune --force
+$ docker image ls
+oai-spgwu-tiny          production             588e14481f2b        1 minute ago          220MB
+...
+```
+
+You are ready to [Configure the Containers](./CONFIGURE_CONTAINERS.md).

docs/CONFIGURE_CONTAINERS.md

+<table style="border-collapse: collapse; border: none;">
+  <tr style="border-collapse: collapse; border: none;">
+    <td style="border-collapse: collapse; border: none;">
+      <a href="http://www.openairinterface.org/">
+         <img src="./images/oai_final_logo.png" alt="" border=3 height=50 width=150>
+         </img>
+      </a>
+    </td>
+    <td style="border-collapse: collapse; border: none; vertical-align: center;">
+      <b><font size = "5">OpenAirInterface 5G Core Network Docker Deployment : Configure Containers</font></b>
+    </td>
+  </tr>
+</table>
+
+
+**TABLE OF CONTENTS**
+
+1.  [Networking](#1-create-a-docker-bridged-network)
+2.  [Deploy](#2-deploy-the-containers)
+3.  [Configure](#3-configure-the-containers)
+
+# 1. Create a Docker Bridged Network #
+
+```bash
+$ docker network create --attachable --subnet 192.168.61.0/26 --ip-range 192.168.61.0/26 prod-oai-public-net
+```
+
+Once again we chose an **IDLE** IP range in our network. **Please change to proper value in your environment.**
+
+# 2. Deploy the containers #
+
+**TODO**
+
+# 3. Configure the containers #
+
+**TODO**
+

docs/DEPLOY_HOME.md

+<table style="border-collapse: collapse; border: none;">
+  <tr style="border-collapse: collapse; border: none;">
+    <td style="border-collapse: collapse; border: none;">
+      <a href="http://www.openairinterface.org/">
+         <img src="./images/oai_final_logo.png" alt="" border=3 height=50 width=150>
+         </img>
+      </a>
+    </td>
+    <td style="border-collapse: collapse; border: none; vertical-align: center;">
+      <b><font size = "5">OpenAirInterface 5G Core Network Docker Deployment Home Page</font></b>
+    </td>
+  </tr>
+</table>
+
+**Table of Contents**
+
+1.  [Pre-requisites](./DEPLOY_PRE_REQUESITES.md)
+2.  [Building the Docker Images](./BUILD_IMAGES.md)
+3.  [Configuring the Containers](./CONFIGURE_CONTAINERS.md)
+4.  [Running the Network Functions](./RUN_CNF.md)
+5.  [Generating Traffic to a connected UE](./GENERATE_TRAFFIC.md)

docs/DEPLOY_PRE_REQUESITES.md

+<table style="border-collapse: collapse; border: none;">
+  <tr style="border-collapse: collapse; border: none;">
+    <td style="border-collapse: collapse; border: none;">
+      <a href="http://www.openairinterface.org/">
+         <img src="./images/oai_final_logo.png" alt="" border=3 height=50 width=150>
+         </img>
+      </a>
+    </td>
+    <td style="border-collapse: collapse; border: none; vertical-align: center;">
+      <b><font size = "5">OpenAirInterface 5G Core Network Docker Deployment : Pre-Requisites </font></b>
+    </td>
+  </tr>
+</table>
+
+# 1. Install the proper version of Docker #
+
+At time of writing (2020 / 09 / 22):
+
+```bash
+$ dpkg --list | grep docker
+ii  docker-ce                             5:19.03.6~3-0~ubuntu-bionic                     amd64        Docker: the open-source application container engine
+ii  docker-ce-cli                         5:19.03.6~3-0~ubuntu-bionic                     amd64        Docker CLI: the open-source application container engine
+```
+
+Also python3 (at least 3.6) shall be installed.
+
+```bash
+$ python3 --version
+Python 3.6.9
+```
+
+**CAUTION: do not forget to add your username to the `docker` group**
+
+Otherwise you will have to run in `sudo` mode.
+
+```bash
+$ sudo usermod -a -G docker myusername
+```
+
+On Centos 7.7 host:
+
+```bash
+$ sudo yum install -y yum-utils
+$ sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
+$ sudo yum install docker-ce docker-ce-cli containerd.io
+$ sudo systemctl start docker
+$ docker info
+```
+
+# 2. Create an account on Docker Hub #
+
+Go to [https://hub.docker.com/](https://hub.docker.com/) website and create an account.
+
+# 3. Pull base images #
+
+* Ubuntu  version: We need 2 base images: `ubuntu:bionic` and `mysql/mysql-server:5.7`
+
+Currently we are working to support `CentOS8` and `RHEL8` distributions.
+
+First log with your Docker Hub credentials.
+
+```bash
+$ docker login
+Login with your Docker ID to push and pull images from Docker Hub. If you don't have a Docker ID, head over to https://hub.docker.com to create one.
+Username:
+Password:
+```
+
+Then pull base images.
+
+On a Ubuntu18.04 host:
+
+```bash
+$ docker pull ubuntu:bionic
+$ docker pull mysql/mysql-server:5.7
+```
+
+Finally you may logoff --> your token is stored in plain text..
+
+```bash
+$ docker logout
+```
+
+# 4. Network Configuration #
+
+**CAUTION: THIS FIRST STEP IS MANDATORY.**
+
+Based on this [recommendation](https://docs.docker.com/network/bridge/#enable-forwarding-from-docker-containers-to-the-outside-world):
+
+```bash
+$ sudo sysctl net.ipv4.conf.all.forwarding=1
+$ sudo iptables -P FORWARD ACCEPT
+```
+
+**CAUTION: THIS SECOND STEP MAY NOT BE NEEDED IN YOUR ENVIRONMENT.**
+
+* The default docker network (ie "bridge") is on "172.17.0.0/16" range.
+* In our Eurecom private network, this IP address range is already in use.
+  - We have to change it to another IP range is free in our private network configuration.
+  - We picked a **new/IDLE** IP range by adding a `/etc/docker/daemon.json` file:
+* If you have to do the same change:
+  - Select "192.168.17.1/24" range if it is free in your environment.
+  - Select another IP range if not.
+
+```json
+{
+    "bip": "192.168.17.1/24"
+}
+```
+
+Restart the docker daemon:
+
+```bash
+$ sudo service docker restart
+$ docker info
+```
+
+Check the new network configuration:
+
+```bash
+$ docker network inspect bridge
+[
+    {
+        "Name": "bridge",
+....
+        "Scope": "local",
+        "Driver": "bridge",
+        "EnableIPv6": false,
+        "IPAM": {
+            "Driver": "default",
+            "Options": null,
+            "Config": [
+                {
+                    "Subnet": "192.168.17.1/24",
+                    "Gateway": "192.168.17.1"
+                }
+            ]
+        },
+....
+```
+
+You are ready to [build the images](./BUILD_IMAGES.md).