diff --git a/docs/Administration.md b/docs/Administration.md index e8d152a..7264dd2 100644 --- a/docs/Administration.md +++ b/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 barcode type can be set in the appsettings like this: -```json -{ - //[...] - "BarcodeType": "code128", - //[...] -} -``` -The following barcodes are supported: -- CODE128C -- EAN13 -- EAN8 -- UPC -- ITF14 -- ITF +The `appsettings.json` file is the generic one, and it specifies information that applies to all environments. -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) \ No newline at end of file diff --git a/docs/Resources/example_nginx.conf b/docs/Resources/example_nginx.conf new file mode 100644 index 0000000..c61a9ee --- /dev/null +++ b/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; + } +} diff --git a/docs/Resources/example_systemd.service b/docs/Resources/example_systemd.service new file mode 100644 index 0000000..0c33141 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/Userdocumentation.md b/docs/Userdocumentation.md index 8ba5dc0..719b6c6 100644 --- a/docs/Userdocumentation.md +++ b/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" \ No newline at end of file diff --git a/src/appsettings.json b/src/appsettings.json index 8b0d9cd..b4a7e5d 100644 --- a/src/appsettings.json +++ b/src/appsettings.json @@ -16,7 +16,6 @@ "Application": "Berufsschule_HAM" } }, - "BarcodeType": "code128", "Elmah": { "AllowedHosts": [ "127.0.0.1",