Skip to content

Commit

Permalink
doc(release): fully update on documentation for v1.1.2 release
Browse files Browse the repository at this point in the history 
Signed-off-by: Raphael Defosseux <[email protected]>
  • Loading branch information
@rdefosse
rdefosse committed Jul 28, 2021
1 parent e927c60 commit 24efffd
Show file tree
Hide file tree
Showing 11 changed files with 408 additions and 98 deletions.
4 changes: 1 addition & 3 deletions ci-scripts/Jenkinsfile-GitHub-Docker
View file
Original file line number Diff line number Diff line change
Expand Up @@ -177,10 +177,8 @@ pipeline {
}
}
}
sh './scripts/syncComponentsLegacy.sh --hss-branch ' + hssBranch + ' --mme-branch ' + mmeBranch + ' --spgwc-branch ' + spgwcBranch + ' --spgwu-tiny-branch ' + spgwuBranch
} else {
sh './scripts/syncComponentsLegacy.sh'
}
sh './scripts/syncComponentsLegacy.sh --hss-branch ' + hssBranch + ' --mme-branch ' + mmeBranch + ' --spgwc-branch ' + spgwcBranch + ' --spgwu-tiny-branch ' + spgwuBranch
sh "mkdir -p archives DS-TEST-RESULTS"
}
if (upstreamEvent) {
Expand Down
117 changes: 81 additions & 36 deletions docs/BUILD_IMAGES.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,66 +14,103 @@

# 1. Retrieve the proper code version #

**CAUTION: 2021/02/08 --> the following tags were used.**
**CAUTION: PLEASE READ THIS SECTION VERY CAREFULLY!**

**cNF Name** | **Branch Name** | **Tags** | **Commit at time of writing** | Ubuntu18 | CentOS7 | CentOS8
------------ | --------------- | ---------- | ------------------------------------------ | -------- | ------- | -------
HSS | `develop` | `2021.w10` | `93dfcbca245ec97652c4d62ba3913a899d956d68` | X | X | X
MME | `develop` | `2020.w47` | `82b11abbd83a346bae220517f09fe8e4233db76b` | X | X | X
SPGW-C | `develop` | `2021.w10` | `b10256535e47ffb86c86a8581d9c50b1f380dcf5` | X | | X
SPGW-U-TINY | `develop` | `2021.w10` | `acd293e616f879f4dacead152c59384d1e533167` | X | | X
This repository only has tutorials and Continuous Integration scripts.

**UPDATE: 2021/05/04 --> I have modified the name of the sync script --> `syncComponentsLegacy.sh`.**
Each 4G Network Function source code is managed in its own repository.

```bash
$ git clone https://github.com/OPENAIRINTERFACE/openair-epc-fed.git
$ cd openair-epc-fed
They are called as git sub-modules in the component folder.

# You can specify a tag on the parent GIT repository such as `2021.w22`
$ git checkout 2021.w22
# Or you can sync to the latest version
$ git checkout master
Before doing anything, you SHALL retrieve the code for each git sub-module.

## 1.1. You are interested on a very stable version. ##

We recommend to synchronize with the master branches on all git sub-modules.

We also recommend that you synchronize this "tutorial" repository with a provided tag. By doing so, the `docker-compose` files will be aligned with feature sets of each NF.

**At the time of writing (2021/07/28), the release tag is v1.1.2.**

# Then you need to resync the sub-modules (ie HSS, SPGW-CUPS, MME).
# You can specify:
# --- a valid tag (such as seen)
# --- a newer tag
# --- a branch to get the latest (`develop` being the latest stable)
# Usually the better option is to specify `develop`
| CNF Name | Branch Name | Tag | Ubuntu 18.04 | RHEL8 (UBI8) |
| ----------- | ----------- | ---------- | ------------ | ----------------|
| FED REPO | N/A | `v1.1.2` | | |
| HSS | `master` | `v1.1.2` | X | X |
| MME | `develop` | `2020.w47` | X | X |
| SPWG-C | `master` | `v1.1.2` | X | X |
| SPGW-U-TINY | `master` | `v1.1.2` | X | X |

$ ./scripts/syncComponentsLegacy.sh --hss-branch 2021.w10 --mme-branch 2020.w47 \
--spgwc-branch 2021.w10 --spgwu-tiny-branch 2021.w10
```bash
# Clone directly on the latest release tag
$ git clone --branch v1.1.2 https://github.com/OPENAIRINTERFACE/openair-epc-fed.git
$ cd openair-epc-fed
# If you forgot to clone directly to the latest release tag
$ git checkout -f v1.1.2

# Synchronize all git submodules
$ ./scripts/syncComponentsLegacy.sh
---------------------------------------------------------
OAI-HSS component branch : 2021.w10
OAI-MME component branch : 2020.w47
OAI-SPGW-C component branch : 2021.w10
OAI-SPGW-U component branch : 2021.w10
OAI-HSS component branch : master
OAI-MME component branch : develop
OAI-SPGW-C component branch : master
OAI-SPGW-U component branch : master
---------------------------------------------------------
git submodule deinit --all --force
git submodule init
git submodule update
```

# Or to not specify anything
$ ./scripts/syncComponentsLegacy.sh
## 1.2. You are interested on the latest features. ##

All the latest features are somehow pushed to the `develop` branches of each NF repository.

It means that we/you are able to build and the Continuous Integration test suite makes sure it
does NOT break any existing tested feature.

Anyhow, the tutorials' docker-compose files on the latest commit of the `master` branch of
`openair-epc-fed` repository SHALL support any additional un-tested feature.

```bash
# Clone
$ git clone https://gitlab.eurecom.fr/oai/cn5g/oai-cn5g-fed.git
$ cd oai-cn5g-fed
# On an existing repository, resync to the last `master` commit
$ git fetch --prune
$ git checkout master
$ git rebase origin/master

# Synchronize all git submodules
$ ./scripts/syncComponentsLegacy.sh --hss-branch develop --mme-branch develop \
--spgwc-branch develop --spgwu-tiny-branch develop
---------------------------------------------------------
OAI-HSS component branch : develop
OAI-MME component branch : develop
OAI-SPGW-C component branch : develop
OAI-SPGW-U component branch : develop
---------------------------------------------------------
....
git submodule deinit --all --force
git submodule init
git submodule update
```

In general, the `docker-compose` files (even in the tutorials) are up-to-date w/ `develop` latest commits in each sub-module.

**CAUTION: At the time of writing (2020 / 10 / 26), only HSS and MME have a full CentOS-7 support.**

It means that if you are on a CentOS 7 host, you will need to build a CentOS8 image of SPGW-C / SPGW-U-TINY.

**CAUTION: (2021 / 07 / 28): CentOS dockerfiles are not part of the OAI CI process. They are certainly in need of maintenance.**

# 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 EURECOM_PROXY=".."` option.
* If you do need it, change with your proxy value.

If you have re-building CN4G images, be careful that `docker` or `podman` may re-use `cached` blobs
to construct the intermediate layers.

We recommend to add the `--no-cache` option in that case.

**CAUTION: the location of the dockerfiles HAVE CHANGED.**

# 3. Build HSS Image #
Expand All @@ -83,7 +120,9 @@ Here in our network configuration, we need to pass the "GIT PROXY" configuration
```bash
$ docker build --target oai-hss --tag oai-hss:production \
--file component/oai-hss/docker/Dockerfile.ubuntu18.04 \
--build-arg EURECOM_PROXY="http://proxy.eurecom.fr:8080" component/oai-hss
# The following line about proxy is certainly not needed in your env \
--build-arg EURECOM_PROXY="http://proxy.eurecom.fr:8080" \
component/oai-hss
$ docker image prune --force
$ docker image ls
oai-hss production f478bafd7a06 1 minute ago 341MB
Expand Down Expand Up @@ -119,7 +158,9 @@ oai-hss production 5fa77e2b6b94 1 minute ago
```bash
$ docker build --target oai-mme --tag oai-mme:production \
--file component/oai-mme/docker/Dockerfile.ubuntu18.04 \
--build-arg EURECOM_PROXY="http://proxy.eurecom.fr:8080" component/oai-mme
# The following line about proxy is certainly not needed in your env \
--build-arg EURECOM_PROXY="http://proxy.eurecom.fr:8080" \
component/oai-mme
$ docker image prune --force
$ docker image ls
oai-mme prodution 45254be9f987 1 minute ago 256MB
Expand Down Expand Up @@ -155,7 +196,9 @@ oai-mme prodution 413cec7d8f3b 1 minute ago
```bash
$ docker build --target oai-spgwc --tag oai-spgwc:production \
--file component/oai-spgwc/docker/Dockerfile.ubuntu18.04 \
--build-arg EURECOM_PROXY="http://proxy.eurecom.fr:8080" component/oai-spgwc
# The following line about proxy is certainly not needed in your env \
--build-arg EURECOM_PROXY="http://proxy.eurecom.fr:8080" \
component/oai-spgwc
$ docker image prune --force
$ docker image ls
oai-spgwc production b1ba7dd16bc5 1 minute ago 218MB
Expand All @@ -182,7 +225,9 @@ oai-spgwc production 15ad64676b1f 1 minute ago
```bash
$ docker build --target oai-spgwu-tiny --tag oai-spgwu-tiny:production \
--file component/oai-spgwu-tiny/docker/Dockerfile.ubuntu18.04 \
--build-arg EURECOM_PROXY="http://proxy.eurecom.fr:8080" component/oai-spgwu-tiny
# The following line about proxy is certainly not needed in your env \
--build-arg EURECOM_PROXY="http://proxy.eurecom.fr:8080" \
component/oai-spgwu-tiny
$ docker image prune --force
$ docker image ls
oai-spgwu-tiny production 588e14481f2b 1 minute ago 220MB
Expand Down
104 changes: 71 additions & 33 deletions docs/BUILD_IMAGES_MAGMA_MME.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,50 +26,77 @@

# 1. Retrieve the proper code version on the OAI-CN part #

At the time of writing (2021 / 02 / 08), if you want to use the OpenAir-CN for a Dual Connectivity use case, you need to use proper branches:
**CAUTION: PLEASE READ THIS SECTION VERY CAREFULLY!**

**cNF Name** | **Branch Name** | **Tags** | **Commit at time of writing** | Ubuntu18 |
------------ | --------------- | ---------- | ------------------------------------------ | -------- |
HSS | `develop` | `2021.w10` | `93dfcbca245ec97652c4d62ba3913a899d956d68` | X |
SPGW-C | `develop` | `2021.w10` | `b10256535e47ffb86c86a8581d9c50b1f380dcf5` | X |
SPGW-U-TINY | `develop` | `2021.w10` | `acd293e616f879f4dacead152c59384d1e533167` | X |
This repository only has tutorials and Continuous Integration scripts.

Each 4G Network Function source code is managed in its own repository.

They are called as git sub-modules in the component folder.

Before doing anything, you SHALL retrieve the code for each git sub-module.

## 1.1. You are interested on a very stable version. ##

We recommend to synchronize with the master branches on all git sub-modules.

We also recommend that you synchronize this "tutorial" repository with a provided tag. By doing so, the `docker-compose` files will be aligned with feature sets of each NF.

**At the time of writing (2021/07/28), the release tag is v1.1.2.**

| CNF Name | Branch Name | Tag | Ubuntu 18.04 | RHEL8 (UBI8) |
| ----------- | ----------- | ---------- | ------------ | ----------------|
| FED REPO | N/A | `v1.1.2` | | |
| HSS | `master` | `v1.1.2` | X | X |
| SPWG-C | `master` | `v1.1.2` | X | X |
| SPGW-U-TINY | `master` | `v1.1.2` | X | X |

```bash
$ git clone https://github.com/OPENAIRINTERFACE/openair-epc-fed.git
# Clone directly on the latest release tag
$ git clone --branch v1.1.2 https://github.com/OPENAIRINTERFACE/openair-epc-fed.git
$ cd openair-epc-fed
# If you forgot to clone directly to the latest release tag
$ git checkout -f v1.1.2

# You can specify a tag on the parent GIT repository such as `2021.w22`
$ git checkout 2021.w22
# Or you can sync to the latest version
$ git checkout master
# Synchronize all git submodules
$ ./scripts/syncComponents.sh
---------------------------------------------------------
OAI-HSS component branch : master
OAI-SPGW-C component branch : master
OAI-SPGW-U component branch : master
```

# Then you need to resync the sub-modules (ie HSS, SPGW-CUPS).
# You can specify:
# --- a valid tag (such as seen)
# --- a newer tag
# --- a branch to get the latest (`develop` being the latest stable)
# Usually the better option is to specify `develop`
## 1.2. You are interested on the latest features. ##

$ ./scripts/syncComponents.sh --hss-branch 2021.w10 --spgwc-branch 2021.w10 --spgwu-tiny-branch 2021.w10
---------------------------------------------------------
OAI-HSS component branch : 2021.w10
OAI-SPGW-C component branch : 2021.w10
OAI-SPGW-U component branch : 2021.w10
---------------------------------------------------------
....
All the latest features are somehow pushed to the `develop` branches of each NF repository.

It means that we/you are able to build and the Continuous Integration test suite makes sure it
does NOT break any existing tested feature.

Anyhow, the tutorials' docker-compose files on the latest commit of the `master` branch of
`openair-epc-fed` repository SHALL support any additional un-tested feature.

# Or to not specify anything
$ ./scripts/syncComponentsLegacy.sh
```bash
# Clone
$ git clone https://gitlab.eurecom.fr/oai/cn5g/oai-cn5g-fed.git
$ cd oai-cn5g-fed
# On an existing repository, resync to the last `master` commit
$ git fetch --prune
$ git checkout master
$ git rebase origin/master

# Synchronize all git submodules
$ ./scripts/syncComponentsLegacy.sh --hss-branch develop --spgwc-branch develop --spgwu-tiny-branch develop
---------------------------------------------------------
OAI-HSS component branch : develop
OAI-SPGW-C component branch : develop
OAI-SPGW-U component branch : develop
---------------------------------------------------------
....
git submodule deinit --all --force
git submodule init
git submodule update
```

In general, the `docker-compose` files (even in the tutorials) are up-to-date w/ `develop` latest commits in each sub-module.

# 2. Generic Parameters #

Here in our network configuration, we need to pass the "GIT PROXY" configuration.
Expand All @@ -86,7 +113,9 @@ On our CI server (a 48-CPU server), this operation takes around **13 minutes**.
```bash
$ docker build --target oai-hss --tag oai-hss:production \
--file component/oai-hss/docker/Dockerfile.ubuntu18.04 \
--build-arg EURECOM_PROXY="http://proxy.eurecom.fr:8080" component/oai-hss
# The following line about proxy is certainly not needed in your env \
--build-arg EURECOM_PROXY="http://proxy.eurecom.fr:8080" \
component/oai-hss
$ docker image prune --force
$ docker image ls
oai-hss production f478bafd7a06 1 minute ago 341MB
Expand All @@ -102,7 +131,9 @@ On our CI server (a 48-CPU server), this operation takes around **10 minutes**.
```bash
$ docker build --target oai-spgwc --tag oai-spgwc:production \
--file component/oai-spgwc/docker/Dockerfile.ubuntu18.04 \
--build-arg EURECOM_PROXY="http://proxy.eurecom.fr:8080" component/oai-spgwc
# The following line about proxy is certainly not needed in your env \
--build-arg EURECOM_PROXY="http://proxy.eurecom.fr:8080" \
component/oai-spgwc
$ docker image prune --force
$ docker image ls
oai-spgwc production b1ba7dd16bc5 1 minute ago 218MB
Expand All @@ -118,7 +149,9 @@ On our CI server (a 48-CPU server), this operation takes around **9 minutes**. P
```bash
$ docker build --target oai-spgwu-tiny --tag oai-spgwu-tiny:production \
--file component/oai-spgwu-tiny/docker/Dockerfile.ubuntu18.04 \
--build-arg EURECOM_PROXY="http://proxy.eurecom.fr:8080" component/oai-spgwu-tiny
# The following line about proxy is certainly not needed in your env \
--build-arg EURECOM_PROXY="http://proxy.eurecom.fr:8080" \
component/oai-spgwu-tiny
$ docker image prune --force
$ docker image ls
oai-spgwu-tiny production 588e14481f2b 1 minute ago 220MB
Expand Down Expand Up @@ -173,6 +206,9 @@ index 34f353a88..b354b18b7 100644

This issue is in our **TODO** list and we are still investigating.

Another known issue is if the UE send a `TAU request` to the MME. Currently the MAGMA MME with an OAI eNB
does not handle it well. We are also working on providing a fix for this issue.

## 6.3. Build the MAGMA-MME Ubuntu18 Docker image ##

On our CI server (a 48-CPU server), this operation takes around **30-35 minutes**. Please be patient.
Expand All @@ -184,7 +220,9 @@ Once again, if you need a proxy, add your proxy URL. If not, remove the option.
```bash
$ docker build --target magma-mme --tag magma-mme:master \
--file lte/gateway/docker/mme/Dockerfile.ubuntu18.04 \
--build-arg GIT_PROXY="http://proxy.eurecom.fr:8080" .
# The following line about proxy is certainly not needed in your env \
--build-arg GIT_PROXY="http://proxy.eurecom.fr:8080" \
.
$ docker image ls
magma-mme nsa-support b6fb01eb0d07 1 minute ago 492MB
...
Expand Down
5 changes: 4 additions & 1 deletion docs/DEPLOY_HOME.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,11 +32,14 @@ In these pages, we are describing how to build and deploy an LTE EPC using the *
- The last valid tag on the MME is **2020.w47**.
- Our developers are now contributing to the **MAGMA-MME**.

**2021/07/28 Update: you have now the choice to either pull images or build your-self.**

**Table of Contents**

1. [Pre-requisites](./DEPLOY_PRE_REQUESITES.md)
2. [Building the Docker Images](./BUILD_IMAGES.md)
2. Getting the images
1. [Retrieving the Container Images](./RETRIEVE_OFFICIAL_IMAGES.md)
2. [Building the Container Images](./BUILD_IMAGES.md)
3. [Deploying using docker-compose](../docker-compose/oai-mme-legacy/README.md)
4. [Verify/Correct your network environment](./CONFIGURE_NETWORKS.md)
5. [Generating Traffic to a connected UE](./GENERATE_TRAFFIC.md)
6 changes: 5 additions & 1 deletion docs/DEPLOY_HOME_MAGMA_MME.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,10 +25,14 @@

We are currently working on the RAN side to fix these issues.

**2021/07/28 Update: you have now the choice to either pull images or build your-self.**

**Table of Contents**

1. [Pre-requisites](./DEPLOY_PRE_REQUESITES_MAGMA.md)
2. [Building the Docker Images](./BUILD_IMAGES_MAGMA_MME.md)
2. Getting the images
1. [Retrieving the Container Images](./RETRIEVE_OFFICIAL_IMAGES_MAGMA.md)
2. [Building the Container Images](./BUILD_IMAGES_MAGMA_MME.md)
3. [Deploying with MAGMA-MME using docker-compose](../docker-compose/magma-mme-demo/README.md)
4. [Verify/Correct your network environment](./CONFIGURE_NETWORKS_MAGMA.md)
5. [Demo made during 2021 MAGMA-dev conference](./NSA_SUPPORT_OAI_RAN.md)
Loading

0 comments on commit 24efffd

Please sign in to comment.