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

###################################################################
Copyright (c) 2025, Ciena Corporation
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)
        - django_key : Randomized string used for internal MCMS encoding operations.

    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 randomized key, use the output from the script "generate_django_key.py" located in the "docker" directory and write into the "django_key" field.
    - If using multiple PON Manager instances, the "django_key" value should be the same across all instances.

    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; https://*ipofserver*
    ex:
    https://10.1.10.255
    https://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
