# 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`.