- Pre-Installation & Requirements
- Project Structure
- Development Environment
- Production Environment
- Tests
- Common Commands
In order to run the different apps the repository obvisously needs to get clone
and the required packages must be installed via npm install. This will install
everything that is needed for development and building the apps for production.
$ git clone git@github.com:SV-Vaihingen-Handball/svv-handball.git
$ cd svv-handball
$ npm install
$ npm install -g nx
$ npm install -g @angular/cliThe entire project is divided into different folders to ensure a generally clear structure. This is necessary because the repository contains all applications and tools and thus also many configuration files. To achieve this goal, Nrwl Nx is used, which helps to architect, test, and build the applications and libraries at any scale. Additionally the robust CLI, caching, dependency management and the fact that it is easy to manage different frameworks in one repo without any pain makes Nx realy helpful. The project is therefore structured as follows:
- Apps: The source and most of the configuration files of the different
applications are stored inside the
appsfolder. - Libraries: The
libsfolder contains libraries which are shared across multiple applications (eg. the Models/Interfaces) - Tools: Inside the tools folder are scripts for specific actions like seeding the database.
Besides the pre-installation process it is also necessary to run npm run seed
so the database is filled with dummy data. Additionally a user for the initial
login is created which is especially important for the API and the CMS application
because both are either completely or partially secured via a JWT-Authentication
mechanism.
$ npm run seed
# For the first authentication the created test user can be used.
# Email: test@test.de
# Password: testIn order to use the API in dev and production mode, a instance of an MongoDB server must be present. You can either install the current version locally via this installation guide or use the prepared docker compose file with the following command.
$ docker-compose up dbIn the current version state of the project both the API and the Express server which is serving the website are using a Redis server. The Redis server is mostly to improve the overall performance and response time by caching the created responses.
$ docker-compose up redisRun the following command in order to start the API in development mode. Navigate to http://localhost:3000/. The API will automatically reload if you change any of the source files.
$ npm run start:api:devFor testing purposes the API can also easily get started in production mode by building the application first and then running it via NodeJS.
$ npm run build:api
$ node dist/api/main.jsNote: In order to start the API an instance of MongoDB and Redis must be running.
Run the following command in order to start the CMS app in development mode. Navigate to http://localhost:4200/. The CMS will automatically reload if you change any of the source files.
npm run start:cms:devNote: In order to start the CMS application an instance of the API must be running.
Run the following command in order to start the website in development mode. Navigate to http://localhost:4201/. The website will automatically reload if you change any of the source files.
$ npm run start:website:devFor testing purposes the Website can also easily get started in production mode by building the application first and then running it via NodeJS.
$ npm run build:website
$ node dist/website/server/main.jsNote: In order to start the Website the API must be running as well as an instance of Redis.
The production server is currently running Debain 10 with NodeJS v14.15.5 and
npm v6.14.11.
In the production environment NGINX is used for managing and distributing the different applications. Simply follow this guide for installing NGINX. With the following commands the NGINX process can be managed:
$ sudo systemctl start nginx
$ sudo systemctl stop nginx
$ sudo systemctl restart nginx
$ sudo systemctl reload nginx
$ sudo systemctl status nginxNOTE: In the root folder of this repository lies a finalized configuration file which should be used.
To improve the interaction performance between the API and the Website, Redis is used for caching the responses. Follow this guide for installing Redis. With the following commands the Redis process can be managed:
$ sudo systemctl start redis
$ sudo systemctl stop redis
$ sudo systemctl restart redis
$ sudo systemctl status redisNOTE: In the root folder of this repository lies a finalized configuration file which should be used.
Obviously the API needs a place for storing the data which in this case is done with MongoDB. With this the installation is pretty simple and quick. In order to mange the MongoDB process the following commands can be used:
$ sudo systemctl start mongod
$ sudo systemctl stop mongod
$ sudo systemctl restart mongod
$ sudo systemctl status mongod$ npm run build:api
$ npm run build:cms
$ npm run build:websiteFor managing the different daemon processes we are using PM2 in production mode. This helps amongst other things to keep the different applications online 24/7. PM2 can be easily installed via npm:
$ npm install pm2 -gThe following commands will either start, stop restart or reload the process of the respective application:
# Website
$ npm run start:website:prod #Use this command only for the first time.
$ pm2 start website
$ pm2 stop website
$ pm2 reload website
$ pm2 delete website# API
$ npm run start:api:prod #Use this command only for the first time.
$ pm2 start api
$ pm2 stop api
$ pm2 reload api
$ pm2 delete apiNOTE: The CMS application is served staticly by NGINX and does not require to be managed by PM2
In the current state of the project, there are only tests for the API. In addition to the actual logic, these also test various validation cases and the interceptors used for the respective routes. So these tests are Unlike unit testing, which focuses on individual modules and classes. These tests are more like end-to-end (e2e) which are covering the interaction of classes and modules at a more aggregate level which will be closer to the kind of interaction that end-users will have with the whole system.
The individual test processes for the features always follow the same scheme. First the respective GET methods, the POST, the PUT and finally the DELETE methods are tested. The entire test process can be started with the following command.
$ npm run test:api| Name | Description |
|---|---|
| start:api:dev | Starts the API in development mode using the Angular Dev-Server |
| start:api:prod | Starts the API in production mode and initalizes the PM2 daemon |
| build:api | Builds the API for production mode which is required in order to perform the start:api:prod command |
| test:api | Starts the End-to-End tests for the API |
| Name | Description |
|---|---|
| start:cms:dev | Starts the CMS in development mode |
| start:cms:dev | Builds the API for production mode |
| Name | Description |
|---|---|
| start:website:dev | Starts the Website in development mode using the Angular Dev-Server |
| start:website:dev:ssr | Starts the Website in development mode using the implemented Express server |
| start:website:ssr | Starts the Express server in production mode which will serve the Website |
| start:website:prod | Starts the Website in production mode and initalizes the PM2 daemon |
| build:website:browser | Bundles only the parts which are shipped to the Browser |
| build:website:server | Bundles the Expres server |
| build:website | Bundles everthing that is needed to start the Express server in production mode |