Out of the box, Classy's default behaviour should suit most courses; however, sometimes custom views and endpoints are necessary to support internal course operations.
Classy consists of two TypeScript applications: AutoTest and Portal. Only Portal is customizable at this time. Portal consists of an MVC frontend and a REST-based API backend application. Docker services and Nginx configuration can also be customized to provide new services on your Classy server that are accessible via HTTP (ie. https://cs999.students.cs.ubc.ca/my-new-docker-service).
The directory structure of a plugin:
myPlugin/
├── docker/
│ └── docker-compose.override.yml
├── nginx/
│ └── nginx.rconf
└── portal/
├── backend/
│ ├── CustomCourseController.ts
│ └── CustomCourseRoutes.ts
└── frontend/
├── CustomAdminView.ts
├── CustomStudentView.ts
└── html/
├── admin.html
├── landing.html
└── ...
You are responsible for managing the new plugin code that you create. Be careful to namespace and develop your files to ensure that down streaming changes from ubccpsc/classy is easy and effortless. You can assume that the same files in the default project will always continue to exist.
- Create a new (empty) GitHub repository.
- Clone the repository onto your local filesystem:
git clone https://github.com/myUsername/myPlugin - Copy the Classy
defaultplugin contents to your local filesystem directory:cp -r /path/to/Classy/plugins/default/* ./myPlugin - Add the files to your new git repository:
cd myPlugin && git add . - Commit the files as starter template code:
git commit -m "Starter plugin code; default scaffolding" - Push the changes to GitHub:
git push
Do NOT remove the default portal folder project scaffolding from your project, as when Classy is integrated with a plugin, these project files will always be required. One can modify or add files to the portal folder.
- To begin customizing Classy, move your new plugin project in the Classy
pluginsfolder. - Ensure that the plugin folder is labelled the name of the plugin (ie. myPlugin).
- Update the
PLUGINvariable in the .env with the plugin name. (eg.PLUGIN=defaultbecomesPLUGIN=myPlugin) - Customize Portal Front-end (TypeScript View Models, HTML View Templates, and TypeScript Controllers)(MVC)
- Customize Portal Back-end (API Routes, Course Controller)
You may choose to remove the nginx and docker folder from the plugin project. These are only read when ./helper-scripts/bootstrap-plugin.sh is run in Step 3. The bootstrap-plugin.sh file copies plugin files into the proper locations in the Classy project to be built by Docker.
- Override/Add Docker services
- Modify Nginx Configuration file to support Docker changes.
These steps can be bypassed if your Classy plugin repository is public, and you have asked tech staff to implement your plugin after verifying that your plugin builds and runs successfully in your development environment. You alternatively may also provide an access token to tech staff if your repository is private.
All prior essential Classy server configurations, installations, and operations are managed by tech staff. Contact tech staff to get Classy setup for the first time.
- SSH into Classy remote box.
- Clone your plugin repository in the
classy/pluginsfolder path with the name of the plugin as the directory. - Update the
PLUGINvariable in the .env with the plugin name. (eg.PLUGIN=defaultbecomesPLUGIN=myPlugin). - Run
./helper-scripts/bootstrap-plugin.shfrom root Classy directory to copydocker-compose.override.ymlandnginx.rconffiles into appropriate locations. - Run
./opt/classy-scripts/fix-permissions - Run
docker compose buildfrom root Classy directory to build Dockerized production project. - Run
docker compose up -dto run Classy project in detached mode in production.
The application folder MUST contain a backend and frontend directory with the included necessary customized files. It is not possible to delete these files, as the application requires the files to be plugged into the application at runtime. You can, however, add additional TypeScript and HTML files to support your customization.
It is advisable that one does not override or extend functionality until one has at least learned and used Classy's default logic. Documentation for default Course Controller methods exist in the https://github.com/ubccpsc/classy/blob/main/packages/portal/backend/src/controllers/CourseController.ts file.
The Portal front-end and back-end applications use the classy/tsconfig.json file to compile TypeScript files into JavaScript files that can be run by Node JS. The front-end uses Webpack to further transpile the JavaScript files into a single file that is optimized for the browser.
The front-end and back-end both require valid TypeScript before they can be compiled. The root Classy tsconfig.json file maps referenced @frontend, @backend, and @common namespaces within the plugin files to the rest of the application dependency files during transpilation (front-end) or runtime (back-end). Avoid using relative location paths, as development and Dockerized production build paths may differ.
- The front-end inherits default functionality AdminView, AbstractStudentView.
- The default functionality is designed to work with the html/* folder file templates.
|
|----------------------------------
| |
| -------------
| - -
| - Default - <---- plugins/default/portal/frontend/CustomAdminView.ts
-------------------- - Front-End - plugins/default/portal/frontend/CustomStudentView.ts
- - **---------- Files - plugins/default/portal/frontend/html/*
- - -------------
- Classy -
- -
- - ------------
- - **---------- -
-------------------- - Default - <---- plugins/default/portal/backend/CustomCourseController.ts
| - Back-End - plugins/default/portal/backend/CustomCourseRoutes.ts
| - Files -
| ------------
| |
|----------------------------------
|
- CustomCourseController extends CourseController for defaults.
- CustomCourseRoutes.ts extends IREST for additional implementations. No route overrides are available.
- CustomAdminView.ts should extend AdminView to inherit default logic. Overrides are optional.
- CustomStudentView.ts should extend AbstractStudentView to inherit default logic. Overrides are optional.
- Default HTML files should be used with the logic above. How you change the HTML and the default behaviour is up to individual discretion.
|
|---------------------------------
| |
| -------------
| - -
| - Custom - <---- plugins/yourPlugin/portal/frontend/CustomAdminView.ts
-------------------- - Front-End - plugins/yourPlugin/portal/frontend/CustomStudentView.ts
- - **---------- Files - plugins/yourPlugin/portal/frontend/html/*
- - -------------
- Classy -
- -
- - ------------
- - **---------- -
-------------------- - Custom - <---- plugins/yourPlugin/portal/backend/CustomCourseController.ts
| - Back-End - plugins/yourPlugin/portal/backend/CustomCourseRoutes.ts
| - Files -
| ------------
| |
|---------------------------------
|
- CustomCourseController.ts should extend CourseController to inherit default functionality. Overrides are optional.
- CustomCourseRoutes.ts should extend IREST. IREST contains registerRoutes() hook to add new routes at Classy start.
The html/ folder should contain HTML files that are used by the Custom front-end CustomAdminView.ts and CustomStudentView.ts files.
As the CustomAdminView.ts and CustomStudentView.ts files inherit the default AdminView and AbstractStudentView classes, default MVC logic will be available at runtime. Overriding default functionality is based on the instructor's discretion and experience.
It is up to you to expand and build upon the default templates, while naming new files, to allow for easily mergeable upstream updates from the ubccpsc/Classy project. It is necessary to pull-in upstream changes before the new term starts for security and new features.
See Classy's default docker-compose.yml configuration: Classy Default docker-compose.yml.
Docker-compose will look in the docker-compose.override.yml file to override the default docker-compose.yml configuration. Docker-compose uses the classy/.env file to load stored environmental variable dependencies, which are needed during the Classy build process.
See how to override a Docker Compose file: Override a docker-compose.yml File.
Never commit the .env to source control. Do not override .env file in the custom docker-compose.override.yml file. Although it is possible to override the specified .env file in the default docker-compose.yml file, the original .env file is required to build and run Classy. SSH access can be requested from Tech-Staff to add additional environmental variable to the classy/.env file, rebuild, and launch Classy.
- Do not override the .env file location in the
docker-compose.override.ymlfile, as it will break the default Classy build. - Do not override the default services unless you know exactly what you are doing. Classy relies on the default configuration.
- If adding services that require new .env variables, add them to the server via SSH (or ask tech-staff to do it).
- Ensure that Docker-compose can build and run the Classy project locally.
- Ensure that your new services are secure (in the context of the new service and who is allowed to have access)
- If new services are introduced, where HTTP proxy/routing changes are needed, update the Nginx.conf file as needed.
The classy/.env file contains environmental variable dependencies used to build the Docker containers. References to the environmental variables can be seen in the docker-compose.yml file.
SSH access must be requested to modify the .env file manually. Alternatively, these variables can be provided to technical staff to ensure that any docker-compose.override.yml file can utilize environmental variables. The .env file path should not be overridden in the docker-compose.override.yml file, as it would not contain the default Classy environmental variable configurations.
`docker compose up`
|---------------------------------
| |
| |
| -------------
-------------------- - -
- - **---------- Default - <---- plugins/default/classy/docker-compose.override.yml
- - - Docker - <---- .env
- Classy - - Services -
- - -------------
- -
- -
--------------------
If a docker-compose.override.yml file exists, it will be read on the docker compose build and docker compose up commands. Services will be overridden and/or extended from defaults.
`docker compose up`
|---------------------------------
| |
| -------------
| - -
| - Default -
-------------------- - Docker -
- - **---------- Services - <---- docker-compose.yml (default services configuration)
- - ------------- <---- .env
- Classy -
- - -------------
- - - -
- - **---------- Custom - <---- docker-compose.yml (inherits Classy default service configuration)
-------------------- - Docker - <---- plugins/yourPlugin/docker-compose.override.yml (overrides docker-compose.yml and adds services)
- Services - <---- .env
-------------
The nginx.rconf has been modified to work with UBC operating requirements. Any customization requires that the nginx.rconf is used as the basis for any customizations to the nginx.conf file in your class-plugin project.
- Used the default
nginx.rconfconfiguration as a basis for any customizations. - Did NOT modify any of the SSL / Stapling rules without tech staff approval, which are required to ensure security.
- Implemented your own changes.
--------------------
- - -----------------
- - - -
- Classy - **---------- Nginx - <---- nginx.rconf (default nginx.conf configuration file)
- - - Configuration -
- - - -
- - -----------------
--------------------
-------------------- NOTE: Cannot override. It overwrites the original default configuration file. Ensure that you copy boilerplate from `classy-plugin` repository for security requirements.
- - -----------------
- - - -
- Classy - **---------- Nginx - <---- plugins/yourPlugin/nginx/nginx.rconf (overwrites default nginx.conf)
- - - Configuration -
- - - -
- - -----------------
--------------------