/flat-server

A Node.js server for the Agora Flat open source classroom.

Primary LanguageTypeScriptMIT LicenseMIT

Agora Flat Server

Project flat-server is a Node.js server for the Agora Flat open source classroom.

中文

Features

  • Login via
  • Wechat
  • Github
  • Google
  • Room scheduling
    • Ordinary rooms
    • Periodic rooms
  • Signing tokens for Whiteboard, Real-time video/audio chat(RTC), Real-time messaging(RTM)
  • Cloud recording and replaying
  • Cloud Storage for multi-media courseware

Develop Locally

Execute the following steps to run flat-server:

Installation

  1. Fork this repo so that Github Actions can work properly.
  2. Then git clone the forked repo to local.
  3. At project root:
    yarn install --frozen-lockfile

Setup Environment

  1. Create two files config/.env.development.local and config/.env.production.local.
  2. Add environment variables following the config/.env.default format.

Setup MySQL and Redis

  1. You may install Docker locally if you don't have a remote MySQL and Redis.
  2. After Docker is installed, pick a location and create a directory for Database. e.g. mkdir -p ~/Data/Docker/MySQL ~/Data/Docker/Redis
  3. Setup MySQL and Redis base on the .env.* file we just created. For example let's say we have a .env.* containing the following configs:
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
# Redis password
REDIS_PASSWORD=123456
# Can also be other db name
REDIS_DB=0

MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_USER=root
# MySQL password
MYSQL_PASSWORD=123456
# Can also be other db name
MYSQL_DB=flat_server

MySQL

  1. Replace the (value of xxx) with actual values and run the following commands: (Note the ; in the end)
    cd ~/Data/Docker/MySQL
    docker run -dit -p 3306:3306 --name mysql --restart always -v `pwd`/data:/var/lib/mysql -v `pwd`/conf.d:/etc/mysql/conf.d -e MYSQL_ROOT_PASSWORD=(value of MYSQL_PASSWORD) mysql
    docker exec -it mysql bash
    mysql -uroot -p (value of MYSQL_PASSWORD)
    CREATE DATABASE (value of MYSQL_DB);
  2. Find createConnection in file src/v1/thirdPartyService/TypeORMService.ts, add a property synchronize: true to the config object. This option is for synchronizing tables and fields to database.
  3. Execute node ./dist/index.js.
  4. After finished, delete synchronize: true. This property is only needed when database fields are altered.

Redis

Replace the (value of xxx) with actual values and run the following commands:

cd ~/Data/Docker/Redis
docker run -dit -p 6379:6379 --name redis -v `pwd`/data:/data -v `pwd`/conf:/usr/local/etc/redis --restart always redis --requirepass "(value of REDIS_PASSWORD)"

Run the Project

  1. Execute at project root:
    yarn run start
  2. Open another terminal and execute at project root:
    node ./dist/index.js

You should see ready on http://0.0.0.0:80 if everything is OK.

Deployment

Deployment is not needed for local development. If you want to bring the server up online, deploy anyway you like. For example through Github Action:

  1. If you forked this repo as user_name/flat-server then go to https://github.com/user_name/flat-server/settings/secrets/actions and add the same content of .env.* to Action secrets.
  2. Additionally add the DOCKERHUB_* and SSH_* variables. See the the last section of Environment Variables Reference bellow.

Environment Variables Reference

