SND SMP

Introduction

This SMI Portal is created to replace the V1 version for Signature Mail. It is a revamped version, which consists of the frontend (Angular 17), backend (Dotnet 8 Core C#), a background worker to process heavy tasks, a MySQL as database, and a dockerized FileServer called ChibiSafe. All these are running on their respective images using Docker (Except for the DB). The recommended server for this project is a Linux Server due to its flexibility, ease of use, and affordability.

SMP Information

• Architecture: Monolithic
• Database: MySQL
• Framework:
  • Backend: C# DotNet8
  • Frontend: Angular Framework 17
• Source Control: GitHub Enterprise
• Targeted Deployment Hub: Linux Server | Ubuntu 22.04 Jammy
• Recommended IDEs:
  • Backend: Visual Studio 2022 (DotNet8 Support) / Visual Studio Code
  • Frontend: Visual Studio Code
• Requirements:
  • Node.js
  • MySQL
  • DotNet8
  • Docker

Architecture

Database:

• Uses MySQL

Backend and Background Worker:

• Uses Docker to containerize the image.

Frontend:

• SMI Portal is containerized as an instance
• Will be accessed using a public URL

ChibiSafe File Server:

• Docker to containerize the image.

Guide

Below are the steps to guide you to run this project in the local environment.

Installing MySQL 8.0

This SMD Portal will be using MySQL as its database storage. Here are the steps to install MySQL on your local development machine.

1. Head to Community DL Page (dev.mysql.com) to download the installer. We are using the current latest version 8.0.36. Select the Windows x86-64bit installer.

2. Click on No thanks, just start my download to start your download.

3. Run the installer and accept and allow changes, then select Custom and click Next.

4. Select these product to be installed and click the arrow to the right.
   • MySQL Server 8.0.36 - X64
   • MySQL Workbench 8.0.36 - X64
   • MySQL Shell 8.0.36 - X64
   • MySQL Router 8.0.36 - X64

5. Confirm the list of product to be installed and then click Execute.

6. Wait for the installation to complete then click Next.

7. Then click Next to proceed to configure MySQL Server.

8. Use default settings then Next.

9. Proceed Next again.

10. Input your password. In this case my password is abcd1234.

11. Rename the services name if you wish or else just use default then Next.

12. Grant full access and proceed.

13. Click on Execute to apply all those configuration you just did.

14. After configuration successfully applied, click on Finish.

15. Then click on Next and proceed to use default configuration for MySQL Router setup.

16. You may check Start MySQL Workbench after setup to run the application after click on Finish to finalize MySQL installation.

17. Or you use Windows Key + S to open search on Windows and type in MySQL to open it.

18. Click on Local instance MySQL80. Additionally you may rename the connection name by right click Edit Connection to suit your project naming criteria.

19. Enter your password that we just configured just now. You may tick Save password in vault and the password will auto saved so you do not need to enter everytime you access MySQL.

In our case, the username is root and the password is abcd1234.

20. Click on Schemas and your database list will be listed on the left side.

Installing GitHub Desktop

The source control for this project is using GitHub Enterprise. If you do not have an account, go to GitHub Signup Page to create an account. Remember to use your company account. After you have created an account, request access to GitHub enterprise from your manager and provide your account name.

The guide below will be to install GitHub Desktop on your local machine and pull the project from the Hub.

1. Head over to this link to download the installer for GitHub Desktop.

2. Click on Skip this step to proceed.

3. Configure your information.

4. Once installed, you will see the screen below.

5. Go to File > Options or Ctrl + , to open GitHub Desktop Settings.

6. Head to Accounts and Sign-in to GitHub.com.

7. It will prompt you sign in using your browser. Click Continue with browser.

8. Key in the Username/Email address and Password of the account linked to the company’s GitHub Enterprise and click Sign in

9. After you sign in, it will redirect back to GitHub Desktop. If you have accepted to join GitHub enterprise from your company email, you will see coldarse with the available repos under it. Select "coldarse/SND.SMP" and click Clone.

10. Create a local path for the repo to clone to and click Clone.

11. After the cloning process is done, you will see the screen as below.

12. To open the project, got to Repository and select Show in Explorer or Ctrl + Shift + F.

13. This will open up the project folder in File Explorer. Double click the .sln file to open the solution in Visual Studio 2022.

14. Your project solution’s Solution Explorer should look something like that.

Installing Docker Desktop

In this project, we will utilize Docker to deploy our applications.

Below are the steps to install Docker Desktop on your local machine.

1. Head over to https://www.docker.com/products/docker-desktop/ and download Docker Desktop for windows

2. Click on the .exe file to open the installer.

3. You will see the Configuration page, you may uncheck Add shortcut to desktop if you do not wish for it to, but make sure to check Use WSL 2, this will enable you to run both Windows and Linux containers on your Windows machine. Click Ok.

4. The installer will now start installing Docker Desktop. The installation will take a while.

5. After the installation is complete, it will prompt you to restart your machine. Click Close and restart.

6. After your machine has restarted, Docker Desktop will automatically pop up its Service Agreement. You may read through the agreement if you wish and select Accept.

7. If you have not previously configured Docker on your machine or have not run any linux related VMs before, you will be prompted to update/install WSL kernel. Follow the link and you will be brought the Step 4 in the link.

8. Click on the link to download the installer for the latest WSL kernel.

9. Click on the .msi file to open the installer.

10. You will be prompted a pop-up to install the WSL. Click Next.

11. It will be a quick installation. Click Finish.

12. Use Windows Key + S to open search on Windows and type in Windows PowerShell and Run As Administrator.

13. Type in the command wsl --set-default-version 2 to set the default version of WSL.

14. Open Docker Desktop if it’s not already open and you shall see Docker Desktop Starting and you shall see a green bar at the bottom left when it has started.

Setting up ChibiSafe File Server

This project uses a file server called ChibiSafe, which provides its own authorization, APIs, and documentation to store any files uploaded to the server for easy retrieval and keepsake.

It uses Docker to run so in this setup, a docker-compose.yml file will be used to create a container instance in your own local machine to host this file server.

1. Navigate to SND.SMP > chibisafe, and within it will contain the docker-compose.yml file.

2. The file should contain the following.

version: "3.7"

services:
  chibisafe:
    image: chibisafe/chibisafe:v.5.6.10
    container_name: chibisafe
    volumes:
      - ./database:/home/node/chibisafe/database:rw
      - ./uploads:/home/node/chibisafe/uploads:rw
      - ./logs:/home/node/chibisafe/logs:rw
    ports:
      - 24424:8000
    restart: always

3. To explain this YAML file simply, it is the requirements for making the container run properly.

4. As you can see under the services tab, we are creating a service called chibisafe with the image that will be pull from the ChibiSafe's DockerHub Repository.

5. We are naming the container name to be chibisafe.

6. In the volumes section, we are creating 3 essential directories:

• database: This is the DB for the file server.
• uploads: This is the place where it will store the files uploaded to the server.
• logs: This directory contains the logs generated by the file server.

7. This file server runs on port 24424 by default, which will route to the port 8000 internally.

8. We are also setting the restart to always to auto-restart whenever it crashes. This will make sure the file server is always up.

9. To run this on your local device, assuming you have already installed and configured Docker to your usage, we are going to open up PowerShell and head to this directory.

10. To run this, simply run the command docker compose up -d.

11. The parameter -d is to make sure the container is running in the background.

12. You shall see it begin to pull the image from the ChibiSafe Repository (if you don't have the image on your local machine)

13. And when its done pulling, it will start on its own.

14. If you see the container has been started like the image above, you can now head over to link and you will see the page below.

15. On the top right corner, click Login / Register.

16. In the Username and Password key in admin on both and click Sign In.

17. You are now logged in to the file server as an admin.

18. You can select the Credentials menu under Account to change your admin password.

19. This project uses the admin account, so to use this we will need the key for the APIs to verify. Click on Request new API key and you will be prompted that this will overwrite the old key, select Confirm to generate.

20. Hover over the textbox to show your generated key and copy it.

21. If you have done the database migration, you will need to insert this into the applicationsettings table.

22. Head over to MySQL and locate the applicationsettings table. Right click and Select Rows

23. Insert/Update the below 2 records in this table if you do not already have them.

• ChibiURL : http://localhost:24424/api/
• ChibiKey : {YourGeneratedToken}

24. On the bottom right corner, click Apply and Apply in the prompt to execute this query for change.

Installing node version manager

Node Version Manager (NVM), as the name implies, is a tool for managing Node versions on your device.

NVM allows you to install different versions of Node, and switch between these versions depending on the project that you're working on via the command line.

To download, go to nvm-windows. The current latest version as of today (April 2024) is 1.1.12.

1. Scroll down and click on the Download Now! button.

2. Then scroll down and click on nvm-setup.exe under Assets.

3. Complete the installation wizard. When done, you can confirm that nvm has been installed by running nvm -v on Command Prompt (CMD).

4. Run this command nvm install 20.9.0 to install nodejs version 20.9.0 which compatible with our current project version.

5. After installation succeeded, run this command nvm use 20.0.0 to use the version you just installed.

6. To check current version, run nvm current.

EF Core Migration to MySQL

This project already had a build in ef core migration script pre-written. All you need to do is just run the projects and everything will be done automatically.

1. Expand the src folder then expand SND.SMP.Migrator and finally click on appsettings.json

2. Comment the live server by adding // on the start of the code then copy the code below at a new line and save it.

 "Default": "server=localhost;port=3306;database=SMPDb;uid=root;pwd=abcd1234;"

3. On middle top of your visual studio, there is a drop down list for projects to run. Choose SND.SMP.Migrator.

4. Then click on the start button located at right of the drop down list.

5. A command prompt will then pop out and ask do you want to perform this migration. Type Y then enter.

6. After that wait for the migration to complete and then press ENTER to exit.

7. Close the command prompt.

8. Head to MySQL Workbench and connect to your database.

9. You will notice that on your left, your database had created.

Setting up swagger

1. Expand the src folder then expand SND.SMP.Web.Host and finally click on appsettings.json

2. Comment the live server by adding // on the start of the code then copy the code below at a new line and save it.

 "Default": "server=localhost;port=3306;database=SMPDb;uid=root;pwd=abcd1234;"

3. On middle top of your visual studio, there is a drop down list for projects to run. Choose SND.SMP.Web.Host.

4. Then click on the start button located at right of the drop down list.

5. Wait for the swagger website to launch itself. This will serve as the prove that you had successfully setup swagger.

Setting up Angular (UI)

To setup Frontend, we will be using Visual Studio Code. You can use Microsoft Visual Studio too to run angular too.

1. Launch Visual Studio Code.

2. Go to File > Open Folder or Ctrl+K + Ctrl+O to open folder.

3. Navigate to your project folder and search for angular folder then Select Folder.

4. Visual Studio Code will load your angular project folder.

5. Right click any of the file and then Open in Integrated Terminal.

6. After that enter npm install to install all the necessary packages.

7. If you are having npm ERR! issue, this is due to dependency issue. You can just ignore the error with npm install --force command.

8. Then, after downloaded relevant packages, start the project by typing yarn start.

9. [Optional] If you encounter error as shown from images below, it is due to your yarn.lock content does not match with your package.json else skip to step 13.

10. [Optional] Ctrl+C to stop the terminal and then right click yarn.lock files and delete it.

11. Next, type in yarn to generate a new yarn.lock file.

12. After finish rebuilding yarn.lock type in yarn start to build and start your angular. Wait for it to finish compile. It may take a while.

13. When Visual Studio Code has done building the project, click on http://localhost:4200 and it will open up in your default browser.

14. This is the login page. The id is admin and password is 123qwe.

15. You have successfully setup the frontend. Test out the CRUD of your services to see if they are working properly.