Setup

This page describes the setup needed to run the Orchestrated 5G Service Provisioning workflows.

Step 0. Clone the Orchestrated 5G Service Provisioning repository

The repository is available at Bitbucket.

Step 1. Prepare Airflow and system dependencies

Follow these steps to install system prerequisites, Maat and Airflow (Ubuntu examples).

1. Go to home directory and install system dependencies:

   cd ~
   sudo apt-get update
   sudo apt-get install -y python3-pip python3-venv ca-certificates curl
   

2. Install Docker and docker-compose:

   sudo install -m 0755 -d /etc/apt/keyrings
   sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
   sudo chmod a+r /etc/apt/keyrings/docker.asc
   echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
   $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
   sudo apt-get update
   sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin docker-compose
   

3. Clone Maat and prepare the environment:

   cd ~
   git clone https://bitbucket.software.geant.org/scm/ossbss/maat.git
   cd ~/maat/docker
   cp .env.example .env
   chmod +x keycloak_conf/keycloak-setup.sh
   

4. Configure Maat environment variables:

   cd ~/maat/docker
   SERVER_IP=$(hostname -I | awk '{print $1}')
   
   sed -i "s/^MAAT_HOST=.*/MAAT_HOST=${SERVER_IP}/" .env
   sed -i "s/^MAAT_PORT=.*/MAAT_PORT=8080/" .env
   sed -i "s/^MAAT_PROTOCOL=.*/MAAT_PROTOCOL=https/" .env
   sed -i "s/^MAAT_RESOURCE_PROTOCOL=.*/MAAT_RESOURCE_PROTOCOL=https/" .env
   sed -i "s/^MAAT_RESOURCE_ADDRESS=.*/MAAT_RESOURCE_ADDRESS=${SERVER_IP}/" .env
   sed -i "s/^MAAT_RESOURCE_PORT=.*/MAAT_RESOURCE_PORT=8080/" .env
   sed -i "s/^MAAT_SERVICE_PROTOCOL=.*/MAAT_SERVICE_PROTOCOL=https/" .env
   sed -i "s/^MAAT_SERVICE_ADDRESS=.*/MAAT_SERVICE_ADDRESS=${SERVER_IP}/" .env
   sed -i "s/^MAAT_SERVICE_PORT=.*/MAAT_SERVICE_PORT=8080/" .env
   sed -i "s/^EVENT_LISTENER_HOST=.*/EVENT_LISTENER_HOST=${SERVER_IP}/" .env
   sed -i "s/^MAAT_UI_HOST=.*/MAAT_UI_HOST=${SERVER_IP}/" .env
   sed -i "s/^KEYCLOAK_HOST=.*/KEYCLOAK_HOST=${SERVER_IP}/" .env
   sed -i "s/^KEYCLOAK_PORT=.*/KEYCLOAK_PORT=8090/" .env
   sed -i "s|^KEYCLOAK_ISSUER_URI=.*|KEYCLOAK_ISSUER_URI=http://${SERVER_IP}:8090/realms/MaatRealm|" .env
   sed -i "s|^KEYCLOAK_REDIRECT_URI=.*|KEYCLOAK_REDIRECT_URI=http://${SERVER_IP}:9100|" .env
   

5. Start Maat (wait approximately 2 minutes for Keycloak to initialize):

   cd ~/maat/docker
   sudo docker compose -f docker-compose-3.yml --env-file .env up -d
   

6. Verify that Maat is running:

   sudo docker compose -f docker-compose-3.yml --env-file .env ps
   

   All services should appear as healthy or Up.

7. Install Airflow 3:

   cd ~
   python3 -m venv ~/venv-airflow3
   source ~/venv-airflow3/bin/activate
   
   export AIRFLOW_HOME=$HOME/airflow
   mkdir -p "$AIRFLOW_HOME/dags" "$AIRFLOW_HOME/logs" "$AIRFLOW_HOME/plugins"
   
   AIRFLOW_VERSION=3.2.1
   PYTHON_VERSION=3.12
   CONSTRAINT_URL="https://raw.githubusercontent.com/apache/airflow/constraints-${AIRFLOW_VERSION}/constraints-${PYTHON_VERSION}.txt"
   
   pip install --upgrade pip
   pip install "apache-airflow==${AIRFLOW_VERSION}" --constraint "${CONSTRAINT_URL}"
   pip install \
     "apache-airflow-providers-ssh==5.0.0" \
     "apache-airflow-providers-postgres==6.6.3" \
     "apache-airflow-providers-redis==4.4.4" \
     "apache-airflow-providers-smtp==2.4.5" \
     --constraint "${CONSTRAINT_URL}"
   

