Christoph Schwörer
f045b99a25
QuellCode/CentronERP war nur als Gitlink (Submodul-Referenz auf 79c1142) getrackt, ohne .gitmodules und ohne erreichbares Remote. Der Untersuchungsgegenstand der Versuchsreihe war damit nicht reproduzierbar gesichert: Ein Klon haette ein leeres Verzeichnis erhalten, und die Belege der 3.287 Anforderungen waeren nicht ueberpruefbar gewesen. Umstellung: - Historie nach c:\DEV\CentronERP_git_snapshot_79c1142 ausgelagert (vollstaendig lesbar, enthaelt 79c1142 und Vorgaenger 89ccfd6) - Gitlink aus dem Index entfernt - Dateiinhalt aufgenommen: 24.557 Dateien, rund 333 MB Die verschachtelte .gitignore der Codebasis gilt weiter, Build-Artefakte bleiben ausgeschlossen. Details in Versuche/Versuch_01/_Codebasis-Nachweis.md
127 lines
7.4 KiB
Markdown
127 lines
7.4 KiB
Markdown
# Run the c-entron Web-Service on Linux
|
|
|
|
Right now we don't create Linux version of our web-service by default.
|
|
But you can create a version manually by running the `build-web-service-linux` target from the `Centron.Scripts` project.
|
|
|
|
It creates a `c-entron Web-Service Linux.zip` file which contains the web-service for Linux.
|
|
|
|
# How to prepare the Linux server
|
|
|
|
The Linux web-service is a framework-dependent version, which means you need to install .NET on the Linux server.
|
|
[How to install .NET on Linux](https://docs.microsoft.com/en-us/dotnet/core/install/linux)
|
|
The above link also contains a list of all Linux distributions that are supported by .NET.
|
|
As far as I know, we should support all of them, but we only tested with Ubuntu and Debian.
|
|
|
|
Make sure to install the correct version of .NET that is needed for our web-service.
|
|
As of right now (Jan. 2024), c-entron.NET and the web-service are running on .NET 8.
|
|
|
|
Also some other dependencies are required for the web-service to work correctly.
|
|
[See here which other dependencies are required](https://docs.devexpress.com/OfficeFileAPI/401441/use-office-file-api-on-linux#prerequisites)
|
|
|
|
# How to install the c-entron Web-Service on Linux
|
|
|
|
Copy the `c-entron Web-Service Linux.zip` archive to the server, and extract it wherever you want to install it.
|
|
For example purposes, lets use `/opt/centronws`.
|
|
|
|
Now we need a `WebServiceConfig.xml`, which on windows is created by the `c-entron Web-Service Connection Manager` - but this tool is not available on linux, and right now we don't have a linux-alternative for it.
|
|
So I recommend to copy the `WebServiceConfig.xml` from a windows-installation of the web-service.
|
|
|
|
After the web-service is copied and configured, you can start it by executing the `Centron.Host.Console` application.
|
|
|
|
You might get some permission errors along the way - fix them by making the `Centron.Host.Console` executable, and giving read-permissions to the directory.
|
|
|
|
You should see some command-line output from the web-service, and after a couple of seconds the web-service should be started and available per HTTP.
|
|
|
|
# How to use HTTPS
|
|
|
|
HTTPS configuration is very different between Linux and Windows, because on Windows its using Windows-only configuration.
|
|
|
|
So on Linux, you have to edit the `WebServiceConfig.xml`.
|
|
Add a `WebServiceCertificateFilePath` XML-node with the path to your pfx-certificate.
|
|
And add another XML-node `WebServiceCertificatePassword` containing your password for the pfx-certificate.
|
|
For example, if you placed the certificate next to the web-service `/opt/centronws/https-certificate.pfx`, and the password is `123456`, adjust the `WebServiceConfig.xml` to look like this.
|
|
|
|
```xml
|
|
<WebServiceConfig>
|
|
<!-- Usual settings that also work for windows -->
|
|
<WebServiceAddress>https://localhost:443</WebServiceAddress>
|
|
<DatabaseConnectionString>VGhpcyBpcyB3aGVyZSB5b3VyIERhdGFiYXNlQ29ubmVjdGlvblN0cmluZyBzaG91bGQgYmU=</DatabaseConnectionString>
|
|
|
|
<!-- The 2 following nodes should be added manually -->
|
|
<WebServiceCertificateFilePath>./https-certificate.pfx</WebServiceCertificateFilePath>
|
|
<WebServiceCertificatePassword>123456</WebServiceCertificatePassword>
|
|
|
|
<!-- Other settings omitted -->
|
|
</WebServiceConfig>
|
|
```
|
|
|
|
Restart the `Centron.Host.Console`, and the c-entron Web-Service should be available per HTTPS with a valid certificate!
|
|
|
|
# How to make the web-service run in the background
|
|
|
|
You can use whatever mechanism or service you want for that, just execute the `Centron.Host.Console` application.
|
|
|
|
One possibility is, to use `systemd` to run the web-service (this obviously only works if `systemd` is available on your Linux distribution).
|
|
|
|
To use `systemd` create a new file `/etc/systemd/system/centronws.service` with the following contents (adjust paths and user if necessary):
|
|
|
|
```ini
|
|
[Unit]
|
|
Description=c-entron web-service
|
|
|
|
[Service]
|
|
WorkingDirectory=/opt/centronws # will set the Current Working Directory (CWD)
|
|
ExecStart=/opt/centronws/Centron.Host.Console # systemd will run this executable to start the service
|
|
SyslogIdentifier=centronws # to query logs using journalctl
|
|
User=c-entron # which user should execute the service, use 'chown yourusername -R /opt/centronws' to take ownership of the folder and files, use 'chmod +x /opt/centronws/Centron.Host.Console' to allow execution of the executable file.
|
|
Restart=always # ensure the service restarts after crashing
|
|
RestartSec=5 # amount of time to wait before restarting the service
|
|
KillSignal=SIGINT # copied from dotnet documentation at https://docs.microsoft.com/en-us/aspnet/core/host-and-deploy/linux-nginx?view=aspnetcore-3.1#code-try-7
|
|
AmbientCapabilities=CAP_NET_BIND_SERVICE # give the executed process the CAP_NET_BIND_SERVICE capability. This capability allows the process to bind to well known ports.
|
|
|
|
[Install]
|
|
WantedBy=multi-user.target
|
|
```
|
|
|
|
After creating this `.service` file, we have to execute some commands.
|
|
|
|
Reload the systemd services using `sudo systemctl daemon-reload`
|
|
Make sure the new service was discovered correctly using `sudo systemctl status centronws`
|
|
Start the c-entron Web-Service using `sudo systemctl start centronws.service`
|
|
|
|
If you want the c-entron Web-Service to start when the machine starts, you can run `sudo systemctl enable centronws.service`
|
|
|
|
# Differences between Linux and Windows as a c-entron User
|
|
|
|
There are a couple of limitations when running on Linux, in comparison to running on Windows.
|
|
Most of them can be fixed in the future, but right now these limitations apply.
|
|
|
|
### Sub-Web-Services
|
|
The Sub-Web-Services don't work on Linux. All of the code regarding them is contained in the `c-entron Web-Service Connection Manager`, which is not available on Linux.
|
|
A refactoring is needed here.
|
|
|
|
**Our latest stance on this topic is:**
|
|
If a customer is running his web-service on linux, then he is a `poweruser`.
|
|
And as a `poweruser` he can copy the web-service, configure it for another database, and create another `systemd service` all by himself.
|
|
|
|
# What is left to do to make the Linux UX good?
|
|
|
|
### Web-Service configuration tool
|
|
On windows we have the `Web-Service Connection Manager`, but we currently don't have a similar tool for linux.
|
|
Right now you're out of luck and have to hand-edit the `WebServiceConfig.xml` file, which is a very bad user experience.
|
|
|
|
What I would like to have is some kind of CLI that guides the user through web-service configuration.
|
|
It would be extra nice if you could call the `Centron.Host.Console.exe` with a `configure` command, and then it steps you through the configuration (web-service url, certificate, path, database connection, etc.).
|
|
|
|
### Certificate password encryption
|
|
Right now the certificate-password is written in `plaintext` in the `WebServiceConfig.xml` file.
|
|
Once we have the `Web-Service configuration tool` from above, we should `encrypt` the certificate-password instead.
|
|
Just as we already encrypt the `database connection-string` and `proxy password`.
|
|
|
|
### Tool to read your Hardware-ID
|
|
On windows it's very easy, because the `Web-Service Connection Manager` shows you your `Hardware-ID`.
|
|
On linux this is currently not available, and you as the user can't really do anything by yourself.
|
|
Right now the workaround is: Send your linux `/etc/machine-id` to a developer, and he magically creates the `Hardware-ID` from it.
|
|
|
|
A better experience would be, to have some kind of CLI that prints you your own `Hardware-ID`.
|
|
Would be nice if it also was on `Centron.Host.Console.exe`, with a `hardware-id` command, and all it does is print out your `Hardware-ID`. |