Berufsschule_HAM/docs/Development.md

How to setup and build the project

1. Setup the environment using VSCode by installing the extensions: ".NET Install Tool", "C#" (from Microsoft), "C# Dev Kit" (from Microsoft) in the Extensions tab
2. Navigate to the "Source Control" tab (left side; looks like a node graph)
3. Click "Clone Repository"
4. Enter this repository's URL
5. Follow the instructions to authenticate using GitHub
6. Run the project using F5 or dotnet build && dotnet run in the console

Important endpoints/URLs

• Login: http://localhost:5275/Home/Login
  • The login page
• Home: http://localhost:5275/Home/Index
  • The home and overview page
• Swagger: http://localhost:5275/swagger/index.html
  • (Active only in development environment)
  • (Requires authorization)
  • All controller endpoints are mapped here.
  • You can test the endpoints here and debug issues.
• Elmah: http://localhost:5275/elmah/errors
  • (Requires authorization)
  • All errors are logged here.
  • You can check for uncaught errors here.
• Healthz: http://localhost:5275/healthz
  • (Requires authorization)
  • Checks for the status of the LDAP database
  • If an issue with the database is detected, you get "Unhealthy" as a result.

Logging

• The logs are - by default - output to ~/logs/.
• The error logs are - by default - output to ~/Elmah

If necessary, change the folder in appsettings.json

Environments

Currently there are two environments

• Development
  • Utilizes appsettings.Development.json and appsettings.json
  • Points to a public LDAP running on ld50.dev (no SSL!)
  • Is the default for local development
• Production
  • Utilizes appsettings.Production.json and appsettings.json
  • Points to a local LDAP
  • Is the default for the QA/Production
  • Requires DOTNET_ENVIRONMENT or ASPNETCORE_ENVIRONMENT variable to be set to Production

How to Install and configure LDAP locally

(This is not necessary for general development.)

1. Install LDAP on Ubuntu and do basic configuration
2. Configure the application to utilize your LDAP and run it once - all "ou" elements will be created automatically

How to connect to ldap server using apache directory studio

1. Click "add new connection"
2. Choose any connection name, hostname: "ld50.dev", port: 8389
3. Authentication method: "Simple Authentication", Bind DN: "cn=admin,dc=localhost", bind password: "TestLDAP"
4. Continue and finish setup

How to contribute

1. Assign an open issue to yourself
2. Create a new branch by clicking on "Create a branch" and confirming
3. Do git fetch or fetch via your IDE
4. Do git switch BRANCHNAME or select the newly created branch in your IDE
5. Implement your changes
6. Prepare your changes to commit
   1. In "Source Control" under "Changes" you'll find the changed files. For each file:
   2. Click on each file, examine all the shown changes and check whether it's what you want committed. Remove temporary elements you added for debugging (e.g. "Console.Log")
   3. After cleaning up the file, click on the "+" on the right (Mouseover text: "Stage Changes")
   4. After staging all file changes in step 3, do a final test of the changes before you commit
   5. Select a commit message that best describes the change you did. e.g.:
      • "Added [...]"
      • "Fixed [...]"
      • "Created [...]"
      • "Implemented [...]"
7. Do git commit -m "MESSAGE" or press the big blue "Commit" button (VSCode)
8. Do git push (in the "GRAPH" section there are a few buttons, one of which has an upward facing arrow and the mouseover text "Push"; use this one.)
9. After committing and pushing your changes, create a pull request in GitHub. (optional: Assign @LD-Reborn for code review.)
10. Once there are no requested changes / the review is approved, merge the branch. If you encounter merge conflicts, contact @LD-Reborn.

How to perform E2E tests

1. cd tests/Berufsschule_HAM.E2ETests
2. dotnet build && dotnet test