Development Environment - e-Learning-by-SSE/nm-self-learning GitHub Wiki
Here we explain the necessary tools, technologies and setup to develop and run the self-learn platform locally.
If you just want to start with "coding", you may want to visit the development quickstart guide here.
Choose between one of the two ways to install the
Please have a look at this installation (currently available only in German): Development Environment with Docker. For this method you only need a basic installation of Docker Desktop and Visual Studio Code. The rest of the development setup is automatically setup and configured through docker.
We use the latest LTS release (even version numbers).
Visit & download NodeJS from https://nodejs.org/en/download/. During the installation process, you may be prompted for a preferred package/ build management tool. We use npm.
Further, we use the nx-build system, which can be installed via npm. For this you need to execute the following command (required administration privileges):
npm -g install nx
Auxiliary applications (database, authentication server) are shipped and executed as Docker images. Therefore, you need a Docker.
Please check that you use WSL 2. This manual shows how to do that. Further, we suggest to use Docker Desktop. Before starting Docker for the first time after boot, you need to ensure that the Docker service is started. This can either be done via WSL (by starting the Linux service) or be starting the Docker application, if Docker Desktop is installed.
After Docker was installed, you can start the auxiliary services with the following command, before you start the self-learning application:
docker compose -f compose-dev.yml up -d
Visual Studio Code is the preferred IDE for the development of the self-learn platform. For Windows users: You may also use Visual Studio Code WSL extension. However, this is not required.
The project / repository root is configured as a VS Code project. Either open the folder in VS code or navigate to the folder in run the command code . to open the IDE.
The project contains a list of recommended extensions. VS code asks to install these recommended extensions when loading the project. This article explains how to install these recommendations.
In short: in VS Code, press F1 to open the command palette and search for Extensions: Show Recommended Extensions. Afterwards, the plugins will appear in your sidebar with an Install button.
An excerpt of the extensions we use:
- Prettier: Code formatter
- ESLint: Static analysis and coding style guidelines
- Tailwind CSS IntelliSense: IntelliSense for Tailwind CSS classes
- Nx Console: UI for Nx commands
- Jest Runner: Simple way to run or debug a single (or multiple) tests from context-menu or via code lens
- Prisma: Adds syntax highlighting, formatting, auto-completion, jump-to-definition and linting for .prisma files
The project is configured via a .env file. The project contains an example, which may be used as an template. For this, you need to rename .env.example to .env:
mv .env.example .env
Please be careful not to upload the .env as this may lead to conflicts.
You can fill the .env file with values automatically by running the script docker/entry.sh.
Afterwards, you may make local modifications. As there is no NEXTAUTH_SECRET predefined, which is mandatory, you need to set a random secret. Create a random secret with following command:
openssl rand -base64 32
And set the random secret in value for NEXTAUTH_SECRET. The default values for accessing the database are already in conjunction to the compose-dev.yml file and, thus, won't need to be re-configured.
In the file .env set a value of NEXT_PUBLIC_IS_DEMO_INSTANCE to true (enables login in the web app).
See the Environment-Configuration page for a detailed description of possible configuration values.
This section describes how to run and execute the application. The following commands may be executed via a system terminal or via the terminal of VS Code.
Before starting the application, you may need to install required dependencies. This should be done after pulling data from the repository, as the list of dependencies may change after adding new libraries to the project.
Since we developed own libraries which aren't available in the default npm repositories, you have to add our own github packages registry.
- Copy
.npmrc.exampleto.npmrcand add your github auth token. 1.1 As an alternative, you can set the auth token to your environment, e.g.export NPM_TOKEN=gh....if you don't want to add it to the file. - Run the following
npm install
Note: A common mistake is to remove the double slashes at the start of the second line. They are indeed a part of the configuration and must not be removed.
The final result (in case you don't want to export the token as environment variable):
@e-learning-by-sse:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=gh_.....
Before you can run the application, you need to start the development environment. First, check that the Docker service is running. If you have installed Docker Desktop on Windows, you may open the start menu, enter Docker, and hit Return. This will lunch the Docker service and you can see the status in the system tray.
When the Docker service is running, you may enter the following command inside the project folder to start the development environment:
docker run -d \
--name dev-db \
-e POSTGRES_USER=username \
-e POSTGRES_PASSWORD=password \
-e POSTGRES_DB=SelfLearningDb \
-v dev_db_data:/var/lib/postgresql/data \
postgres:13
You may need to (re-)generate the database client that connects the data base with your code (ORM). This must be done when ever the schema file (located at libs/data-access/database/prisma/schema.prisma) was changed. Since we use Prisma, this can be done with the follwing command:
npm run prisma generate
Additionally, you may create the database (first command) and apply sample data (second command). Keep in mind that this will delete the content of your tables:
npx prisma db push --accept-data-loss
npx prisma db seed
Note: For simpler use, you can use
npm run prisma:seedwhich does all of this at once.
This project uses Prisma for database access.
To interact with the database, you can use code like the following:
import { User } from "@prisma/client"; // User is generated by Prisma from our schema
import { database } from "@self-learning/database";
function getUserById(id: string): Promise<User> {
// all properties (user, id, ...) are type-safe!
return database.user.findUnique({
where: {
id: id
}
});
}Development only: After making changes to the database schema (libs/data-access/database/prisma/schema.prisma)), use the following command to push these changes to the database:
npm run prisma db push
After the development environment was started, you may start the application as follows:
The following command will compile pages on the fly (when they are needed / changed). This is much slower then in production, but recommended for development as you can see your changes immediately.
npm start
If you want to use prisma studio to easly access the database during development run this:
npx prisma studio
Note: For simpler use, you can use
npm run devto start the watch mode and prisma studio at the same time.
The following commands are intended to compile and execute the application. The application won't be re-compiled on changes, which makes the execution much faster. This is intended for production or to test production setting.
npm run build
npm run start:prod
# Run all tests
npm run test
# Testing a specific application or library
nx test [APPLICATION_NAME / LIBRARY_NAME] [--watch]
When using the Jest Runner extension during development, you will see a Run and Debug CodeLens button above your tests. Use these to start individual tests. Additionally, you may want to configure "jestrunner.runOptions": ["--watch"] in your VS Code's settings.json (or using the Settings UI Extensions > Jest-Runner Config > Run Options > Add Item -> "--watch"). Afterwards, your tests will automatically start with watch mode enabled.
"Can't reach database server":
Can't reach database server at `localhost`:`5432`
You should check if your database configuration files (.env and compose-dev.yml) are consistent in respect to the port, username and password of the database server.
"Invalid Type":
{
code: 'invalid_type',
expected: 'string',
received: 'undefined',
path: [Array],
message: 'Required'
}
],
addIssue: [Function (anonymous)],
addIssues: [Function (anonymous)],
errors: [
Message can appear when you access several sites (e.g. the after pressing the login button). Check if you need to setup your prisma database. See section above for seeding.
NextAuth 'expected 200 OK, got: 400 Bad Request':
If you get this message on login attempts, this can have multiple reasons. A common one is to check if the fake-oidc server is accessable. Open a browser and go to "http://localhost:8090". If you get an SSL error and you don't want to use SSL, you must disable it.
NextAuth 'Not Found':
When this error occurs after you changed your NextAuth ISSUER settings, you may have a trailing slash in your URI which is not allowed.
NextAuth: TypeError: "ikm" must be at least one byte in length:
You forgot to set a NEXTAUTH_SECRET. See the configurations section above.
# Install dependencies
npm ci
# [DEMO ONLY] Apply database schema
npm run prisma db push --accept-data-loss
# [DEMO ONLY] Seed database with demo data
npm run prisma db seed
# Build application
npm run build --omit=dev
# Start server (at http://localhost:4200)
npm run start:prodNote: We recommend using our built docker images available at https://github.com/e-Learning-by-SSE/nm-self-learning/pkgs/container/nm-self-learning