KSI Web frontend

This project was build upon the Angular framework as an frontend for the backend server. A knowledge of the Angular tutorial - Tour of the heroes - should be enough to make changes and improvements.

Table of content

• 1 Clone
• 2 Running
• 3 Building
• 4 Code structure
  • 4.1 Application source
    • 4.1.1 Angular structures and models
    • 4.1.2 Styles
    • 4.1.3 Application utilities
• 5 Project utilities
  • 5.1 gen-api.sh
  • 5.2 gen-changelog.sh
  • 5.3 gen-scss-theme.sh
  • 5.4 gen-icons.sh
• 6 Deployment
• 7 Localization

1 Clone

git clone https://github.com/fi-ksi/web-frontend-angular.git &&
cd web-frontend-angular &&
npm install

2 Running

To start the development server, use npm run start.

3 Building

To build for:

• testing server: npm run build.kyzikos

• production server: npm run build.kleobis

Note: these builds are automatically performed when automatic deployment is used

4 Code structure

All source code that is direct part of the final applications is to be found inside the src directory:

• assets - images, fonts, icons and internalization texts in respective sub-directories
• cgi-bin - auto-deployment script
• environemnts - see Angular docs
• routes - see Localization
• src/api - auto generated by gen-api.sh, more below
• src/app - the source code of the web application itself

4.1 Application source

4.1.1 Angular structures and models

Sub-directories are named after the Angular structure, that they contain - components, pipes, services. These sub-directories are then structured by their Angular module. If the structure is to be used in more than one module, the shared module should be used. For easier refactoring, pipes and services should export everything by using index.ts.

The models sub-directory is for storing interfaces that are to be used across multiple other files.

4.1.2 Styles

The styles sub-directory contains following files:

• colors.scss - color palette, only these colors are to be used in the application; all colors should be referenced by their name
• theme.scss - here are defined theme-specific variables, see below
• vars.scss - defines constants for unified design throughout the application - e.g. margin and padding sizes
• mixins.scss - frequently used styles between multiple components

4.1.3 Application utilities

The util/ sub-directory contains helper classes and functions - e. g. universal MappedFormControl (used in date input) and function for rewriting asset URL from the old frontend location.

5 Project utilities

Utilities are located inside the util/ directory, containing following files:

5.1 gen-api.sh

• executed by npm run gen.api

gen-api.sh takes swagger.json produced by backend swagger project. Both projects need to be cloned to the same directory.

Based on the swagger definition, it generates API service and models inside the src/api/ folder.

A few automatics fixes to the generated code are then made by this util.

5.2 gen-changelog.sh

• executed by npm run gen.changelog

gen-changelog.sh takes git's log and saves this information into src/assets/changelog/ directory. This is then used by the changelog modal inside the application.

5.3 gen-scss-theme.sh

executed by npm run gen.theme

gen-scss-theme.sh generates scss variables based on src/app/styles/theme.scss and saves them into the same file under AUTO-GENERATED section. for usage inside the application. SCSS variables are safer than regular css variables because the compiler throws error if used variable is undefined.

5.4 gen-icons.sh

executed by npm run gen.icons

gen-icons.sh takes main .svg icon from src/assets/img/icon.svg and generates all required .png icons under src/assets/icons for PWA.

6 Deployment

TL;DR: After merging PR to main, you can run following commands to start deployment on prod: git checkout main && git pull && git checkout prod-kleobis && git rebase main && git push && git checkout main.

Automatic deploy is executed based on which branch is pushed into. To see which branch deploys where, take a look inside the .github/workflows directory. Most important branches are:

• prod-kleobis that is deployed on the ksi.fi.muni.cz production environment
• dev-kyzikos that is deployed on the kyzikos.fi.muni.cz development environment (accessible only from FI network or VPN)

For the deployment to be successful, a script cgi-bin/dist-update.sh must already exist on the target server and be executable (after first successful deploy, this script is automatically updated). Following project secrets must exist (their real name differs by the used target server):

• DEPLOY_USER - username for the HTTP auth
• DEPLOY_PASSWORD - password for the HTTP auth
• PROD_DEPLOY_URL - HTTP URL of the dist-update.sh script on the target server

Also, if the name or owner of the repository is changed, be sure to reflect this change inside the cgi-bin/dist-update.sh script by modifying its variables - GITHUB_OWNER and GITHUB_REPOSITORY.

7 Localization

The source code is written in English, but the web itself is in Czech. This is possible by using ngx-translate package. All texts (except a few exceptions) are saved inside src/assets/cs.json.

The routes are also translated by using fileReplacements inside angular.json file. Raw values can be found inside src/routes/.

8 Logging

You can find the logs of all HTTP requests (and other events like incorrect password, cheating) including the IP address and the ID of the user making the request in /var/log/gunicorn/naskoc-backend.log.