###################################################################
For most up to date and thorough information regarding MCMS PON Manager setup,
Please reference the relevant version release notes (TN035)

###################################################################
Copyright (C) 2022 by Tibit Communications, Inc.
All rights reserved.

Overview
--------

This document provides instructions for creating a MCMS PON Manager Docker container from a .deb package

See the following additional documents for more information on the MCMS PON Manager:
 * ponmgr/README.txt
 * Tibit Tech Note TN0035 MCMS PON Manager User Guide and Release Notes.

Requirements:
* Ubuntu Linux 18.04 (Bionic Beaver) or 20.04 (Focal Fossa)
* docker-ce 19.03.5 (Docker Community Edition for Ubuntu)
* docker-compose 1.17.1-2
* Internet Connection

Currently Supported Browsers:
    - FireFox
    - Chrome

Ensure that you have execute/root permissions

Build Environment Setup
-----------------------

This section provides instructions for preparing the build environment for creating
a containerized PON Manager.

1) Update host OS with the latest patches.

    - sudo apt update
    - sudo apt upgrade

2) Install Docker Community Edition for Ubuntu. Do not use the docker apt package
distributed with Ubuntu 18.04/20.04. Instead, use the instructions at the following
link to install Docker Community Edition.
  * https://docs.docker.com/install/linux/docker-ce/ubuntu/


3) Install the docker-compose utility.

    - sudo apt install docker-compose



Creating the Container
----------------------

Use the following steps to build and install the PON Manager container. Execute
docker-compose commands from the docker/ directory.

1) Edit the PON Manager configuration files:
    a. user_database.json | Stores info for database to be used for user authentication
        - host : Host/IP of your mongoDB server hosting your user database
        - name : Name of your user database. (IF it doesn't exist, it will be created)
        - port : MongoDB Port
        - auth_enable : Boolean value determining if the MongoDB server at host:port is using authentication
        - auth_db : Name of your MongoDB user database. (Used when auth_enabled = true)
        - username : The username of the MongoDB user to authenticate with. (Used when auth_enabled = true)
        - password : The password of the MongoDB user specified by username. (Used when auth_enabled = true)
        - tls_enable : Boolean value specifying whether the MongoDB server at host:port is using encryption
        - ca_cert_path : The local path to the encryption certificate
        - db_uri : Raw MongoDB connection uri. All other fields are ignored if this is used
        - dns_srv : Boolean to determine if the MongoDB server is using a DNS seed list
        - replica_set_enable : Boolean value used to determine if the MongoDB server is running as a replica set
        - replica_set_name : The name of the MongoDB replica set. (Used when replica_set_enable = true)
        - replica_set_hosts : List of hosts to be used as the MongoDB replica set. (Used when replica_set_enable = true)

    b. databases.json | Stores list of all available PON databases in Pon Manager
        - Default:
            - host : Host/IP of your mongoDB server hosting your PON Data
            - name : Name of your Pon Data database (Ex. tibit_pon_controller)
            - port : MongoDB Port
            - auth_enable : Boolean value determining if the MongoDB server at host:port is using authentication
            - auth_db : Name of your MongoDB user database. (Used when auth_enabled = true)
            - username : The username of the MongoDB user to authenticate with. (Used when auth_enabled = true)
            - password : The password of the MongoDB user specified by username. (Used when auth_enabled = true)
            - tls_enable : Boolean value specifying whether the MongoDB server at host:port is using encryption
            - ca_cert_path : The local path to the encryption certificate
            - db_uri : Raw MongoDB connection uri. All other fields are ignored if this is used
            - dns_srv : Boolean to determine if the MongoDB server is using a DNS seed list
            - replica_set_enable : Boolean value used to determine if the MongoDB server is running as a replica set
            - replica_set_name : The name of the MongoDB replica set. (Used when replica_set_enable = true)
            - replica_set_hosts : List of hosts to be used as the MongoDB replica set. (Used when replica_set_enable = true)

    c. recovery_email_configuration.json | Configures SMTP Email server for sending user password recovery emails
        host : The host to use for sending email
        port : Port to use for the SMTP server defined above (string)
        use_tls : Use TLS connection. Requires supported host and port (boolean in string format)
        user : username for the SMTP server
        password : password for user

2) Configure django_key parameter in user_database.json | Interal key for API operations
    - The django key can be any freeform string.
    - To generate a key, use the script "generate_django_key.py" located in the "special_scripts" directory in the root of your PON Manager package
    - If using multiple PON Manager instances, the django key value should be the same across all instances. The django key can be rotated out and changed periodically. Ex. If compromised

    To Configure, add a new key value pair to the set in user_databases.json with the key of "django_key" and the value being the secret key
    ex.
        "django_key": "someSecretKey"


3) Build the docker image used by the PON Manager container using docker-compose.

    docker-compose build

4) Make the Apache user owner of the 'databases.json' configuration file
    chown www-data.www-data databases.json

5) Create, install, and start the container using docker-compose. Specify the '-d'
option to start the container in the background.

    docker-compose up -d



Accessing the PON Manager Container
-------------------------------------

    In browser, navigate to; http://*ipofserver*
    ex:
    http://10.1.10.255
    http://127.0.0.1


Managing the PON Manager Container
-------------------------------------

This section provides additional commands for managing the PON Manager docker
container. Execute docker-compose commands from the docker/ directory.

* restart the PON Manager Container

    docker-compose restart


* Modify configuration files
    a. Modify the configuration files as desired according to the section; "Creating the Container"
    b. Restart the Container as defined above in the section; "Restart the PON Manager Container"

* Stop the PON Manager container

    docker-compose down