Variable Name Description Note
SERVER_PORT Server port e.g. 8087
REDIS_HOST Redis host e.g. 127.0.0.1
REDIS_PORT Redis port e.g. 6379
REDIS_PASSWORD Redis password
REDIS_DB Redis db name e.g. 0
MYSQL_HOST MySQL host e.g. 127.0.0.1
MYSQL_PORT MySQL port e.g. 3306
MYSQL_USER MySQL user name e.g. root
MYSQL_PASSWORD MySQL password
MYSQL_DB MySQL database e.g. flat_server
JWT_SECRET JWT secret
JWT_ALGORITHMS JWT crypto algorithms See Algorithms supported
LOG_PATHNAME Log path name e.g: {{PROJECT_DIR}}/logs. See env variable
LOG_FILENAME Log file name e.g: {{DAY_DATE}}. See env variable
METRICS_ENABLED enable prometheus metrics Default: false, see: fastify-metrics
METRICS_ENDPOINT metrics endpoint Default: /metrics.
METRICS_PORT metrics http server port Default: 0, if metrics port eq 0, metrics server will register endpoint route on flat-server
CLOUD_STORAGE_CONCURRENT Maximum count of Cloud Storage uploading files Default: 3
CLOUD_STORAGE_SINGLE_FILE_SIZE Maximum size of a Cloud Storage file Default: 524288000 (500M)
CLOUD_STORAGE_TOTAL_SIZE Maximum Cloud Storage size of a user Default: 2147483648 (2G)
CLOUD_STORAGE_PREFIX_PATH Cloud Storage upload path prefix Default: cloud-storage (No / prefix or suffix)
CLOUD_STORAGE_ALLOW_FILE_SUFFIX Cloud Storage supported file extensions Default: ppt,pptx,doc,docx,pdf,png,jpg,jpeg,gif,mp3,mp4,ice
CLOUD_STORAGE_ALLOW_URL_FILE_SUFFIX Cloud Storage supported file url extensions Default:vf
WEB_WECHAT_APP_ID Wechat Open Platform App ID
WEB_WECHAT_APP_SECRET Wechat Open Platform App Secret
MOBILE_WECHAT_APP_ID Wechat Open Platform App ID
MOBILE_WECHAT_APP_SECRET Wechat Open Platform App Secret
GITHUB_CLIENT_ID Github Client ID See Authorizing OAuth Apps
GITHUB_CLIENT_SECRET Github Client Secret See Authorizing OAuth Apps
AGORA_APP_ID Agora App ID For RTC and RTM. See Use an App ID for authentication
AGORA_APP_CERTIFICATE Agora App Certificate See Enable the App Certificate
AGORA_RESTFUL_ID Agora RESTful ID For classroom replaying. See Restful Authentication
AGORA_RESTFUL_SECRET Agora RESTful Secret See Restful Authentication
AGORA_OSS_VENDOR Agora Cloud Recording OSS For storing RTC Cloud Recording media files. See Cloud Recording Start -> Schema -> clientRequest -> storageConfig
AGORA_OSS_ACCESS_KEY_ID Agora Cloud Recording OSS As above
AGORA_OSS_ACCESS_KEY_SECRET Agora Cloud Recording OSS As above
AGORA_OSS_REGION Agora Cloud Recording OSS As above
AGORA_OSS_BUCKET Agora Cloud Recording OSS As above
AGORA_OSS_FOLDER Agora Cloud Recording OSS As above
AGORA_OSS_PREFIX Agora Cloud Recording OSS As above
NETLESS_ACCESS_KEY Netless Whiteboard AK See Projects and permissions
NETLESS_SECRET_ACCESS_KEY Netless Whiteboard SK See Projects and permissions
ALIBABA_CLOUD_OSS_ACCESS_KEY Alibaba Cloud OSS AK For storing multi-media courseware. See AccessKey
ALIBABA_CLOUD_OSS_ACCESS_KEY_SECRET Alibaba Cloud OSS SK As Above
ALIBABA_CLOUD_OSS_BUCKET Alibaba Cloud OSS bucket See Bucket
ALIBABA_CLOUD_OSS_REGION Alibaba Cloud OSS region See Region

If you need to deploy to a remote server, add the following variables additionally:

Variable Name Description Note
DOCKERHUB_USERNAME Your hub.docker.com user name
DOCKERHUB_TOKEN token generated from hub.docker setting page
SSH_HOST SSH host
SSH_USERNAME SSH user name
SSH_KEY SSH key Generate a secret key with ssh-keygen -t rsa -b 4096 (Starts with -----BEGIN OPENSSH PRIVATE KEY-----). Then in the server, add the ssh public key to ~/.ssh/authorized_keys
SSH_PORT SSH port

Tech Stack