Merge pull request #320 from LD-Reborn/43-documentation-create-a-user-manual

43 documentation create a user manual

docs/Administration.md

@@ -1,25 +1,71 @@
 # Administration
-
+## Requirements
+### Hardware
+- Ubuntu Server with
+    - 2 CPU cores
+    - 2 GB RAM
+    - 50 GB SSD
+- Windows Server with
+    - 4 CPU cores
+    - 4 GB RAM
+    - 100 GB SSD
+### Software
+- DotNet Core 10.0 Hosting Bundle (Windows)
+- DotNet Core 10.0 Runtime (Ubuntu)
+- LDAP server (Active Directory or OpenLDAP)
+## Hosting setup
+- Windows: [Read the Microsoft documentation regarding hosting .NET apps](https://learn.microsoft.com/en-us/aspnet/core/tutorials/publish-to-iis?view=aspnetcore-10.0&tabs=visual-studio)
+- Ubuntu:
+    - Install DotNet Core 10.0 runtime via package manager: `sudo apt install dotnet10 dotnet-runtime-10.0`
+    - Set up nginx to point to the application:
+        - `sudo apt install nginx`
+        - Configure nginx:
+            - Create and edit the config file: `sudo nano /etc/nginx/sites-available/HAM.conf`
+            - Insert the content and configure: [example_nginx.conf](Resources/example_nginx.conf)
+            - create a symbolic link to sites-enabled: `cd ../sites-enabled && ln -s ../sites-available/HAM.conf HAM.conf`
+        - Restart nginx: `sudo systemctl restart nginx`
+        - If you don't already have an SSL certificate:
+            - Install certbot: `sudo apt install certbot -y`
+            - Acquire a certificate: `sudo certbot certonly -d  mydomain.com -d www.mydomain.com`
+            - Set up a cronjob for renewal:
+                - `sudo crontab -e`
+                - Append the following line: `0 0 * * * /usr/bin/certbot renew --pre-hook "systemctl stop nginx" --post-hook "systemctl start nginx nginx"`
+                - Save with ctrl + s and exit with ctrl + x
+    - Get the application by either:
+        - Downloading the release from the releases section of the repository and unpacking it to `/var/www/HAM`
+        - Building the application from source
+            - Clone the repository on the target server (e.g. your home directory)
+            - Enter the `src` folder
+            - Build the application:
+                - `dotnet build`
+                - `dotnet publish -c Release`
+            - Copy the output to the destination: `sudo cp bin/Release/net10.0 /var/www/HAM`
+    - Configure the application as specified in [Configuration](#configuration)
+    - Set up the Sytemd service 
+        - Create the service file: `sudo nano /etc/systemd/system/HAM.service`
+        - Set up the contents of the service file. E.g.: [example_systemd.service](Resources/example_systemd.service)
+        - Reload the systemd daemon: `sudo systemctl daemon-reload`
+        - Enable and start the service: `sudo systemctl enable HAM.service --now`
 ## Configuration
 ### Environments
-(TODO: Explanation regarding appsettings.XYZ.json here)
+There are three files named "appsettings" that end in ".json". These are the configuration files.
 
-### Barcode type
+The `appsettings.json` file is the generic one, and it specifies information that applies to all environments.
-The barcode type can be set in the appsettings like this:
-```json
-{
-    //[...]
-    "BarcodeType": "code128",
-    //[...]
-}
-```
-The following barcodes are supported:
-- CODE128C
-- EAN13
-- EAN8
-- UPC
-- ITF14
-- ITF
 
-Make sure to type in the barcode format in lowercase.
+The files named `appsettings.*.json` contain configuration specific to that environment. Everything that is put there overrides the `appsettings.json` configuration.
 
+### Ldap
+This is where you put your LDAP configuration regarding connection and where the individual elements are located.
+
+- `Host`: The IP address of the LDAP server
+- `Port`: The port (usually 389) of the LDAP server
+- `UseSsl`: Whether to require SSL
+- `BindDn`: The username to authenticate with
+- `BindPassword`: The password to use to authenticate
+- `BaseDn`: The dn where everything is located under
+- `AssetsOu`: The ou under which the assets reside
+- `LocationsOu`: The ou under which the locations reside
+- `UsersOu`: The ou under which the users reside
+
+### Other configuration
+For other configuration (like setting custom ports) consult the [Microsoft documentation](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration/?view=aspnetcore-10.0)

docs/Resources/example_nginx.conf

@@ -0,0 +1,23 @@
+server {
+    listen 80;
+    server_name yoursubdomain.domain.dom;
+    return 301 https://$host$request_uri;
+}
+
+server {
+    listen 443 ssl; # initial config: listen 80;
+    server_name yoursubdomain.domain.dom;
+
+    ssl_certificate /etc/letsencrypt/live/yoursubdomain.domain.dom/fullchain.pem; # initial config: comment out
+    ssl_certificate_key /etc/letsencrypt/live/yoursubdomain.domain.dom/privkey.pem; # initial config: comment out
+
+    client_max_body_size 500G;
+
+    location / {
+        proxy_pass http://localhost:5000/;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+}

docs/Resources/example_systemd.service

@@ -0,0 +1,35 @@
+[Unit]
+Description=HAM .NET Application
+After=network.target
+
+[Service]
+Type=simple
+NotifyAccess=all
+Restart=always
+RestartSec=10
+
+# Working directory
+WorkingDirectory=/var/www/HAM
+
+# Application settings
+ExecStart=/usr/bin/dotnet /var/www/HAM/Berufsschule_HAM.dll
+ExecReload=/bin/kill -HUP $MAINPID
+#TimeoutStopSec=30
+#TimeoutStartSec=60
+
+# Environment variables (uncomment and modify as needed)
+Environment=DOTNET_ENVIRONMENT=Production
+
+# Security settings
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+
+# Logging
+StandardOutput=journal
+StandardError=journal
+SyslogIdentifier=ham
+
+[Install]
+WantedBy=multi-user.target

docs/Userdocumentation.md

@@ -1,2 +1,74 @@
 # User documentation
-`TODO`
+## Login
+- Upon opening the page, enter the username and password the administrators set up for you.
+- Then click the "Login" button.
+- Now you're logged in. By using the buttons or the navigation bar you can navigate to the correct page for the task you need to complete.
+## Inventory
+To inventorize items, complete the following steps:
+- If you have a camera:
+    - Press the "Scan barcode" button
+    - Locate the barcode on the asset
+    - Align the barcode with the camera until the camera closes and a modal opens
+- If you don't have a camera:
+    - Read the asset ID from the asset you want to inventorize
+    - Input the asset ID into the "Asset ID" input field
+    - Click the "Enter asset ID manually" button
+- A modal opened. Inspect the fields and their data.
+- If the contents match, click "information is correct"
+- If there is something wrong, click "update information", apply the modifications and then click "apply changes"
+## Printing
+When in the "Inventory" or "Assets" page, a blue icon should be visible on the bottom left.
+- Click the blue icon. A modal should open. All Barcodes you added to the print batch will be visible here
+- Layout the barcodes according to your preferences and/or requirements
+- Click "print batch"
+- A new page opens with a print modal. DO NOT print to a printer yet!
+- Select "Save to pdf" as a target and hit "save"
+- Open the exported pdf and print it using the printer of your choice.
+## Assets
+### Filter
+Above the table rows, beneath the table header is the filter row, which contains input fields where you can set the contents to filter by.
+
+Elements that contain the provided strings remain shown.
+
+To filter by multiple properties (e.g. owner name and location) fill in the applicable fields.
+### Detail view
+To view asset details, click on the list entry of the asset you want to view the details of.
+### Creation
+To create an asset, click on the "Create Asset" button, fill in the applicable fields and click on "Create".
+### Update
+To update an asset, click on the "Update" button next to the asset in the table, modify the applicable fields and click on "Update".
+### Deletion
+To delete an asset, click on the "Delete" button next to the asset in the table, and confirm with "yes, delete".
+## Locations
+### Filter
+Above the table rows, beneath the table header is the filter row, which contains input fields where you can set the contents to filter by.
+
+Elements that contain the provided strings remain shown.
+
+To filter by multiple properties (e.g. room name and room number) fill in the applicable fields.
+### Creation
+To create a location, click on the "Create Location" button, fill in the applicable fields and click on "Create".
+### Update
+To update a location, click on the "Update" button next to the location in the table, modify the applicable fields and click on "Update".
+### Deletion
+To delete a location, click on the "Delete" button next to the location in the table, and confirm with "yes, delete".
+## Users
+### Detail view
+To view user details, click on the list entry of the user you want to view the details of.
+### Creation
+To create a user, click on the "Create User" button, fill in the applicable fields and click on "Create".
+### Update
+To update a user, click on the "Update" button next to the user in the table, modify the applicable fields and click on "Update".
+### Deletion
+To delete a user, click on the "Delete" button next to the user in the table, and confirm with "yes, delete".
+## Groups
+### Creation
+To create a group, click on the "Create Group" button, fill in the applicable fields and click on "Create".
+### Update
+To update a group, click on the "Update" button next to the group in the table, modify the applicable fields and click on "Update".
+### Deletion
+To delete a group, click on the "Delete" button next to the group in the table, and confirm with "yes, delete".
+## Settings
+The presets are hidden by default. To edit the presets, click on "Presets".
+
+Save the changes by clicking on "Apply settings and update presets"

src/appsettings.json

@@ -16,7 +16,6 @@
         "Application": "Berufsschule_HAM"
     }
   },
-  "BarcodeType": "code128",
   "Elmah": {
       "AllowedHosts": [
         "127.0.0.1",