Overview

Sunbird software is containerized. The installation script uses the Docker swarm orchestration engine to run the Sunbird docker images. The Docker swarm consists of manager and agent nodes. The containers are run on the agent nodes and the manager nodes manage the container lifecycle.

All the stateless services in Sunbird - Portal, LMS Backend, API Gateway and Proxies - are run as docker containers inside the swarm. All stateful services consisting of Cassandra, PostgreSql, Elasticsearch and the OAuth service(Keycloak) are run on Virtual Machines (VMs) directly. The installation is automated using shell scripts and Ansible.

This page provides you with information on the prerequisites and the sequence of steps to install Sunbird.

Prerequisites

• Minimum 2 servers with 7 GB RAM, running Ubuntu server 16.04 LTS. You can scale the infrastructure by adding servers. Sunbird is designed to scale horizontally. The servers should connect to each other over TCP on the following ports The scripts do not work on virtual machines created locally (using VMware/VirtualBox) and have been tested on Azure and AWS VMs.

• Recommended that you have a domain name and a valid SSL certificate for the domain. If you do not have a domain name, you can configure Sunbird such that it can be accessed over an IP address. If you have a domain name, and you want to get an SSL certificate, refer Let’s Encrypt to generate a free certificate which is valid for 90 days.

• Sunbird requires EkStep API keys to access the EkStep content repository. Follow the steps here to get the keys. If you are creating a test environment, get the QA API keys.

• Create a common linux user (e.g. deployer) on all the servers. Configure this user to use key based ssh. Use an empty passphrase while generating the ssh key to avoid password prompts during installation. Since the installation script uses this key (user) to deploy Sunbird, this user must have sudo access on the servers.

• Create an Azure storage account to complete the Sunbird installation. This account is used to store QR code images and achievement badges.

• The following table lists the services that are set up and run as part of installation. The table also lists the optimal server count for a typical staging or production environment with thousands of users.

  Server Name	Suggested Servers per Environment	Basic Requirement	Maximum Servers
  Docker swarm manager1	Staging - 1 Prod - 3	CPU: 1core & RAM: 2GB	Any
  Docker swarm agent nodes1	Staging - 1 Prod - 3	CPU: 2core & RAM: 6GB	Any
  Elasticsearch2	Staging - 1 Prod- 3	CPU: 1core & RAM: 3GB	Any
  Postgres master2	Staging&Prod - 1	CPU: 1core & RAM: 3GB	1
  Postgres slave2	Staging&Prod - 1	CPU: 1core & RAM: 3GB	1
  Cassandra2	Staging&Prod - 1	CPU: 1core & RAM: 3GB	1
  Keycloak1	Staging&Prod - 1	CPU: 1core & RAM: 4GB	Any

• When you install Sunbird on 2 servers, all services with a common superscript (e.g. servername²) for the Server Name are run on the same server. The App server runs services with superscript ¹ and the DB server runs services with superscript ².

Mapping Ports

The following is a list of ports that must be open:

Note: If you setup more than one swarm agent node, you will need to configure a load balancer to spray the incoming requests to all the agent nodes. All agent nodes in a swarm route the request to the right service.

Supported application versions

Installation Procedure

Note: Choose one docker swarm manager VM as the installation server and execute the following steps from that server. If you are installing Sunbird on two servers, execute the steps from the app server.

1.Install git using sudo apt-get update -y && sudo apt-get install git -y

2.Run git clone https://github.com/project-sunbird/sunbird-devops.git

3.cd sunbird-devops

4.Checkout the latest release branch git checkout tags/release-1.8.1 -b release-1.8.1

5.cd deploy

6.Update the configuration parameters in the config file.

The configuration parameters are explained in the following table:

1. Run the script ./sunbird_install.sh. This script sets up the infra setup from stage 1 to stage 6 in a sequence as mentioned in the following table.

Note: The badger service does not work without an Azure storage account name and key.

1. Get the public key from keycloak http://<dns_name / IP>/auth -> realm settings -> keys -> public keys (click on public keys) and set it for sunbird_sso_publickey parameter in config file. Now, execute the command ./sunbird_install.sh -s core to redeploy the core services.

Note: - If you want to re-run particular stage in the installation, execute ./sunbird_install.sh -s <stage name>

• To know more about the script sunbird_install.sh refer to the section below.

Post Installation Configuration

1. Create user access token - To create a user access token you should execute the following cURL:

curl -X POST {dns_name}/auth/realms/sunbird/protocol/openid-connect/token \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'client_id=admin-cli&username=user-manager&password={password}&grant_type=password'

The values in the { } braces should be replaced with your environment values - {dns_name} - Domain or the IP address of your application server. - {password} - Password of the user-manager user. The one you have provided for sso_password parameter in the config file above.

1. Create root organization - To create a root organization you should the following cURL:

curl -X POST  \ 
  {dns_name}/api/org/v1/create \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {jwt token from ~/jwt_token_player.txt}' \
  -H 'x-authenticated-user-token: {access token created last step}' \
  -d '{
  "request":{
     "orgName": "{Your Organization Name}",
     "description": "{Your organization description}",
     "isRootOrg":true,
     "channel":"{Your Channel Name}"
    }
   }'

Note Channel should be a unique name across Sunbird instances who are using the EkStep content repository

1. Update sunbird_default_channel in the config file with {Your Channel Name} (that was created in previous step) and re-run the command ./sunbird_install.sh -s core

2. Run ./sunbird_install.sh -s posttest, to validate all the services for a successful installation. On executing the script, a file postInstallationLogs.log in the logs directory will be created.

3. Open https://[domain-name] and sign up.

4. You may choose your own user name and password. The format for the username while login is: username@channelName

Sunbird Install Script

The Sunbird installation script ./sunbird_install.sh is a wrapper shell script that invokes other scripts or Ansible playbooks. It fetches all the docker images from the Sunbird DockerHub repository.

• sanity.sh - Basic Sunbird prerequisites check.

• install-deps.sh - Installs Ansible v2.4.1.0 on the installation server to provision and deploy Sunbird. This script also sets up the docker swarm.

• generate_config.sh - Creates a workspace for the installation and sets up necessary config files.

• generate_hosts.sh - Creates a hosts file (Ansible file format) dynamically to run the Ansible scripts.

• install-dbs.sh - Installs Cassandra, Elasticsearch and Postgres databases

• init-dbs.sh - Sets up the required schema for Cassandra, Elasticsearch and Postgres databases

• deploy-apis.sh - Deploys the api gateway (Kong) as a docker service using Ansible.

• deploy-proxy.sh - Deploys the proxy (Nginx) as a docker service.

• provision-keycloak.sh - Installs Keycloak.

• deploy-keycloak-vm.sh - Deploys the OAuth service (Keycloak) on the VM. The Keycloak service runs outside the swarm.

• bootstrap-keycloak.sh - Imports the auth realm and configures Keycloak.

• deploy-badger.sh - Deploys the badger service as docker service.

• deploy-core.sh - Deploys the core services player, content, actor and learner service as docker services. The content, actor and learner service together form the LMS backend.