Platform for Learning and Teaching online.
This repository is the entry point to the PLaTon platform for developers, it's the one you should clone to start contributing to PLaTon or to deploy it on your server.
Also please create your issues on this repository and we will transfer them to the right repository.
In order to run PLaTon you'll need the following tools installed
Docker
Docker Compose
OpenSSL
ca-certificates
(only on a linux system)Visual Studio Code
node 12.22.1 & npm 6.14.12
(We recomend using nvm to install specific version of node https://github.com/nvm-sh/nvm)
We recommend you to install the Docker and the Remote development extensions on vscode. The first one will allow you to use docker inside the editor and the second to use docker as a full-featured development environment.
You will be asked to install the extensions on the first time you will open the project, but if not you can also display the recommendations by opening the command palette of vscode (
CTRL + P
on Linux andCMD + P
on Mac) then type the following text
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 withsudo
please read this guide.
You have Docker Compose installed by default with the new Docker Desktop app, to allow it to work with our script you must enable docker-compose to work with Docker Compose V2. (Preferences -> General -> Use Docker Compose V2)
Also if you are using docker for mac, we recommend you to increase the memory size to 4GB in the resources section of the docker dashboard.
Since the platform depends on multiple services like a PostgreSQL database, Elasticsearch, Python, Node, Angular and others projects of the organization... the development process is fully dockerized. All the coding, running, testing and deployment takes place inside docker containers so you don't have to install anything on your system except Docker
and Visual Studio Code
.
You are free to develop on the OS of your choice, it's does not matter thanks to docker, but we recommend you to choose a Linux or an OSX system since the project is fully tested on these two platforms.
-
First of all, you should clone this repository on your system using the following command
git clone https://github.com/PremierLangage/platon
-
Go to the
platon
directory and execute the./bin/install.sh
scriptcd platon ./bin/install.sh
This script will clone the repositories needed to run PLaTon outside of the current directory:
-
platon-server -> backend of the platform written with django.
-
platon-front -> frontend of the platform written with Angular
-
sandbox -> server to execute code inside of a secured and isolated environment, written with django.
This will give you the following directory structure:
platon/ ... platon-front/ ... platon-server/ ... sandbox/
After, it will generate some files like
.env
file into the current directoryconfig.json
file into../platon-server/platon/config.json
ssl
certificates intoserver/certs
- ...
Please continue reading this guide to learn more about all the generated files and directories.
-
-
Install node_modules
cd ../platon-front/ npm install
A 3 minutes download depending on your net-access.
-
Generate docker images of PLaTon services and run containers.
cd ../platon ./bin/docker-up.sh
The creation of the images may take some times on the first usage depending on your system setup.
-
Once all services starts, open the browser on
https://platon.dev
This will work because
platon.dev
host is added to the/etc/hosts/
file of your system by theinstall.sh
script and assl
certificate is generated under the directoryserver/certs
to be used by nginx.You have to wait for all the containers (specialy the
platon_app (app_1)
container that will compile angular components before running it) to be running before opening your browser.At this point, you will see an error in your browser like the following one:
The message and the way you will fix it might be different depending on the browser.
- On Firefox, you should open the page
about:config
in a new tab and toggle off thenetwork.stricttransportsecurity.preloadlist
setting then refresh the page, you will now see an option to bypass the warning.
-
On Chrome, click a blank section of the denial page. Using your keyboard, type
thisisunsafe
. This will add the website to a safe list, where you should not be prompted again. Strange steps, but it surely works! -
On Safari for mac, you should add
server/certs/platon.dev.crt
the Keychain app, then approve theplaton.dev
certificate by double click on it.
- On Firefox, you should open the page
In addition to these 3 scripts, the project contains other scripts placed in the bin folder:
Script | Description | When to use |
---|---|---|
docker-up.sh |
Create development docker images of the project and start all development containers. | When you wan't to run PLaTon in development mode |
docker-up.sh --prod |
Create production docker images of the project and start all production containers. | When you wan't to run PLaTon in production mode |
docker-down.sh |
Stop all running containers. | When you wan't to stop the docker containers |
sandbox.sh |
Start the sandbox development server. | When you wan't to use the features depending on a sandbox (must be used before docker-up.sh ) |
install.sh |
Clones the repositories and add some default config files (This script will not clone the repositories if you already have them and it will not override your config files). | Only once or when you pull a change from this repository. |
shell-api.sh |
Connect to the backend container. | To run manage.py commands for example (the containers must be started before in order to run this script)?-. |
shell-app.sh |
Connect to the frontend project container. | To run ng commands to run unitests for example (the containers must be started before in order to run this script). |
shell-postgres.sh |
Connect to the postgres database container. | To run psql commands to create a dump for example (the containers must be started before in order to run this script). |
Instead of developing directly on your host machine, or using the shell-* scripts, we recommend you to run the containers inside vscode. The projects are configured to install some useful vscode extensions.
https://code.visualstudio.com/docs/remote/attach-container
When you develop inside of a container, vscode will automatically config git from the config on the host system so please use git directly inside the containers instead of the host machine.
Also, it will recommend you to install some extensions based on the container your'e working on.
PLaTon is organized through different technical services:
- Django REST Framework to write a REST API.
- Django Channels to create websocket endpoints.
- Angular to create the frontend application of the platform.
- PostgreSQL to store the data of the platform.
- Elasticsearch to add a full text search feature to the platform.
- Celery to create automated tasks.
- Redis to add a caching layer on top of Django Channels and Celery.
- Nginx to serve all theses services on the same server using a reverse proxy system.
To use all these services at the same, PLaTon use Docker to run each service inside a container and connect them using a docker-compose file.
The following diagram represents the stack of the platform in a development environment.
In a development environment:
- Django will served on the port
8000
usingpython3 manage.py runserver
command (Django will also serve the static files and the media files). - Angular will be served on the port
7000
usingnpm start
command. - Nginx will listen on port
80
(http) and443
(https) to forward the requests to Django or Angular depending on the requested url prefix. - Postgres, Redis and Elasticsearch will listen on their own standard port.
- The sandbox is the only service that is not be dockerized. You must install it on your system and start it using
./bin/sandbox.sh
.
HOT reloading is enabled in this mode since angular and django are started using a dedicated webserver so any time a file change in the projects, the code will be recompiled. This works thanks to docker volumes (the source codes will be mounted inside the containers).
The following diagram represents the stack of the platform in a production environment.
In a production environment:
- Django will be served on port
8000
using Uvicorn. - Angular will be compiled a volume that is mounted inside the nginx container.
- Nginx will act as a reverse proxy like for the development environment. It will redirect api and websocket requests to uvicorn and will serve django static files and angular pages.
You might have experienced that using a lot of different ports is confusing while developping services locally: it often involves cross-origin resource sharing which need to be allowed. Cross-origin resource sharing let a domain access the data on an another one. When you need to access your data from a different domain, you need to allow this domain to query the data.
CORS is allowed in the settings of the django project.
The following table list all the environment variables defined inside the .env
file of the repository. This file allow to config the services of the docker-compose like the ports where the tools will be started.
This file is not versioned, it will be generated by the
./bin/install.sh
script. So if a future version of the repository adds a new environment variable, you should add it by yourself by comparing the local content of the file and the one comming from github.
Name | Service | Description | Default |
---|---|---|---|
COMPOSE_HTTP_TIMEOUT | docker | Increase docker build timeout which is set to 20 by default | 200 |
POSTGRES_USER | postgres | Owner of the database created inside the postgres service. | django |
POSTGRES_PASSWORD | postgres | Password of the database created inside the postgres service. | django_password |
POSTGRES_DB | postgres | Name of the database created inside the postgres service. | django_platon |
PG_DATA | postgres | Directory where to store the data inside the postgres service. | PG_DATA=/var/lib/postgresql/data |
DEBUG | api | Sets django's DEBUG value settings | true |
SECRET_KEY | api | Sets django's SECRET_KEY value settings | true |
| ALLOWED_HOSTS | api | Sets django's ALLOWED_HOSTS value setting | 127.0.0.1,localhost,platon.dev |
| DB_NAME | api | Sets django's DATABASES name value setting | django_platon |
| DB_USERNAME | api | Sets django's DATABASES name value setting | django |
| DB_PASSWORD | api | Sets django's DATABASES password value setting | django_password |
| DB_HOST | api | Sets django's DATABASES host value setting | postgres |
| DB_PORT | api | Sets django's DATABASES port value setting | 5432 |
| REDIS_HOST | api | Sets django's REDIS_HOST
value setting | redis |
| REDIS_PORT | api | Sets django's REDIS_PORT
value setting | 6379 |
| ELASTICSEARCH_HOST | api | Sets django's ELASTICSEARCH_HOST
value setting | elasticsearch |
| ELASTICSEARCH_PORT | api | Sets django's ELASTICSEARCH_PORT
value setting | 9200 |
There are two more environment variables defined dynamically inside the docker-compose files
SANDBOX_HOST
andSANDBOX_PORT
by the./bin/docker-up.sh
script.
During the execution of the install.sh
script, the file config.json
of this repository will be copied to platon-server/platon/config.json
. This file is not versioned in platon-server repo and it allow you to add some default data
to the database like users, lms...
Read through our contributing guidelines to learn about our submission process, coding rules and more.
Want to report a bug, contribute some code, or improve the platform? Read up on our guidelines for contributing and then check out one of our issues labeled as help wanted or submit a new one.
In order to contribute to the backend code, so you must follow the principles of REST API conventions as described here and apply it to Django REST Framework.
We have very precise rules over how our git commit messages can be formatted. Please read the convention here.