search

PlatonOrg / platon

Platform for Learning and Teaching Online: Open Source Education Platform
Other
7 stars 0 forks source link

readme

PLaTon - Platform for Learning and Teaching Online

Logo PLaTon

CI codecov CodeFactor

Table of Contents

  1. Introduction
  2. Key Features
  3. Installation
    1. Prerequisites
    2. Recommendations
    3. Setup
  4. Technical Documentation
    1. Platform Architecture
    2. Environment Configuration
    3. Codebase Structure
    4. Key Libraries and Frameworks
    5. Development Workflow
      1. Scripts
      2. Testing
      3. Linting and Formatting
    6. Deployment
      1. On-premise
      2. Cloud
      3. CI Pipelile
      4. Github
  5. Functional Documentation
  6. Contributing
  7. License

Introduction

PLaTon is an open-source online learning and teaching platform designed to facilitate the creation, management, and sharing of educational resources. It provides a comprehensive set of tools for educators, students, and administrators to create, organize, and manage courses and activities in a collaborative environment. PLaTon aims to support the learning process by integrating with popular Learning Management Systems (LMS) and fostering an active community of users and contributors.

Homepage : https://cisstech.github.io/platon/

Key Features

Planned features

Installation

Prerequisites

In order to run PLaTon you'll need the following tools installed

> docker --version
Docker version 20.10.22, build 3a2c30b

> node --version
v22.0.0

> yarn --version
1.22.19

> nvm --version
0.37.2

Recommendations

We highly suggest the use of nvm to update node version easily based on the .npmrc file placed inside the root folder.

By default, the docker daemon always runs as the root user on a linux system. If you don’t want to preface the docker command with sudo please read this guide.

Also if you are using docker for mac, we recommend you to increase the memory size to at least 4GB in the resources section of the docker dashboard.

Docker for mac

Setup

Verify installation: To ensure that PLaTon has been successfully installed and set up, check that you can access the platform in your web browser at https://localhost and that the backend server is responding to API requests. If everything is working as expected, you should be able to create and manage resources, courses, and activities, as well as register and log in as different user types.

At this point, you may see an error in your browser like the following one:

SSL warnings

The message and the way you will fix it might be different depending on the browser.

Keychain app

Note: The default administrator account has the following credentials:

The other default accounts are listed inside the ./tools/database/init.json file.

See the environment configuration section for more information about default accounts.

Technical Documentation

Platform Architecture

PLaTon is a comprehensive online learning and teaching platform. It is designed with a modular architecture to provide a scalable, maintainable, and flexible solution for managing educational resources, activities, courses, and user interactions.

Technical Stack

The platform is built using a modern tech stack, ensuring high performance and robustness. The main components of the technical stack are:

The platform is organized into four main components:

Docker stack

┌─────────────────────────────────────────────────────┐
│                      Docker                         │
├─────────────────────────────────────────────────────┤
│                      Nginx                          │
│                                                     │
│                Reverse Proxy Config                 │
│                                                     │
├─────────────────┬─────────────────┬────────────────-┤
│    PostgreSQL   │      Redis      │     PgAdmin     │
│                 │                 │                 │
│     (Database)  │    (Cache)      │  (Admin Panel)  │
└─────────────────┴─────────────────┴────────────────-┘
graph TD
    A[Client Browser] --> B[Nginx Reverse Proxy]
    B --> C[Angular Frontend :4200]
    B --> D[NestJS Backend API :4201]
    B --> E[Documentation :4203]
    D --> F[PostgreSQL Database]
    D --> G[Redis Cache]
    H[Docker] --> B
    H --> F
    H --> G
    H --> I[PgAdmin]

    subgraph Host Machine
    C["Angular Frontend :4200<br/><small>yarn start:web</small>"]
    D["NestJS Backend API :4201<br/><small>yarn start:api</small>"]
    E["Documentation :4203<br/><small>yarn serve:docs</small>"]
    end

    subgraph Docker Containers
    B["Nginx Reverse Proxy<br/><small>./bin/docker/up.sh</small>"]
    F[PostgreSQL Database]
    G[Redis Cache]
    I[PgAdmin]
    end

    subgraph Commands
    J["Start all services:<br/><small>./bin/docker/up.sh && yarn serve:service-1 ... yarn serve:service-n</small>"]
    end
