Skip to main content

Publishing to Apache

This guide explains how to configure a Linux server with Apache to publish a Lagoon application. Screenshots from the previous documentation have been deliberately removed.

Hardware and software requirements​

The software and hardware components required for the application to run are not provided with the installation package.

Hardware requirements​

The minimum configuration for hosting on a local network is as follows:

  • The application server requires a 2-core CPU with 4 GB of RAM.
  • Hard disk larger than 40 GB or 60 GB.

These values may change depending on the load the server handles: number of applications hosted, number of people using them simultaneously, number of files to store, etc.

Software prerequisites​

This installation manual is intended for deployment on the Red Hat Enterprise Linux distribution. Use a version compatible with ASP.NET Core Runtime 8.0, for example RHEL 8 or later. Linux commands must be adapted if another distribution is used.

The CentOS distribution is not recommended, since its development has stopped: .NET 8+ versions will not be supported.

Installation must be performed by a user with access to the sudo command. The commands presented in the following chapters come from RHEL 9.

Software environment​

The application uses ASP.NET Core Runtime 8.0 as well as the Lagoon toolkit developed by DESIRADE.

The components to monitor are Apache and the DBMS, for example MySQL or SQL Server. Installation of the DBMS part is not detailed in this document.

Installation procedure​

Installing the Apache web server​

To install the Apache web server, run the following commands.

Installing Apache​

sudo dnf -y update
sudo dnf -y install httpd

Start the server​

sudo systemctl start httpd

Configure the server to start automatically​

sudo systemctl enable httpd

Configuring Apache​

Blazor applications use a dedicated web server named Kestrel. To associate Kestrel with an Apache instance, configure Apache so that all requests related to the application are redirected to this server.

  • Open the proxy configuration file: vi /etc/httpd/cond.modules.d/00-proxy.conf.
  • Check that the required proxy modules are loaded.
  • In a secure HTTPS configuration, open the SSL configuration file and check that the line exists: vi /etc/httpd/cond.modules.d/00-ssl.conf.
  • Create a configuration file in the /etc/httpd/conf.d/MyApp.conf directory, replacing MyApp with the application name.
# Configuration en mode HTTP
<VirtualHost *:80>
     RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}

     # Redirection WebSocket nécessaire à Blazor.
     RewriteEngine on
     RewriteCond %{HTTP:Upgrade} websocket [NC]
     RewriteCond %{HTTP:Connection} upgrade [NC]
     RewriteRule ^/?(.*) "ws://localhost:5000/$1" [P,L]

     # Configuration du proxy vers Kestrel.
     ProxyPreserveHost On
     ProxyPassMatch ^/_blazor/(.*) http://localhost:5000/_blazor/$1
     ProxyPass /_blazor ws://localhost:5000/_blazor
     ProxyPass / http://localhost:5000/
     ProxyPassReverse / http://localhost:5000/
</VirtualHost>

# Configuration en mode HTTPS
<VirtualHost *:443>
     SSLEngine On
     SSLCertificateFile <Chemin vers le fichier CRT>
     SSLCertificateKeyFile <Chemin vers le fichier KEY>

     RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
     RequestHeader set "X-Forwarded-SSL" expr=%{HTTPS}

     # Redirection WebSocket nécessaire à Blazor.
     RewriteEngine on
     RewriteCond %{HTTP:Upgrade} websocket [NC]
     RewriteCond %{HTTP:Connection} upgrade [NC]
     RewriteRule ^/?(.*) "ws://localhost:5000/$1" [P,L]

     # Configuration du proxy vers Kestrel.
     ProxyPreserveHost On
     ProxyPassMatch ^/_blazor/(.*) http://localhost:5000/_blazor/$1
     ProxyPass /_blazor ws://localhost:5000/_blazor
     ProxyPass / http://localhost:5000/
     ProxyPassReverse / http://localhost:5000/
</VirtualHost>

Restart the web server:

sudo systemctl restart httpd

Case of an existing Apache server​

If the application is installed on an existing Apache server already hosting other applications, two solutions can be implemented.

Change the port for the application​

Add the following to the configuration file created earlier:

Listen <port souhaité>

Then replace the port in the VirtualHost tag and restart Apache.

sudo systemctl restart httpd

Define a subdomain specific to the application​

Add the following parameter inside the VirtualHost tag:

