Skip to content

MLH-Fellowship/MLH-A11Y

Repository files navigation

source hackmd.io
tags: accessibility LMS education tech React Python Flask Docker Grafana Prometheus cAdvisor docker-compose

MLH A11y

App Description: Building an interactive learning management system (LMS) that helps expose MLH Fellows to digital accessibility by providing resources and an intro to automated accessibility testing.

Table of Contents

Setup/Installation 🏗

Required

  1. Install Docker
  2. Run docker-compose up -d --build
  3. Navigate to http://localhost/ in your browser

Optional

  1. Navigate to http://localhost/grafana to set up Grafana

Tech Stack 🍔

Client

We primarily used Markdown to create educational content for lessons and structure the majority of the website, which we then rendered into React. The React files are connected through the use of React Router, which allows the user to navigate between pages.

  • React – main front-end framework
  • React Markdown – render Markdown files in web app
  • React Router - allows navigation between different webpages
  • Bootstrap - creates user-friendly components
  • rehypeRaw - enables inline HTML rendering within Markdown
  • Axios – supports get and post requests

Web Server

For our project, we integrated a Python Flask server that works as an API for sending/receiving data and handling user authentication.

Tech Used

  • Python
  • Flask – API, user auth

API Endpoints

User authentication

HTTP Verb Endpoint Description
POST /register register new user
POST /login login user

Other/Misc

HTTP Verb Endpoint Description
GET /health api health check

Database

We installed a PostgreSQL database containerized using the PostgreSQL image in the Docker registry.

User

Property Type Description
username string user's username
password string user's password

Containers

In our project, we containerized and isolated necessary components of our application. In addition, we created two different docker-compose files to differentiate production and development. This helped us be more efficient and productive developing in our project. Below is a table that represents the containers, networks, and dependencies of this project (from docker-compose):

Container Name Component Networks Depends On
app React app (front-end) nginx_client api
api Flask web server api_db, nginx_api db
db PostgreSQL db api_db n/a
nginx Nginx server nginx_api, nginx_client, monitoring n/a
cadvisor Container Monitoring monitoring n/a
prometheus Prometheus data gathering monitoring cadvisor
grafana Monitoring visualization monitoring prometheus

CI/CD

For our continuous integration, we integrated linting testers for python in our project, docker-build tester, and a deploy workflow (embedded with an endpoint check to verify deployment) and a discord notification for a successful deployment.

  • Docker build – test client and web server docker images
  • Linters (ex. black and flake8 for Flask-based backend)
  • User authentication endpoint testing (see test-prod.sh)
  • Deployment – ssh to AWS CentOS instance and deploy app using docker-compose
    • Success/Failure notification through Discord webhook
Workflow Run on Description
docker-build push to master/pull request run docker-build tests
linters push to master/pull request run python linters
deploy push to master deploy application to AWS

Monitoring

For our project, we setup three monitoring tools. We setup cAdvisor, Prometheus, and Grafana. These three monitoring tools depend on one another. The dependency line is as follows: cAdvisor --> Prometheus --> Grafana. Grafana is setup runnin on the /grafana endpoint of our application. Monitoring tools endpoints:

  • cadvisor: /cadvsisor
  • grafana: /grafana

Grafana

cAdvisor

Prometheus

Deployment

MLH-A11y is deployed on t2.medium CentOS Stream 8 EC2 instance hosted on AWS. The domain, mlha11y.tech, was bought and configured on Domain.com, and is secured with Let's Encrypt using certbot-nginx.

Issues Encountered

Web Server/DB Issues

When building our web server, we had some trouble using requesting data from our markdown files and converting it into React for the different unit pages. However, we got around this by using Axios. We decided to use axios.get in order to retrieve the markdown file and set its contents as a variable.

Client Issues

In launching our unit-based educational approach, we initially dealt with several barriers in finding appropriate libraries to easily and efficiently render lesson material, videos, and content. We immediately began looking at the options and settled on react-markdown, a library by remarkjs for rendering markdown files in React. We immediately came across an obstacle: delivering interactive and reactive markdown-based content - a key feature we wanted to implement to ensure that users would be able to get hands-on experience with coding using custom Repl.it exercises. The base implementation of react-markdown did not enable us to render inline HTML, but we were able to resolve this issue by utilizing the rehypeRaw package, allowing us to both style and customize our Markdown templates to a greater degree.

We also had some issues with created protected routes for some of the pages. We originally wanted to have the unit pages only be accessible when logged in, but we kept getting errors that various variables are undefined.

Production Issues

We encountered several speed bumps with securing our routing, using nginx and Docker, and setting up monitoring tools like Prometheus and Grafana. Early on, the most notable issue was that our project's full dependencies would consistently crash our VM on each docker-compose up --build command. As a stop-gap, we had to reboot our t2.micro instance, remove all Docker containers, generated files, volumes, and images, and rebuild. This was a tedious process, but after we received the go-ahead to upgrade our instance to a t2.medium, we were able to resolve other docker-based issues with relative ease.

Authors

About

An interactive learning management system (LMS) that helps expose MLH Fellows to digital accessibility.

Topics

Resources

License

Code of conduct

Security policy

Stars

Watchers

Forks

Releases

No releases published

Sponsor this project

 

Packages

No packages published