HAM/Berufsschule_HAM
1
0
Fork 1
mirror of https://github.com/LD-Reborn/Berufsschule_HAM.git synced 2025-12-20 06:51:55 +00:00
Code Issues Packages Projects 1 Releases Wiki Activity

Merge pull request #70 from LD-Reborn/62-documentation-refactor-readme

Browse Source 
Reworked README, added Development.md, added Userdocumentation.md
This commit is contained in:
LD50
2025-10-05 15:30:52 +02:00
committed by GitHub
parent 2a2fec62fa f2aace4054
commit 215e391566
3 changed files with 85 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

43
README.md
View File

@@ -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).

77
docs/Development.md Normal file
View File

@@ -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.

2
docs/Userdocumentation.md Normal file
View File

@@ -0,0 +1,2 @@
# User documentation
`TODO`