Edit on GitHub

Installing Lacuna PSC on Ubuntu Server

To install an on-premises instance of Lacuna PSC on Ubuntu Server, follow the steps below. For other platforms, click here.

Prerequisites

  • Ubuntu Server (any version currently in support by vendor, latest LTS version recommended)

Install the ASP.NET Core Runtime 6.0

Important

These instructions assume you are logged in as root. If you are not, run sudo su - before continuing!

Follow the instructions below depending on your Ubuntu version to:

  1. Register the Microsoft key and add the product repository (this only needs to be done on versions prior to 22 and once per machine)
  2. Install the package aspnetcore-runtime-6.0

Ubuntu 22.04 (LTS)

apt-get update
apt-get install aspnetcore-runtime-6.0

Ubuntu 20.04 (LTS)

curl -O https://packages.microsoft.com/config/ubuntu/20.04/packages-microsoft-prod.deb
dpkg -i packages-microsoft-prod.deb
rm packages-microsoft-prod.deb

apt-get update
apt-get install aspnetcore-runtime-6.0

Ubuntu 18.04 (LTS)

curl -O https://packages.microsoft.com/config/ubuntu/18.04/packages-microsoft-prod.deb
dpkg -i packages-microsoft-prod.deb
rm packages-microsoft-prod.deb

apt-get update
apt-get install aspnetcore-runtime-6.0

Ubuntu 16.04 (LTS)

curl -O https://packages.microsoft.com/config/ubuntu/16.04/packages-microsoft-prod.deb
dpkg -i packages-microsoft-prod.deb
rm packages-microsoft-prod.deb

apt-get update
apt-get install aspnetcore-runtime-6.0

Test the installation

To test the installation, run:

dotnet --list-runtimes

The expected output is similar to:

Microsoft.AspNetCore.App 6.0.* [*/dotnet/shared/Microsoft.AspNetCore.App]
Microsoft.NETCore.App 6.0.* [*/dotnet/shared/Microsoft.NETCore.App]
Tip

For other operating system versions and alternative ways to install the ASP.NET Core Runtime, see this page

Install additional dependencies:

apt-get install libc6-dev libgdiplus

Install Lacuna PSC

Create a local user to run the Lacuna PSC server:

mkdir /var/lacuna-psc
useradd --system --home-dir /var/lacuna-psc lacuna-psc
chown lacuna-psc:lacuna-psc /var/lacuna-psc

Create the site folder, download and extract the binaries:

Note

To test the next version of Lacuna PSC, currently in Release Candidate stage, replace psc-x.y.z.tar.gz on the following commands with psc-1.3.0-rc01.tar.gz. Beware: Release Candidate versions are not production-ready and thus should only be installed on staging or test environments!

mkdir /usr/share/lacuna-psc
curl -O https://cdn.lacunasoftware.com/psc/psc-1.2.5.tar.gz
tar xzf psc-1.2.5.tar.gz -C /usr/share/lacuna-psc
chmod -R a=,u+rwX,go+rX /usr/share/lacuna-psc
Note

Site binaries can be read by any user and can only be changed by root users. This means that the application user (lacuna-psc) can read but not change the files, which is intentional.

Create the configuration file from the given template:

mkdir /etc/lacuna-psc
cp /usr/share/lacuna-psc/config-templates/linux/appsettings.conf /etc/lacuna-psc/
chown -R root:lacuna-psc /etc/lacuna-psc
chmod -R a=,u+rwX,g+rX /etc/lacuna-psc
Note

Configuration files can only be read by members of the lacuna-psc group and can only be changed by the root user. This is important to protect sensitive data stored on the configuration files from unauthorized access.

Generate a certificate to sign OAuth tokens

Generate a self-signed certificate to sign OAuth tokens issued by the application:

dotnet /usr/share/lacuna-psc/Lacuna.Psc.Site.dll -- gen-cert "Patorum PSC" "" /etc/lacuna-psc/issuer.pfx
chown -R root:lacuna-psc /etc/lacuna-psc && chmod -R a=,u+rwX,g+rX /etc/lacuna-psc

Configure the trusted roots

Edit the certificate trust configuration file:

mkdir /var/lacuna-psc/trustarbitrators
touch /var/lacuna-psc/trustarbitrators/psc-trust.json
chown -R lacuna-psc:lacuna-psc /var/lacuna-psc
nano /var/lacuna-psc/trustarbitrators/psc-trust.json

Add the trusted root certificates as follows:

{
  "Version": "2019-05-09",
  "StandardPkis": [
    "Brazil",
    "Italy",
    "Peru"
  ],
  "TrustedRoots": [
    "MIIFzDC...",
    "MIIFzDC..."
  ]
}
  • The field Version must be kept as is above
  • The collection StandardPkis may contain Brazil, Italy or Peru denoting that the root certificates for each of these countries are to be trusted
  • The collection TrustedRoots may contain additional trusted CA root certificates encoded in Base64
