CPT202_GMS

Official repository of the CPT202 Group Management System

Code style hint

• format before commit (Code > Auto format code)

• Use raise to break long if else for better readability and compatibility for future change Example:

  # Better practice
  if user_should_not_do_this_due_to_a:
      raise Exception("No, you can't because A")
      
  if user_should_not_do_this_due_to_b:
      raise Exception("No, you can't because B")
      
  result = continue_normal_procedure()
  return result
  
  # Not so good
  if user_can_do_this:
      result = continue_normal_procedure()
      return result
  elif case_a:
      raise Exception("No, you can't because A")
  elif case_b:
      raise Exception("No, you can't because B")
  

• Remove TODO keyword from comment if task completed

Deployment instruction

The project is docker ready, using docker-compose for deployment by default.

Dockerfiles are located at src/docker/.

The project deployment is tested under Ubuntu 20.04, and the use of a Linux server is recommended.

Install docker on the server

Install docker on the production server by following the official guide Get Docker.

Method 1: Deploy with continuous integration (Recommended)

The project uses GitHub Actions for continuous integration

Add secrets

On the GitHub repository page, navigate to Settings > Secrets

Add the following secrets:

name	content	example
ADMIN_USERNAME	admin user name, must be in email format	superuser@gms.com
ADMIN_PASSWORD	admin initial password	foo
MYSQL_DATABASE	database name	gms
MYSQL_USER	mysql username	gms
MYSQL_PASSWORD	mysql user password	buz
MYSQL_ROOT_PASSWORD	mysql root password	bar
JWT_PUBKEY	public key for JWT	-----BEGIN PUBLIC KEY----- ... -----END PUBLIC KEY-----
JWT_KEY	private key for JWT	-----BEGIN RSA PRIVATE KEY----- ... -----END RSA PRIVATE KEY-----
DOMAIN_CERT_FULLCHAIN	TLS certificate for the site	-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----
DOMAIN_CERT_KEY	TLS key file	-----BEGIN EC PARAMETERS----- ... -----END EC PARAMETERS----- -----BEGIN EC PRIVATE KEY----- ... -----END EC PRIVATE KEY-----
SSH_KEY	private key of the remote host	-----BEGIN RSA PRIVATE KEY----- ... -----END RSA PRIVATE KEY-----
SSH_USER_HOST	username and hostname for ssh connection	alice@gms.example.com

Run CI job

Navigate to Actions > Workflows > CI, click run workflow.

Method 2: Deploy manually

Generate JWT keypair

Place the JWT keypair at src/backend/config/jwt/ and overwrite the example file.

The default algorithm for the key is RS256, and can be generated by the following commands:

ssh-keygen -t rsa -b 4096 -m PEM -f jwt.key
# Don't add passphrase
openssl rsa -in jwt.key -pubout -outform PEM -out jwt.key.pub

For security reason, do NOT use the example keypair in the production environment.

Modify backend configuration

Backend configuration file: src/backend/config/app_config.yml

Please refer to the inline comment for explanations

Setup MySQL

In src/docker/config/docker-compose.yml:

• Set the value of MYSQL_ROOT_PASSWORD MYSQL_USER MYSQL_PASSWORD MYSQL_DATABASE

In src/backend/config/app_config.yml:

• Set the value of mysql_host to "mysql", which is the container name set in docker-compose.yml
• Set the value of mysql_database, mysql_user, mysql_password to the same value as the ones in docker-compose.yml

Prepare TLS certification for HTTPS

Place the following files:

• Public cert(NGINX fullchain): src/docker/config/cert/fullchain.cer
• Private key: src/docker/config/cert/key.pem

Modify nginx configuration (optional)

Configuration file: src/docker/config/nginx.conf

Compile the webpage

Install NodeJS

Follow the official guide Download node

Install yarn

Follow the official guide Yarn installation

Install node modules and build

With src/web as working directory:

yarn install
yarn build

The static web file should be outputted to src/web/dist

Deploy with docker-compose

Install docker(optional) and docker-compose

Install docker on the local machine by following the official guide Get Docker. Install docker-compose on the local machine by following the official guide Install Compose

Setup remote context for docker-compose

docker context create remote ‐‐docker "host=ssh://production_server"

Confirm settings by using docker ‐‐context remote ps

Run container on remote

Run in foreground

docker-compose --context remote up

Run with daemon

docker-compose --context remote up -d

To shut down the service

docker-compose --context remote down

Update containers

Rebuild all image

docker-compose --context remote build

Rebuild image of specific service

docker-compose --context remote build <service>

Rebuild and run

docker-compose --context remote up --force-recreate --build -d

Remove unused images

docker --context remote image prune -a

Notes on possible docker-compose problems

docker-compose not respect ~/.ssh/config

Use ssh-agent login as a workaround

# In case you get the error 'Could not open a connection to your authentication agent.'
eval "$(ssh-agent)"

ssh-add -k /path/to/server/keyfile
docker context create remote --docker "host=ssh://user@hostname:port"

ERROR: Context 'remote' not found

switch context back and forth:

docker use context remote
docker use context default

docker-compose over SSH raises ChannelException(2, 'Connect failed')

In /etc/ssh/sshd_config of the docker host, set MaxSessions to 30

docker insanely resource usage when publishing the port range

In /etc/docker/daemon.json of the docker host, add "userland-proxy": false

docker-compose raises ssh: /tmp/_MEImZgOCk/libcrypto.so.1.1: version `OPENSSL_1_1_1' not found

export COMPOSE_PARAMIKO_SSH=1

Deploy with docker-compose on a host without docker-cli

export COMPOSE_DOCKER_CLI_BUILD=0