8. Configure and initialize Airflow:

   export AIRFLOW_HOME=$HOME/airflow
   
   airflow db migrate
   
   sed -i "s#^dags_folder *=.*#dags_folder = ${AIRFLOW_HOME}/dags#" "${AIRFLOW_HOME}/airflow.cfg"
   sed -i "s#^plugins_folder *=.*#plugins_folder = ${AIRFLOW_HOME}/plugins#" "${AIRFLOW_HOME}/airflow.cfg"
   sed -i "s#^base_log_folder *=.*#base_log_folder = ${AIRFLOW_HOME}/logs#" "${AIRFLOW_HOME}/airflow.cfg"
   sed -i "s#^load_examples *=.*#load_examples = False#" "${AIRFLOW_HOME}/airflow.cfg"
   sed -i "s#^executor *=.*#executor = LocalExecutor#" "${AIRFLOW_HOME}/airflow.cfg"
   sed -i "s#^sql_alchemy_conn *=.*#sql_alchemy_conn = sqlite:///${AIRFLOW_HOME}/airflow.db#" "${AIRFLOW_HOME}/airflow.cfg"
   

9. Start Airflow:

   source ~/venv-airflow3/bin/activate
   export AIRFLOW_HOME=$HOME/airflow
   export PYTHONPATH=$AIRFLOW_HOME/dags
   export AIRFLOW__API__PORT=8082
   
   airflow standalone
   

10. Access the services:

    • Airflow: http://<machine-ip>:8082

      • Username: admin

      • Password: auto-generated, printed in the terminal output when airflow standalone starts. If the terminal output is no longer visible:

        cat ~/airflow/simple_auth_manager_passwords.json.generated
        

    • Maat Web UI: http://<machine-ip>:9100

      • Username: admin
      • Password: admin
      • Note: the browser may show a certificate warning when the UI connects to the Maat API over HTTPS. If so, first open https://<machine-ip>:8080 in the browser and accept the certificate.

    • Maat API: https://<machine-ip>:8080

    • Keycloak admin console: http://<machine-ip>:8090

      • Username: admin
      • Password: admin

Step 2. Configure Maat connectivity

1. Verify that the Maat API is reachable from the Airflow host:

   source ~/venv-airflow3/bin/activate
   SERVER_IP=$(hostname -I | awk '{print $1}')
   curl -k https://${SERVER_IP}:8080/actuator/health
   

2. Update the Maat base URL in ~/airflow/dags/lib/maat.py to match your server address:

https://<machine-ip>:8080

Step 3. Configure Amarisoft SSH and paths

As stated, this lab currently supports Amarisoft-based targets. In this step, we will do basic tasks to ensure that your Amarisoft box is ready to be used with the workflows.

1. Open ~/airflow/dags/lib/local_config.py and set the Amarisoft SSH credentials in AMARISOFT_SSH.

2. Confirm the remote Amarisoft directories are available:

   • /root/enb/config/ for gNodeB configuration
   • /root/mme/config/ for core configuration

3. Verify SSH connectivity to the Amarisoft hosts from the Airflow environment:

   source ~/venv-airflow3/bin/activate
   ssh <amarisoft-user>@<amarisoft-host>
   

Step 4. Populate inventory of physical resources in Maat

The workflows depend on the following Maat object categories:

• device.gnodeb
• device.radio_unit
• device.core
• 5g.cell
• 5g.core

The DAGs can create 5g.cell and 5g.core logical resources, but the associated physical device entries must already exist in Maat.

In order to do so, adapt the resources in the maat-data/data-model/ directory from the provided repository to your specific environment and inventory, and then run the following script inside the maat-data/ directory:

python3 apply_maat_updates.py

Step 5. Validation of setup

1. Verify the DAGs create_5g_cell, create_5g_core, and create_5g_basic are visible in the Airflow UI at http://<machine-ip>:8082.

2. Verify Maat connectivity by listing resources from the Airflow environment:

   source ~/venv-airflow3/bin/activate
   SERVER_IP=$(hostname -I | awk '{print $1}')
   curl -k https://${SERVER_IP}:8080/resourceInventoryManagement/v4.0.0/resource
   

3. Confirm SSH login to the Amarisoft hosts using the configured credentials.