Updated administration documentation

docs/Administration.md

@@ -1,25 +1,68 @@
 # 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: [example_nginx.conf](Resources/example_nginx.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