graph TD
    A[Client Browser] --> B[Nginx Reverse Proxy]
    B --> C[Angular Frontend]
    B --> D[NestJS Backend API]
    B --> E[Static Documentation]
    D --> F[PostgreSQL Database]
    D --> G[Redis Cache]
    H[Docker] --> B
    H --> C
    H --> D
    H --> E
    H --> F
    H --> G
    H --> I[PgAdmin]
    H --> J[Certbot]

    subgraph Docker Containers
    B["Nginx Reverse Proxy<br/><small>./bin/docker/up.sh --prod</small>"]
    C[Angular Frontend]
    D["NestJS Backend API<br/><small>node dist/apps/api/main.js</small>"]
    E[Static Documentation]
    F[PostgreSQL Database]
    G[Redis Cache]
    I[PgAdmin]
    J["Certbot<br/><small>Automatic SSL renewal</small>"]
    end

    subgraph Commands
    K["Start all services:<br/><small>./bin/docker/up.sh --prod</small>"]
    L["Build for production:<br/><small>yarn build:web<br/>yarn build:api<br/>yarn build:docs</small>"]
    end

Here's a high-level overview of how the different parts interact:

This hybrid approach allows for easy development and testing, while still leveraging the benefits of containerization for production deployments.

Technical Overview

PLaTon is built on a modern, scalable architecture using the following key technologies:

Environment Configuration

This document describes the environnement configuration for the application, including the required environment variables and their descriptions. Proper configuration is crucial for the smooth operation of the system. Make sure to set these variables before running the application in development or production mode.

Name Service Description Default
COMPOSE_HTTP_TIMEOUT docker Increase docker build timeout which is set to 20 by default 200
POSTGRES_USER postgres PostgreSQL database username. platon
POSTGRES_PASSWORD postgres PostgreSQL database password. test
POSTGRES_DB postgres PostgreSQL database name. platon
PG_DATA postgres PostgreSQL data directory. PG_DATA=/var/lib/postgresql/data
PGADMIN_DEFAULT_EMAIL pgadmin PgAdmin default email for login. test@test.com
PGADMIN_DEFAULT_PASSWORD pgadmin PgAdmin default password for login. test
DB_NAME api Database name for the API service. platon_db
DB_USERNAME api Database username for the API service. platon
DB_PASSWORD api Database password for the API service. test
DB_HOST api Database host for the API service. localhost
DB_PORT api Database port for the API service. 5432
REDIS_HOST api Sets NestJs REDIS_HOST value setting localhost
REDIS_PORT api Sets NestJs REDIS_PORT value setting 6379
SECRET_KEY api Secret key for the API service. secret
PASSWORD_SALT api Secret key for the API service. 10
JWT_ACCESS_TOKEN_LIFETIME api Access token lifetime for JWT authentication. 7d
JWT_REFRESH_TOKEN_LIFETIME api Refresh token lifetime for JWT authentication. 7d
FILES_CACHE_LIFETIME api Duration of cacheable files in seconds. 604800 (7 days)
GRAPHQL_PLAYGROUND api Enable/disable GraphQL Playground. true
SANDBOX_URL api Defines python sandbox url. http://localhost:7000
SANDBOX_ENV_LIFESPAN api Value in seconds that determins for how long node sandbox env files should be kept. 604800 (7 days)
SERVER_NAME nginx Defines nginx server name. localhost

Codebase Structure

The platform's codebase is organized into a series of libraries and applications within the Nx workspace. This modular design allows for efficient code organization, reusability, and separation of concerns. The main categories of libraries are:

Each library is organised intro 3 sub-libs :

You can visualize the dependancy graph by running yarn dep-graph command.

Key Libraries and Frameworks

This project is built using a variety of key libraries and frameworks that provide the necessary functionality for the application. In this section, we will discuss the most important libraries and frameworks used, as well as their role in the project.

