OpenWiFi 2.0 SDK
The wlan-cloud-ucentral-deploy repository contains a Compose file and the related files and directories to set up a local uCentral instance with Docker Compose. You'll find all related data under the docker-compose/ directory.
The deployment creates local volumes to persist mostly application and database data. In addition to that several bind mounts are created:
docker-compose/certs/ directory used by multiple services
Service specific data directories and configuration files located under docker-compose/ mounted into the appropriate containers.
Be aware that the deployment uses bind mounts on the host to mount certificate and configuration data for the micro services and therefore these files and directories will be owned by the user in the container. Since the files are under version control, you may have to change the ownership to your user again before pulling changes.
Changing image tags used in the deployments may be performed in docker-compose/.env.
By default this file specifies the micro service image tags according to the release branch you have checked out.
Additional configuration changes such as database settings or passwords are found in the various other service specific .env files.
The rest of the configuration is done through the config files located in the appropriate subdirectories of the Compose project directory.
Exposed port dependencies by application are listed below:
127.0.0.1:80/tcp - OpenWiFi-UI
127.0.0.1:5912/tcp - rttys dev
127.0.0.1:5913/tcp - rttys user
0.0.0.0:15002/tcp - OpenWiFi-uCentralGW websocket
127.0.0.1:16002/tcp - OpenWiFi-uCentralGW REST API public
0.0.0.0:16003/tcp - OpenWiFi-uCentralGW fileupload
127.0.0.1:16102/tcp - OpenWiFi-uCentralGW alivecheck
127.0.0.1:16001/tcp - OpenWiFi-uCentralSec REST API public
127.0.0.1:16101/tcp - OpenWiFi-uCentralSec alivecheck
By default only the websocket and fileupload component of the OpenWiFi uCentralGW (Gateway) micro service are exposed on all interfaces. All other exposed services listen on localhost. You can change that according to your needs in the ports sections ofdocker-compose/docker-compose.yml.
The repository includes a TIP Root CA Digicert-signed (for the Gateway websocket to devices) and a self-signed certificate (for the REST API northbound and other components), which you can use to create a local deployment out of the box.
The certificates are valid for the *.wlan.local domain.
1. First you'll have to install Docker Compose according to your platform specific instructions. After that clone the repository with git clone https://github.com/Telecominfraproject/wlan-cloud-ucentral-deploy.
2. The Docker Compose uCentral micro service configs use ucentral.wlan.local as a hostname, so make sure you add an entry in your hosts file (or in your local DNS solution) which points to 127.0.0.1 or whatever the IP of the host running the deployment is.
3. Switch to the Compose project directory with cd docker-compose/.
4. Spin up the deployment with docker-compose up -d. If your deployment was successfully created, you should see the following output with docker-compose ps:
5. Since the certificate for the REST API and other components is self-signed, you have to add it to the system trust store of the containers communicating together internally via TLS. The add-ca-cert.sh script located in the Compose project directory does the work for you.
You also have to trust the self-signed REST API certificate on your local machine. To achieve that you either have to add certs/restapi-ca.pem to your trusted browser certificates or add certificate exceptions in your browser by visiting https://ucentral.wlan.local:16001 and https://ucentral.wlan.local:16002 and accepting the self-signed SSL certificate warnings (make sure to visit both and add the exceptions).
6. Connect to your AP via SSH and add a static hosts entry in /etc/hosts for ucentral.wlan.local which points to the address of the host the Compose deployment runs on.
7. While staying in the SSH session, copy the content of certs/restapi-ca.pem on your local machine to your clipboard and append it to the file /etc/ssl/cert.pem on the AP. This way your AP will also trust the self-signed certificate.
8. Go to http://ucentral.wlan.local to visit the UI and login with username tip@ucentral.com and password openwifi if you didn't change the default credentials in the uCentralSec configuration.
9. To use the curl test scripts which are included in the micro service repositories make sure to set the following environment variables before issuing a request:
Stop the running containers with docker-compose down
Check out the new branch by repeating Step 1 from How to above for the given release and docker-compose up -d.
Don’t forget to re-add the self-signed certificates to the containers with the provided script.
Also be aware that you may have to change back some file permissions. To obtain the most recent changes as the files are under version control, you may have to change the ownership to your user again before pulling changes.
OpenWiFi 2.0 SDK
OpenWi-Fi 2.0 SDK can be deployed to Kubernetes using a Helm package. The Helm package code is located at https://github.com/Telecominfraproject/wlan-cloud-ucentral-deploy/ repository.
Each micro service in the OpenWiFi SDK system has its own Helm chart that is managed in the micro service’s own repository. The assembly chart collects all the relevant micro service charts and other external dependencies like kafka, rtty, etc. and deploys them together as one cohesive release.
You can review the full list of all the assembled micro services and related dependencies here: https://github.com/Telecominfraproject/wlan-cloud-ucentral-deploy/blob/main/chart/Chart.yaml#L6
There are multiple ways you can install OpenWiFi SDK with assembly charts:
One way is by installing directly from the assembly chart’s repository. For that, you’ll need to install and extra Helm plugin that is used to pull the latest charts code from all the referenced micro services: https://github.com/aslafy-z/helm-git.
Another way, which is considered more stable, is by installing from a prepackaged bundle that is published to https://tip.jfrog.io/ui/native/tip-wlan-cloud-ucentral-helm/ on every official uCentral release. For this approach to work, you don’t need to install any additional plugins or dependencies, just to make sure you’ve got Helm installed on your local system.
Install the helm-git pluging according to the official documentation
Run helm upgrade --install tip-ucentral git+https://github.com/Telecominfraproject/wlan-cloud-ucentral-deploy/@chart?ref=main
You can also reference any other open branch from the deployment repository. For example, if you want to deploy using the assembly code from the v2.0.0-rc1 branch, you can just run helm upgrade --install tip-ucentral git+https://github.com/Telecominfraproject/wlan-cloud-ucentral-deploy/@chart?ref=v2.0.0-rc1
This method doesn’t require to install anything locally other than Helm
Start by adding the wlan-cloud-ucentral Helm repository to your local list of repositories by running helm repo add tip-ucentral https://tip.jfrog.io/artifactory/tip-wlan-cloud-ucentral-helm/
helm upgrade --install tip-ucentral wlan-cloud-ucentral to install the latest version, or specify the release you want to install by adding the --version x.y.z flag.
The configuration of OpenWiFi SDK using Helm chart may be separated into layers:
Micro services default values - values files that are stored in micro service helm charts (i.e. https://github.com/Telecominfraproject/wlan-cloud-ucentralgw/blob/master/helm/values.yaml ). These values are used by default if no other parameters are supplied, so in case you have any microservice-related variables that need to be added in default installation (for example new application configuration properties), add them in the related helm chart values as they will be applied in next release update.
Assembly chart values - values that are stored in the assembly repository (https://github.com/Telecominfraproject/wlan-cloud-ucentral-deploy/blob/main/chart/values.yaml ) – these are values that override default micro services values so that all uCentral components could connect to each other correctly, and the whole system can be installed as one bundle. These parameters are environment specific, and can differ between and installation of the bundle on an EKS cluster or a MicroK8s local setup.
Helm upgrade/install flag overwrites - these values cam be specific for each specific helm install command during execution and usually contain installation-specific values like TLS certificates, security credentials, loadbalancer configuration parameters and so on. These may be passed using --set flag or --values flag (details may be found in https://helm.sh/docs/chart_best_practices/values/ and in micro services helm charts), or you can also save them into one file and reference this file during the helm upgrade command using the --values flag.
During deployment all values are merged as maps with priority to the level of deployment (so Environment-specific values will override any overrides from Assembly chart values and so on).
Example: Let’s pass environment-specific ucentralgw.properties configuration parameter (which is probably quite common thing to test). For example, we have an environment that requires to set parameter ucentral.websocket.host.0.backlog to 1000. For that we would need to run following command, extending our base command:
OpenWiFi SDK can also be deployed to an AWS labs environment using a Github actions workflow: https://github.com/Telecominfraproject/wlan-testing/actions/workflows/ucentralgw-deployment.yaml.
The configuration is dynamic, and new namespaces (a.k.a environments) may be created by adjusting the json configuration in the workflow.
The json format allows to deploy or upgrade and existing environment using the latest Docker images or to specify a specific version of each micro service.
To deploy specific version to the specific environment a list of things must be done:
First, you need to make sure that the Docker image with the correct version exists in Artifactory, otherwise, the Helm upgrade will fail.
Update the json configuration in the workflow to reference the require version for the require micro service (examples are attached in the json file itself)
Re-run the deployment in Github actions. You can also make all the above changes in a separate branch, and re-run the workflow from that branch (using a drop-down in the top left corner in Github’s UI).
TIP OpenWiFi
Release 2.0 SDK offers a number of ways to consume OpenWiFi. Available as a single Docker for just the uCentralGW or as a set of micro services offering increasing value to consume helps multiple eco-system partners use as much or as little as desired to integrate with or build a commercial product on the TIP OpenWiFi SDK.
Features of the 2.0 SDK at July MVP include:
RBAC based security framework
OpenAPI compliant Northbound
Kafka Message Bus
PGSql HA Cluster
Firmware Manager
Central Logging Dashboard
User Interface
Docker Compose & Helm DevOps Deployment Automation