ServerName <nom sous-domaine>

Then restart Apache.

sudo systemctl restart httpd

Installing the .NET Core Framework​

The application requires the .NET Core Framework to be installed in order to run. This Framework has been available in Red Hat's official repository packages since RHEL 8.

sudo dnf -y install aspnetcore-runtime-8.0

To check that the package was installed correctly, run:

dotnet --info

Installing Chrome​

If the application uses the PDF export feature, the Chrome browser must be installed on the server.

cd /tmp
sudo wget https://dl.google.com/linux/direct/google-chrome-stable_current_x86_64.rpm
sudo dnf install -y ./google-chrome-stable_current_x86_64.rpm

Then configure the path to the browser executable in appsettings.json, as described in the application configuration.

Deploying the application​

The steps to install the application are:

  • Create a directory, for example mkdir /var/www/myapp.
  • Copy all the application files into this directory.
  • Check that the configuration settings in appsettings.json are correct:
    • ConnectionStrings: database connection strings.
    • Lagoon:PublicUrl: application URL, i.e. the one provided to users.
    • Lagoon:UseForwardedHeaders: set this value to true if Apache is in a secure HTTPS configuration.
    • Lagoon:ChromiumPath: path to the Chromium browser executable, /opt/google/chrome/chrome by default.
    • FolderPath: directory containing the trace file, writable by the user running the application.
  • Start the application from the application directory.
dotnet MYAPP.Server.dll

To check that the server is working:

curl -i http://localhost:5000

Check that the response is not an error. The login page must be accessible from a web browser.

Declaring the application as a service​

Create a MyApp.service file containing the following settings:

[Unit]
Description=Lagoon application

[Service]
# Répertoire de l'application.
WorkingDirectory=/var/www/myapp
# Ligne de commande pour lancer le serveur applicatif.
# Si /usr/bin/dotnet ne fonctionne pas, utiliser 'which dotnet' pour trouver le bon répertoire.
ExecStart=/usr/bin/dotnet /var/www/myapp/MYAPP.Server.dll
# Pour récupérer les logs avec journalctl, définir un nom explicite.
SyslogIdentifier=MyApp
# Il est recommandé qu'un utilisateur soit dédié à l'application, ici app-svc.
# Pour mettre à jour les droits, utiliser 'chown -R app-svc /var/www/myapp'.
User=app-svc
# Pour s'assurer du redémarrage après un crash.
Restart=always
RestartSec=5
KillSignal=SIGINT
ASPNETCORE_ENVIRONMENT=Production
Environment=DOTNET_NOLOGO=true

# https://inceptivetechnologies.com/blog/dot-net-core-kestrel-server-on-port-80/
# Pour mapper sur le port 80, désactiver les lignes suivantes :
# AmbientCapabilities=CAP_NET_BIND_SERVICE
# Environment=ASPNETCORE_URLS='http://+:80'

[Install]
WantedBy=multi-user.target

See the Microsoft documentation: https://learn.microsoft.com/en-us/aspnet/core/host-and-deploy/linux-nginx?view=aspnetcore-8.0&tabs=linux-ubuntu#create-the-service-file

Deploy the file:

sudo cp MyApp.service /etc/systemd/system/MyApp.service
sudo systemctl daemon-reload

Enable the application to start automatically:

sudo systemctl enable MyApp

Start the application as a service:

sudo systemctl start MyApp

Check that the service is running correctly:

sudo systemctl status MyApp

View the service's execution output:

journalctl -u MyApp.service -xb -n 100 --no-pager

Test the connection to the application from a web browser. You should land on the login page.

If a 50X-type error appears, check the Apache logs in /var/log/httpd/error_log. In case of a [proxy:error] ... Permission denied ... error, run:

sudo setsebool -P httpd_can_network_connect 1
sudo systemctl restart httpd

Version update procedure​

To deploy an application update:

  • Stop the application server.
sudo systemctl stop MyApp
  • If the configuration file has not been changed in this new version, copy appsettings.json to another directory.
  • Delete the files in the application directory.
  • Copy the files from the new version into the application directory.
  • For the application configuration:
    • If the configuration file has changed, edit the settings as during installation.
    • If the file has not changed, replace appsettings.json with the one copied earlier.
  • Restart the application server.
sudo systemctl start MyApp