From f2aace4054aa096af5964a344a0a8f988466a202 Mon Sep 17 00:00:00 2001 From: LD-Reborn Date: Sun, 5 Oct 2025 15:30:28 +0200 Subject: [PATCH] Reworked README, added Development.md, added Userdocumentation.md --- README.md | 43 +++------------------- docs/Development.md | 77 +++++++++++++++++++++++++++++++++++++++ docs/Userdocumentation.md | 2 + 3 files changed, 85 insertions(+), 37 deletions(-) create mode 100644 docs/Development.md create mode 100644 docs/Userdocumentation.md diff --git a/README.md b/README.md index be62ad6..9dca8bc 100644 --- a/README.md +++ b/README.md @@ -1,41 +1,10 @@ # Berufsschule_HAM +![Build & Publish](https://github.com/LD-Reborn/Berufsschule_HAM/actions/workflows/deploy.yml/badge.svg) + This Project serves the purpose of managing Hardware-Assets -# How to setup and build the project -1. If you want to use a local LDAP instance: [Install LDAP](#How-To-Install-and-configure-LDAP) - otherwise use the default ld50.dev configuration -2. Setup the environment using VSCode by installing the extensions: ".NET Install Tool", "C#" (from Microsoft), "C# Dev Kit" (from Microsoft) in the Extensions tab -3. Navigate to the "Source Control" tab (left side; looks like a node graph) -4. Click "Clone Repository" -5. Enter this repository's URL -6. Follow the instructions to authenticate using GitHub -7. Run the project using `F5` or `dotnet build && dotnet run` in the console +# Development documentation +All information regarding development can be found [here](docs/Development.md). -# How to Install and configure LDAP -1. [Install LDAP on Ubuntu and do basic configuration](https://documentation.ubuntu.com/server/how-to/openldap/install-openldap/) -2. Create the three "ou" elements: "assets", "locations" with objectClass "organizationalUnit", and "ou" element "users" with objectClasses "organizationalUnit", and "top". - - -# 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. Create a new branch - 1. In "Source Control" tab click on "main" (i.e. the current branch) - 2. Select "+ Create a new branch..." - 3. Give it a name (e.g. your name or "YourName-#KanbanTaskID") -2. Implement your changes -3. 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 -4. Press the big blue "Commit" button -5. 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.) -6. After committing and pushing your changes, merge the branch. Ask @LD-Reborn to merge, or if you don't fear merge conflicts: - 1. Switch to the main branch `git checkout main` (or select main branch at the top) - 2. Merge branch `git merge Your-branch-name` - 3. If it was successful you will see a commit you can push. Push it. - 4. If there was no error: congrats. If there was, contact @LD-Reborn +# User documentation +All information regarding general usage can be found [here](docs/Userdocumentation.md). \ No newline at end of file diff --git a/docs/Development.md b/docs/Development.md new file mode 100644 index 0000000..bf978bd --- /dev/null +++ b/docs/Development.md @@ -0,0 +1,77 @@ +# 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](https://documentation.ubuntu.com/server/how-to/openldap/install-openldap/) +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. \ No newline at end of file diff --git a/docs/Userdocumentation.md b/docs/Userdocumentation.md new file mode 100644 index 0000000..8ba5dc0 --- /dev/null +++ b/docs/Userdocumentation.md @@ -0,0 +1,2 @@ +# User documentation +`TODO`