diff --git a/docs/Administration.md b/docs/Administration.md index e8d152a..1e756dc 100644 --- a/docs/Administration.md +++ b/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 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