Second semester project (P2) for handling of personalized learning material recommendation based on learning preferences.
Below you will find a guide to set up for developing the P2 project on a windows system, as well as a style guide on writing code for the project.
For this guide it is expected that you use Linux (WSL), Visual Studio Code (VSCode) and Git.
WSL is a linux distrbution running within windows. This makes it a great candidate for the basis of a development environment.
VSCode is a powerful and practical text editor.
Git is a version control system, making it easier for the team to collaborate.
To connect to AAU's servers you will need Cisco AnyConnect to connect through VPN. Currently an issue exists where WSL does not work while connected with VPN. A fix is being researched.
Install Cisco AnyConnect from https://ssl-vpn1.aau.dk/ - Log in using your AAU credentials and 2F-authenticantion. Then login to the application at ssl-vpn1.aau.dk also with your AAU credentials.
While on AAUs VPN, open windows cmd and connect externally to AAUs system with ssh. Then cd to the part of the server where we are supposed to work.
ssh AAUusername@dat2c2-20.p2datsw.cs.aau.dk
cd /srv/www/dat2c2-20.p2datsw.cs.aau.dkInstall VSCode downloaded from here.
Open VSCode in windows and install the "Remote - WSL" extension. If you already have WSL setup, VS Code should register your WSL installation and suggest the extension.
Now open VSCode from your WSL terminal. Install the extensions "ESLint" and "Prettier - Code formatter", as well as any other extensions you might want. I suggest "JavaScript (ES6) code snippets", "Bracket Pair Colorizer 2" and "Live Server".
Ctrl + k + c -> Add a HTML file style comment.
Alt + shift + f -> Pretty auto formatting of the code.
Ctrl + shift + p -> Open the VSCode command line.
⚠️ You might not be able to use WSL while connected to AAUs VPN with Cisco AnyConnect. A solution is being researched. See: https://gist.github.com/pyther/b7c03579a5ea55fe431561b502ec1ba8
Enable and install WSL by following the guide here. I suggest Ubuntu as the distribution of choice.
Then run the below commands in the WSL terminal.
sudo apt update && sudo apt upgrade
sudo apt install build-essentialThese commands update the freshly installed linux subsystem, and then installs a collection of basic development tools.
Install Node.js using the NVM installation option described in here.
| Command | Description |
|---|---|
| mkdir <directory> | Creates a folder called <directory>. |
| touch <filename> | Creates an empty file called <filename>. Also updates the timestamp of <filename>. |
| cd <directory> | Change directory to <directory>. Home if no directory is chosen. |
| ls -al | Show all the files (hidden files too) in the working directory line-for-line. |
| code . | Opens a VSCode editor inside the current directory. |
| explorer.exe . | Opens the current linux directory in Windows explorer. |
| explorer.exe <filename> | Opens <filename> in windows. |
Update git in the WSL terminal to the latest release
Write about SSH connection and Git commands
To give ourselves an easier time, we're going to use SSH with git. To set it up, follow the guide here and here.
Here is a list of important Git commands in the Ubuntu terminal, as well as a short description.
| Command | Description |
|---|---|
| git clone <repo> | Clones <repo> onto your local machine. <repo> is a SSH link from GitHub. |
| git status | Displays the current working tree status. |
| git pull | Update your local data to match online repository. Depends on current branch. |
| git add . | After making a change or adding a file locally, this prepares all changes to be committed. |
| git commit -m "<message>" | Write a telling <message> about your change, and records the changes to be pushed. |
| git push | Pushes your committed changes to the branch you are working in. |
| git checkout <branch> | Changes to the specified <branch>. |
| git checkout -b <branch> | Creates a new local branch with <branch> name. |
| git push --set-upstream origin <branch> | Creates your local branch in the online repo, and pushes to it. |
| git branch | Displays the branch you are working in, as well as other available branches in the project. |
As the size of this project is rather small in scale, the major focus for writing code is readabilty. To this end, write modular, reusable code, adhering to the DRY (Don't Repeat Yourself) principle. Additionally, camelCase styling is used for JavaScript, HTML and CSS, while PascalCase styling is used in the database.
After writing your code, make sure to properly document it. To keep documentation similar between writers, the project uses standard JSDoc annotations.
The command
/**above a function or class generates a standard documentation form. Add to this the author annotation, and the return annotation if necessary.
After documenting your code, use the Jest framework to describe a test suite and write a number of unit tests for your code units. You may write integration tests as well, but these are not strictly required. A test suite in Jest is a collection of 'tests', consisting of assertions and collected inside a 'describe' block.
The project uses a MySQL database. A database scheme is included in the github repository, to allow running a completely local environment. This will also eventually facilitate testing the functions related to the database. For this to work properly, create a .env file with the following variables, and set them according to your own environment:
PORT=
DATABASE_HOST=
DATABASE_USER=
DATABASE_PASSWORD=
DATABASE=
JWT_SECRET=
BASEURL=
Obviously, the project uses github. We follow the principles of GitHub Flow. Therefore, when working on your feature branch, each commit should contain a message conveying the context for any changes made. See here for great examples.
The project will eventually be hosted by AAU, and will be cloned from this github repository, and a .env file as well as a database will be created there as well.