Warning

This file does not support comments

Configure Lacuna PSC

Edit the configuration file and follow the instructions on it to configure your Lacuna PSC instance:

nano /etc/lacuna-psc/appsettings.conf

On the [General] section, to fill the EncryptionKey setting generate a 256-bit key to encrypt sensitive data stored on the database:

openssl rand -base64 32

On the [Amplia] section, to fill the ApiKey setting you must create an application on your existing Amplia instance and generate an API key for it:

  1. Sign in to your Amplia instance
  2. Click on Applications on the left menu, then on Add
  3. Fill out a name and select the subscription on which the certificates should be issued (not on Sys Admin)
  4. Mark the Worker role
  5. Click on Create
  6. Click on Keys, then on Add
  7. Fill out some description and, on the Expiration field, choose "Never expires"
  8. Click on Create
  9. Copy the API key generated (this value cannot be retrieved later)

Follow the steps in Configure OpenID Connect to fill out the [Oidc] section.

Fill the remaining settings according to the instructions on the configuration file.

Set up a daemon

Create the service definition file:

touch /etc/systemd/system/lacuna-psc.service
nano /etc/systemd/system/lacuna-psc.service

Enter the following:

[Unit]
Description=Lacuna PSC

[Service]
WorkingDirectory=/usr/share/lacuna-psc
ExecStart=/usr/bin/dotnet Lacuna.Psc.Site.dll
Restart=always
RestartSec=10
KillSignal=SIGINT
SyslogIdentifier=lacuna-psc
User=lacuna-psc
Environment=ASPNETCORE_ENVIRONMENT=Linux
Environment=ASPNETCORE_URLS=http://+:5003
Environment=DOTNET_PRINT_TELEMETRY_MESSAGE=false

[Install]
WantedBy=multi-user.target

Save the file, then enable the service and start it:

systemctl enable lacuna-psc
systemctl start lacuna-psc
systemctl status lacuna-psc

The expected output is similar to:

* lacuna-psc.service - Lacuna PSC
   Loaded: loaded (/etc/systemd/system/lacuna-psc.service; enabled; vendor preset: enabled)
   Active: active (running) since Sun 2019-07-07 05:50:04 UTC; 4min 22s ago
 Main PID: 10960 (dotnet)
    Tasks: 31 (limit: 2319)
   CGroup: /system.slice/lacuna-psc.service
           └─10960 /usr/bin/dotnet Lacuna.Psc.Site.dll

...

Dec 04 12:45:08 server.patorum.com lacuna-psc[32562]: Hosting environment: Production
Dec 04 12:45:08 server.patorum.com lacuna-psc[32562]: Content root path: /usr/share/lacuna-psc
Dec 04 12:45:08 server.patorum.com lacuna-psc[32562]: Now listening on: http://localhost:5003
Dec 04 12:45:08 server.patorum.com lacuna-psc[32562]: Application started. Press Ctrl+C to shut down.
Hint: Some lines were ellipsized, use -l to show in full.

If necessary, restart the service: systemctl restart lacuna-psc

To test that the Lacuna PSC server is running, run:

curl http://localhost:5003/api/system/info

The expected output is something like:

{"productName":"Lacuna PSC","productVersion":"...","spaVersion":"...","timestamp":"..."}

Set up a reverse proxy server

Note

If you prefer to use Apache instead of Nginx, see this article.

Install Nginx (if not already installed):

apt-get install nginx

Test that Nginx is running:

curl -I http://localhost/

Check the first lines of the output, which should be similar to:

HTTP/1.1 200 OK
Server: nginx/...
...

Disable the default Nginx site:

rm /etc/nginx/sites-enabled/default

Create a site configuration file for Lacuna PSC:

touch /etc/nginx/sites-available/lacuna-psc
nano /etc/nginx/sites-available/lacuna-psc

Enter the following, replacing the domain on the server_name entry:

server {
    listen        80;
    server_name   psc.patorum.com;
    location / {
        proxy_pass         http://localhost:5003;
        proxy_http_version 1.1;
        proxy_set_header   Upgrade $http_upgrade;
        proxy_set_header   Connection keep-alive;
        proxy_set_header   Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;
    }
}
Tip

Ideally, your site configuration should contain the entries ssl_certificate and ssl_certificate_key with a valid SSL certificate. This configuration is outside of the scope of these instructions.

Enable the site:

ln -sf /etc/nginx/sites-available/lacuna-psc /etc/nginx/sites-enabled/lacuna-psc

Test the Nginx configuration and reload it:

nginx -t
nginx -s reload

Test the site:

curl -H "Host: psc.patorum.com" http://localhost/api/system/info
Warning

For production environments, it is essential to configure Firebase App Check and reCAPTCHA to protect the API from abuse

See also