Development Workflow

Scripts

The bin folder contains a collection of scripts to perform various tasks related to the platform's development, deployment, and maintenance. These scripts are organized into subfolders based on their purpose, and they are designed to streamline the development process.

Testing

The test script in the package.json file allows developers to run tests for the Platon project. Tests help ensure that the code is working correctly and is of high quality. The tests are a part of the Continuous integration pipeline thanks to Github Actions and are runned before any merge to the master branch.

yarn test

The test script leverages Nx to run tests across all the affected applications and libraries within the workspace. It also generates code coverage reports and uses ChromeHeadless browser for testing.

Linting and Formatting

Linting helps in maintaining a consistent code style and detecting potential issues in the codebase. In this project, the linting process is set up using ESLint, Nx, and Angular ESLint.

To run the linting process, you can use the following commands:

In addition to linting, formatting your code is also essential for maintaining a clean and consistent codebase. Prettier is a popular code formatting tool that can be integrated into your project's development workflow.

Prettier automatically enforces a consistent code style by parsing your code and reformatting it according to predefined rules. It helps eliminate debates about code formatting and ensures that all developers working on the project follow the same formatting guidelines.

To run the formatting process, you can use the following commands:

These scripts will analyze the codebase and provide a report of any linting issues found, helping you maintain a clean and consistent code style across the project.

Deployment

On-premise

If you plan to use a custom ssl files instead, update the docker-compose and the nginx conf by defining the path to your files.

Cloud

[TODO]

CI Pipeline

graph TD
    A[Pull Request to main branch] --> B{CI Workflow}
    B --> C[Prepare Job]
    B --> D[Build Job]
    B --> E[Lint Job]
    B --> F[Test Job]

    C --> C1[Checkout Code]
    C --> C2[Setup Yarn]

    D --> D1[Checkout Code]
    D --> D2[Setup Yarn]
    D --> D3[Set NX SHAs]
    D --> D4[Generate GraphQL Types]
    D --> D5[Run affected:build]

    E --> E1[Checkout Code]
    E --> E2[Setup Yarn]
    E --> E3[Set NX SHAs]
    E --> E4[Run affected:lint]

    F --> F1[Checkout Code]
    F --> F2[Setup Yarn]
    F --> F3[Set NX SHAs]
    F --> F4[Run affected:test]
    F --> F5[Upload coverage to Codecov]

    C --> D
    C --> E
    C --> F

    subgraph "Environment"
    G[Node.js v22]
    end

    subgraph "Triggered by"
    H[Pull Request to main]
    I[Manual workflow dispatch]
    end

This diagram provides a clear visual representation of the CI process as defined in your ci.yml file.

  1. The workflow is triggered by pull requests to the main branch or manual workflow dispatch.

  2. It uses Node.js version 22 as specified in the environment variables.

  3. There are four main jobs: Prepare, Build, Lint, and Test.

  4. The Prepare job is a prerequisite for the other three jobs.

  5. Each job includes steps for checking out the code and setting up Yarn.

  6. The Build, Lint, and Test jobs use NX to determine affected projects and run their respective commands.

  7. The Build job includes an additional step to generate GraphQL types.

  8. The Test job includes a final step to upload coverage to Codecov.

Github Home page

The homepage of the project is hosted at https://cisstech.github.io/platon/

yarn build:github
yarn publish:github

Documentation

Documentation is hosted at : https://cisstech.github.io/platon/docs

There is also a self hosted version of the documentation that runs alongside of the application thanks to nginx reverse proxy at /docs/main

In development mode the documentation can be served using the following command :

yarn serve:docs

In production mode, nginx serve the documentation as static files inside the docker container

Before serving the docs, you should run yarn command inside ./apps/docs.

Contributing

Contributions are always welcome.

Please read our CONTRIBUTING.md first. You can submit any ideas as pull requests or as GitHub issues.

Please just make sure that ...

Your code style matches with the rest of the project

Unit tests pass

Linter passes

License

CeCILL-B