Documentation: System Diagram & Definitions of Terms

[andrewstec]

Issue: We currently do not have any high-level diagram that explains components, such as the differences between AutoTest, Classy Front-end, and Classy Back-end, and how they interact with Github.

Due to the issue above, it becomes difficult to understand the business logic of the application. Although one knows that code is automatically marked, they do not know how or why it is marked, which may make it confusing if we give an instructor additional requirements without the context.

Requirements:

• why and how Docker containers can autograde assignments --> DONE
• the communication capability between Github and AutoTest (component in Classy) --> DONE
• create high-level diagram that explains Network Layer and Application Layer to technical staff

Nice to have's:

• limitations of Classy.

[andrewstec]

Update:

The documentation now includes a segmented table of contents by user-role. Based on the organization of documentation and added areas, we have met some of the above criteria. Some of the above criteria is also better understood.

Changes to the context that should be explained:

Before

After

• why and how Docker containers can autograde assignments --> DONE
• ideal use cases for Classy could become --> Could become case study in separate ticket https://github.com/ubccpsctech/classy/issues/72
• or perhaps we should deprecate references to AutoTest to make things simpler --> Keeping AutoTest separate and explaining detail about how it works with Github integration.
• the communication capability between Github and AutoTest (component in Classy) --> Kept AutoTest entity and created documentation found in /docs/instructor/autotest.md.
• have not described limitations of Classy... it is now a nice-to-have.

[andrewstec]

There are two networks setup as part of Classy, in Docker, that are found on classy-dev:

grading_net:

"Config": [
                {
                    "Subnet": "172.28.0.0/16",
                    "IPRange": "172.28.5.0/24",
                    "Gateway": "172.28.5.254"
                }

classy_default:

"Config": [
                {
                    "Subnet": "172.21.0.0/16",
                    "Gateway": "172.21.0.1"
                }

Dockers that run on the same machine and are not part of a swarm use Docker's bridge network driver. The above two networks are bridge networks.

The four default containers that run on Classy are part of the classy_default network:

-bash-4.2$ docker network inspect classy_default
[
    {
        "Name": "classy_default",
        "Id": "52d387165fc53ce0bfa5fcbf139d0f60e3743bced599a98a169fed1f50119ddc",
        "Created": "2019-10-11T10:04:31.953745275-07:00",
        "Scope": "local",
        "Driver": "bridge",
        "EnableIPv6": false,
        "IPAM": {
            "Driver": "default",
            "Options": null,
            "Config": [
                {
                    "Subnet": "172.21.0.0/16",
                    "Gateway": "172.21.0.1"
                }
            ]
        },
        "Internal": false,
        "Attachable": true,
        "Ingress": false,
        "ConfigFrom": {
            "Network": ""
        },
        "ConfigOnly": false,
        "Containers": {
            "0dbe8950a96efd0f60ba59045db3c1a8d6ee38e62ed571df4906182461c3392c": {
                "Name": "portal",
                "EndpointID": "d434166d27fabc28ac43a556f78ae61735e616f3e0d3f258c81e6bec24668295",
                "MacAddress": "02:42:ac:15:00:04",
                "IPv4Address": "172.21.0.4/16",
                "IPv6Address": ""
            },
            "67599e3917004640cedbda0bccd76f3d181894b4918626ccb960b7c05a987f68": {
                "Name": "autotest",
                "EndpointID": "047d09af250f0bec24227744cc9c7f980ed65e47adb34a206fdcb8c6febf3324",
                "MacAddress": "02:42:ac:15:00:03",
                "IPv4Address": "172.21.0.3/16",
                "IPv6Address": ""
            },
            "87c37a3aa87406e0e9160af679555c672f236f2acba3ea3887f348961a3a880c": {
                "Name": "proxy",
                "EndpointID": "e97e0a9302b9fc8526f14852ab865ee456185917cf305b63f2e607788beb525c",
                "MacAddress": "02:42:ac:15:00:05",
                "IPv4Address": "172.21.0.5/16",
                "IPv6Address": ""
            },
            "f8ce95113f02482931b348cce31bf43eb1b2f259404f99e31502b6df1f35a6b6": {
                "Name": "db",
                "EndpointID": "083e8376ba8d93090ac94fa415c9ab12d583ecb90ad4da1ac2b80e020ef8ec80",
                "MacAddress": "02:42:ac:15:00:02",
                "IPv4Address": "172.21.0.2/16",
                "IPv6Address": ""
            }
        },
        "Options": {},
        "Labels": {
            "com.docker.compose.network": "default",
            "com.docker.compose.project": "classy",
            "com.docker.compose.version": "1.23.2"
        }
    }
]

[andrewstec]

If a container starts up for grading, it is found on the grading_net, which has an internet routeable gateway, but is restricted by IP Table rules. Below is an example of the grading_net while a container is running:

[
    {
        "Name": "grading_net",
        "Id": "931b766f39ea76b814b7c6caf1cb21b71c96dbbb0e5518239f83b75228097430",
        "Created": "2019-09-04T09:09:58.209570856-07:00",
        "Scope": "local",
        "Driver": "bridge",
        "EnableIPv6": false,
        "IPAM": {
            "Driver": "default",
            "Options": {},
            "Config": [
                {
                    "Subnet": "172.28.0.0/16",
                    "IPRange": "172.28.5.0/24",
                    "Gateway": "172.28.5.254"
                }
            ]
        },
        "Internal": false,
        "Attachable": true,
        "Ingress": false,
        "ConfigFrom": {
            "Network": ""
        },
        "ConfigOnly": false,
        "Containers": {
            "3c590daca8a370d8bd9e4a0a72e06ed4e353004c25152bf1f41df40acf1cdd6e": {
                "Name": "inspiring_mendeleev",
                "EndpointID": "4933d54a93b3c6e51e02e104b779eb71c238ef546b728272cca94680784aa406",
                "MacAddress": "02:42:ac:1c:05:00",
                "IPv4Address": "172.28.5.0/16",
                "IPv6Address": ""
            }
        },
        "Options": {},
        "Labels": {}
    }
]

[andrewstec]

System diagrams now found in /docs/tech-staff/architecture.md