Installing Amplia Reg on Ubuntu Server
To install an on-premises instance of Amplia Reg 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)
- Amplia instance with:
- A CA to issue end-user certificates (either a root CA or an intermediate CA)
- A CA to issue device certificates
- PKI SDK license (in Base64 format)
- Web PKI license (Base64/binary format)
- DNS entry previously created for the app
- Connection string to a previously created SQL Server or PostgreSQL database
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:
- Register the Microsoft key and add the product repository (this only needs to be done on versions prior to 22 and once per machine)
- 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 Amplia Reg
Create a local user to run the Amplia Reg server:
mkdir /var/ampliareg
useradd --system --home-dir /var/ampliareg ampliareg
chown ampliareg:ampliareg /var/ampliareg
Create the site folder, download and extract the binaries:
Note
To test the next version of Amplia Reg, currently in Release Candidate stage, replace ampliareg-x.y.z.tar.gz on the following commands
with ampliareg-2.6.0-rc15.tar.gz. Beware: Release Candidate versions are not production-ready and thus should only be installed on staging or test environments!
mkdir /usr/share/ampliareg
curl -O https://cdn.lacunasoftware.com/ampliareg/ampliareg-2.5.2.tar.gz
tar xzf ampliareg-2.5.2.tar.gz -C /usr/share/ampliareg
chmod -R a=,u+rwX,go+rX /usr/share/ampliareg
Note
Site binaries can be read by any user and can only be changed by root users. This means that the application user (ampliareg) can read but not change the files, which is intentional.
Create the configuration file from the given template:
mkdir /etc/ampliareg
cp /usr/share/ampliareg/config-templates/linux/appsettings.conf /etc/ampliareg/
chown -R root:ampliareg /etc/ampliareg
chmod -R a=,u+rwX,g+rX /etc/ampliareg
Note
Configuration files can only be read by members of the ampliareg 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.
Configure Amplia Reg
Edit the configuration file and follow the instructions on it to configure your Amplia Reg instance:
nano /etc/ampliareg/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
Also on the [General] section, to fill the RootPasswordHash setting choose a strong password for root access to the dashboard and hash it:
dotnet /usr/share/ampliareg/Lacuna.AmpliaRegNg.Site.dll -- hash-root-pass
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:
- Sign in to your Amplia instance
- Click on Applications on the left menu, then on Add
- Fill out a name and select the subscription on which the certificates should be issued (you most likely have a single subscription, so select it)
- Mark the Worker role
- Click on Create
- Click on Keys, then on Add
- Fill out some description and, on the Expiration field, choose "Never expires"
- Click on Create
- Copy the API key generated (this value cannot be retrieved later)
To fill the Amplia:DeviceCertificates section, follow the steps in Create a CA for device certificates.
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/ampliareg.service
nano /etc/systemd/system/ampliareg.service
Enter the following:
[Unit]
Description=Amplia Reg
[Service]
WorkingDirectory=/usr/share/ampliareg
ExecStart=/usr/bin/dotnet Lacuna.AmpliaRegNg.Site.dll
Restart=always
RestartSec=10
KillSignal=SIGINT
SyslogIdentifier=ampliareg
User=ampliareg
Environment=ASPNETCORE_ENVIRONMENT=Linux
Environment=ASPNETCORE_URLS=http://+:5002
Environment=DOTNET_PRINT_TELEMETRY_MESSAGE=false
[Install]
WantedBy=multi-user.target
Save the file, then enable the service and start it:
systemctl enable ampliareg
systemctl start ampliareg
systemctl status ampliareg
The expected output is similar to:
* ampliareg.service - Amplia Reg
Loaded: loaded (/etc/systemd/system/ampliareg.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/ampliareg.service
└─10960 /usr/bin/dotnet Lacuna.AmpliaRegNg.Site.dll
...
Dec 04 12:45:08 server.patorum.com ampliareg[32562]: Hosting environment: Production
Dec 04 12:45:08 server.patorum.com ampliareg[32562]: Content root path: /usr/share/ampliareg
Dec 04 12:45:08 server.patorum.com ampliareg[32562]: Now listening on: http://localhost:5002
Dec 04 12:45:08 server.patorum.com ampliareg[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 ampliareg
To test that the Amplia Reg server is running, run:
curl http://localhost:5002/api/system/info
The expected output is something like:
{"productName":"Lacuna Amplia Reg","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 Amplia Reg:
touch /etc/nginx/sites-available/ampliareg
nano /etc/nginx/sites-available/ampliareg
Enter the following, replacing the domain on the server_name entry:
server {
listen 80;
server_name ampliareg.patorum.com;
client_max_body_size 11000000;
location / {
proxy_pass http://localhost:5002;
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/ampliareg /etc/nginx/sites-enabled/ampliareg
Test the Nginx configuration and reload it:
nginx -t
nginx -s reload
Test the site:
curl -H "Host: ampliareg.patorum.com" http://localhost/api/system/info
Warning
For production environments, it is essential to configure reCAPTCHA to protect the API from abuse
Post-installation steps
Follow the post-installation procedure to complete the installation.