From 9abdeba7378b04dad6671d0318103ea3923f24be Mon Sep 17 00:00:00 2001 From: Jaspreet Sachdev Date: Mon, 6 Dec 2021 21:51:21 +0000 Subject: [PATCH] GitBook: [#9] Added deployment steps --- SUMMARY.md | 8 +-- .../deploy-using-docker-compose.md | 55 +++++++++++-------- .../deploy-using-helm.md | 0 .../overview.md | 4 +- 4 files changed, 38 insertions(+), 29 deletions(-) rename {sdk-installation-wip => sdk-installation}/deploy-using-docker-compose.md (62%) rename {sdk-installation-wip => sdk-installation}/deploy-using-helm.md (100%) rename {sdk-installation-wip => sdk-installation}/overview.md (60%) diff --git a/SUMMARY.md b/SUMMARY.md index 696ee40..cb0c191 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -22,11 +22,11 @@ * [Monitoring](monitoring/README.md) * [ELK Integration](monitoring/elk-integration.md) -## SDK Installation - WIP +## SDK Installation -* [Overview](sdk-installation-wip/overview.md) -* [Deploy using Docker Compose](sdk-installation-wip/deploy-using-docker-compose.md) -* [Deploy using Helm](sdk-installation-wip/deploy-using-helm.md) +* [Overview](sdk-installation/overview.md) +* [Deploy using Docker Compose](sdk-installation/deploy-using-docker-compose.md) +* [Deploy using Helm](sdk-installation/deploy-using-helm.md) ## Configuration Examples diff --git a/sdk-installation-wip/deploy-using-docker-compose.md b/sdk-installation/deploy-using-docker-compose.md similarity index 62% rename from sdk-installation-wip/deploy-using-docker-compose.md rename to sdk-installation/deploy-using-docker-compose.md index d16c03a..f183712 100644 --- a/sdk-installation-wip/deploy-using-docker-compose.md +++ b/sdk-installation/deploy-using-docker-compose.md @@ -29,9 +29,13 @@ The following two modes are currently supported by docker-compose: * docker-compose.lb.selfsigned.yml: manages LB deployment with self-signed certificates * docker-compose.lb.letsencrypt.yml: manages LB deployment with Letencrypt certificates -### Environment Variables +### Docker Compose Environment Variables +The deployments are managed using different environment files for docker-compose: +* .env : used for non LB deployments with either self-signed or own certificate deployments executed by docker-compose. For additional information please read [this](https://github.com/Telecominfraproject/wlan-cloud-ucentral-deploy/tree/main/docker-compose#non-lb-deployment-with-self-signed-certificates). +* .env.selfsigned: used for LB with self-signed deployments executed by alias docker-compose-lb-selfsigned. For additional information please read [this](https://github.com/Telecominfraproject/wlan-cloud-ucentral-deploy/tree/main/docker-compose#lb-deployment-with-self-signed-certificates). +* .env.letsencrypt: used for LB with letsencrypt deployments executed by alias docker-compose-lb-letsencrypt. For additional information please read [this](https://github.com/Telecominfraproject/wlan-cloud-ucentral-deploy/tree/main/docker-compose#lb-deployment-with-letsencrypt-certificates). ### Volumes @@ -39,7 +43,7 @@ The deployment creates local volumes to persist mostly application and database `docker-compose/certs/` directory used by multiple services -Service specific data directories and configuration files located under `docker-compose/` mounted into the appropriate containers. +`docker-compose/{microservice}_data/` directory used by each service for configuration and data. Where {microservice} is one of: owgw, owsec, owfms and owprov. {% hint style="info" %} 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.\ @@ -48,19 +52,14 @@ Since the files are under version control, you may have to change the ownership ### Configuration -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. +This configuration information specific to the deployment is kept in environment files per microservices. These files are: owgw.env, owgw-ui.env, owsec.env, owfms.env, owprov.env and owprov-ui.env. These env files are used to generated the runtime configuration(properties) file when no configuration is found in their respective {microservices}-data directory. ### Ports Exposed port dependencies by application are listed below: -`127.0.0.1:80/tcp` - OpenWiFi-UI\ +`127.0.0.1:80/443 tcp` - OpenWiFi-uCentralGW-UI\ +`127.0.0.1:8080/8443 tcp` - OpenWiFi-Provisoning-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\ @@ -83,31 +82,41 @@ The certificates are valid for the `*.wlan.local` domain. ## How to 1. First you'll have to [install Docker Compose](https://docs.docker.com/compose/install/) 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. +2. The Docker Compose uCentral micro service configs use `openwifi.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`: +4. Set the default user and temporary password by following instruction of security service [here](https://github.com/Telecominfraproject/wlan-cloud-ucentralsec/tree/main#default-username-and-password). +5. Edit owsec.env and ensure the following variable contains the username and shasum from step 4: + + ``` + AUTHENTICATION_DEFAULT_USERNAME=##username from step 4## + AUTHENTICATION_DEFAULT_PASSWORD=##hash from step 4## + ``` +6. 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`: ``` - Name Command State Ports ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- -ucentral_kafka_1 /opt/bitnami/scripts/kafka ... Up 9092/tcp -ucentral_rttys_1 /rttys/rttys Up 127.0.0.1:5912->5912/tcp, 127.0.0.1:5913->5913/tcp -ucentral_ucentralgw-ui_1 /docker-entrypoint.sh ngin ... Up 127.0.0.1:80->80/tcp -ucentral_ucentralgw.wlan.local_1 /bin/sh -c /ucentral/ucent ... Up 0.0.0.0:15002->15002/tcp, 127.0.0.1:16002->16002/tcp, 0.0.0.0:16003->16003/tcp, 127.0.0.1:16102->16102/tcp, 17002/tcp -ucentral_ucentralsec.wlan.local_1 /bin/sh -c /ucentral/ucent ... Up 127.0.0.1:16001->16001/tcp, 127.0.0.1:16101->16101/tcp, 17001/tcp -ucentral_zookeeper_1 /docker-entrypoint.sh zkSe ... Up 2181/tcp, 2888/tcp, 3888/tcp, 8080/tcp + Name Command State Ports +--------------------------------------------------------------------------------------------------------------------------------------------------------------------- +openwifi_kafka_1 /opt/bitnami/scripts/kafka ... Up 9092/tcp +openwifi_owfms_1 /docker-entrypoint.sh /ope ... Up 0.0.0.0:16004->16004/tcp,:::16004->16004/tcp, 0.0.0.0:16104->16104/tcp,:::16104->16104/tcp, 17004/tcp +openwifi_owgw-ui_1 /docker-entrypoint.sh ngin ... Up 0.0.0.0:443->443/tcp,:::443->443/tcp, 0.0.0.0:80->80/tcp,:::80->80/tcp +openwifi_owgw_1 /docker-entrypoint.sh /ope ... Up 0.0.0.0:15002->15002/tcp,:::15002->15002/tcp, 0.0.0.0:16002->16002/tcp,:::16002->16002/tcp, + 0.0.0.0:16003->16003/tcp,:::16003->16003/tcp, 0.0.0.0:16102->16102/tcp,:::16102->16102/tcp, 17002/tcp +openwifi_owprov-ui_1 /docker-entrypoint.sh ngin ... Up 80/tcp, 0.0.0.0:8080->8080/tcp,:::8080->8080/tcp, 0.0.0.0:8443->8443/tcp,:::8443->8443/tcp +openwifi_owprov_1 /docker-entrypoint.sh /ope ... Up 0.0.0.0:16005->16005/tcp,:::16005->16005/tcp, 0.0.0.0:16105->16105/tcp,:::16105->16105/tcp, 17005/tcp +openwifi_owsec_1 /docker-entrypoint.sh /ope ... Up 0.0.0.0:16001->16001/tcp,:::16001->16001/tcp, 0.0.0.0:16101->16101/tcp,:::16101->16101/tcp, 17001/tcp +openwifi_rttys_1 /rttys/rttys Up 0.0.0.0:5912->5912/tcp,:::5912->5912/tcp, 0.0.0.0:5913->5913/tcp,:::5913->5913/tcp ``` 1. 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). -2. 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. +2. Connect to your AP via SSH and add a static hosts entry in `/etc/hosts` for `openwifi.wlan.local` which points to the address of the host the Compose deployment runs on. 3. 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. -4. 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. +4. Go to `http://openwifi.wlan.local` to visit the UI and login with default username and password. You will now be prompted to change this default password to something more secured. 5. 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: ``` -export UCENTRALSEC="ucentral.wlan.local:16001" +export UCENTRALSEC="openwifi.wlan.local:16001" export FLAGS="-s --cacert /docker-compose/certs/restapi-ca.pem" ``` diff --git a/sdk-installation-wip/deploy-using-helm.md b/sdk-installation/deploy-using-helm.md similarity index 100% rename from sdk-installation-wip/deploy-using-helm.md rename to sdk-installation/deploy-using-helm.md diff --git a/sdk-installation-wip/overview.md b/sdk-installation/overview.md similarity index 60% rename from sdk-installation-wip/overview.md rename to sdk-installation/overview.md index 39a6409..a74cd0b 100644 --- a/sdk-installation-wip/overview.md +++ b/sdk-installation/overview.md @@ -7,6 +7,6 @@ The [wlan-cloud-ucentral-deploy](https://github.com/Telecominfraproject/wlan-clo The repository is managed using branches where: -* main branch: contains references to development SDK images -* release/v\* branch: contains image references specific to the release artifacts. For example: release/v2.4.0 branch will have references to SDK images related to 2.4.0 +* main branch: contains references to the latest development SDK images +* release/v\* branch: contains image references specific to the release artifacts. For example: release/v2.4.0 branch will contain references to SDK images related to 2.4.0 release candidates (RC) and GA.