install_22_4 [RADIUSdesk]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
<nav type="pills" justified="false">
  * [[:user_manuals|Back to Documentation]]
  * [[:install_22_4|Install on Ubuntu 22.04]]
</nav>

----

====== Installation of RADIUSdesk on Ubuntu 22.04 with Nginx ======
===== Skills required for the installation =====

To install RADIUSdesk, you need sufficient knowledge and experience with Linux:
  * Installing the Linux operating system.
  * Editing text files via the terminal with a text editor such as Vi or Nano.
  * Installing packages from a repository.
  * You must be familiar with how TCP/IP networks work.

===== Background =====

  * Nginx is a web server that seems to have overtaken Apache in terms of popularity and number of active websites on the Internet.
  * It is new, lightweight, fast, highly scalable and capable of handling a large load without overloading your system.
  * Nginx is the new Apache so to speak.
  * This section describes the steps you need to take to get RADIUSdesk up and running with a LEMP stack on Ubuntu 22.04
     * A LEMP stack is one of those acronyms you can use to impress your friends. It stands for Linux NginX MySQL and PHP.

<alert type="info">
  * We **(not so recently)** switched from CakePHPv3 to CakePHPv4.
  * If you manage devices with MESHdesk and APdesk, make sure you also run the instructions that include cake3 so that your system is backwards compatible.
  * The firmware on these devices may still point to the cake3 directory, so we need to include support for this directory.
</alert>

-----------

===== What we need =====

  * A standard Nginx installation on Ubuntu is actually very simple.
  * The more complicated part is customizing Nginx for the following tasks:

<panel type="default" no-body="true">
^ Requirement      ^ Comment       ^ 
| Interpreting PHP scripts    | We want the web server to call the PHP interpreter when a page with the .php extension is requested.  |
| Accessing MySQL functions from PHP | Since we are setting up a LEMP server, we need to install a MySQL server and access it from PHP. We will install MariaDB, which is a direct replacement for MySQL. |
| Change the expiration date of the HTTP headers to encourage caching. | We want files that do not change (e.g. CSS or images) to be cached on the client side to make the experience more pleasant for the client |
| Compress the text before it is sent to the client. | We can compress the text that flows between the client and the server and in this way reduce the number of bytes transmitted over the wire, which in turn should provide a more pleasant experience for the client |
| Enable rewrite rules in CakePHP for pretty URLs | CakePHP uses the .htaccess files in Apache to enable pretty URLs. Since Nginx does not support .htaccess files, we need to modify Nginx to behave the same way. |

</panel>

--------

===== HOWTO =====
<alert type="warning">
  * Please note that the behavior of the shell has changed in Ubuntu 22.04.
  * It seems that it does NOT execute the multi-line insertion of commands.
  * <wrap em>**So unfortunately you have to copy these commands line by line.**</wrap>
</alert>


==== Adding a sudo user  ====
  * We assume that you have a clean installation of Ubuntu 22.04 WITHOUT Apache installed.
  * If you have not yet added a sudo user add one now.
<code bash>
# Add the system user
sudo adduser system
sudo usermod -aG sudo system
# Update the system to the latest 
sudo apt-get upgrade
</code>

==== Introduction to network technology under Ubuntu 22.04  ====
  * If you do not yet have a working network configuration on the server on which you want to perform the installation, use this section as a reference, otherwise simply continue with the next section.
  * Since there is a big difference between Ubuntu 16.04 and Ubuntu 22.04, we believe this section will help those who need to get used to the new way of working.
  * We assume that you have a bare VM (like the one from https://www.osboxes.org/ubuntu-server/ )
  * We also assume that you have used it to create a VM in Virtualbox and now only see the local loopback interface (127.0.0.1) when you enter the ip a command.
  *  To see which interfaces are available (even if some are not yet configured)
<code bash>
ip a
 </code>
  * On my system, three interfaces are shown as I plan to use the VM as a router as well, with Coova Chili running on the one interface. So we have **lo**, **enp0s3** and **enp0s8**.
  * At the moment I will only configure these two interfaces as DHCP clients.
<code bash>
sudo vi /etc/netplan/50-cloud-init.yaml
 </code>
  * We edit the file so that it looks like this (adapt it to the interfaces of your system)
<code bash>
# This file is generated from the information provided by
# the data source.  Changes to it do not persist across an instance.
# To disable the network configuration functions of cloud-init, write a file
# /etc/cloud/cloud.cfg.d/99-disable-network-config.cfg with the following content:
# network: {config: disabled}
network:
    version: 2
    ethernets:
            enp0s3:
                    addresses: []
                    dhcp4: true
                    optional: true
            enp0s8:
                    addresses: []
                    dhcp4: true
                    optional: true
</code>
  * Apply the network configuration with the command:
<code bash>
sudo netplan --debug apply
</code>
  * If everything went well, our VM now has an IP address (via DHCP) that we can use.
<code bash>
ip addr
#Feedback contains
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
    inet 127.0.0.1/8 scope host lo
       valid_lft forever preferred_lft forever
    inet6 ::1/128 scope host
       valid_lft forever preferred_lft forever
2: enp0s3: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP group default qlen 1000
    link/ether 08:00:27:fe:57:09 brd ff:ff:ff:ff:ff:ff
    inet 192.168.1.111/24 brd 192.168.1.255 scope global dynamic enp0s3
       valid_lft 255675sec preferred_lft 255675sec
    inet6 fe80::a00:27ff:fefe:5709/64 scope link
       valid_lft forever preferred_lft forever
3: enp0s8: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP group default qlen 1000
    link/ether 08:00:27:8c:d3:32 brd ff:ff:ff:ff:ff:ff
    inet6 fe80::a00:27ff:fe8c:d332/64 scope link
       valid_lft forever preferred_lft forever
</code>
  * Now that we have set up a working network on our computer, we can continue.

==== Install Nginx ====
  * We assume that you have installed a clean installation of Ubuntu 22.04 WITHOUT Apache.


<alert type="success">
  * To remove Apache
   <code bash>
   sudo systemctl stop apache2.service
   sudo apt-get -y remove apache2
   </code>
</alert>

  * Make sure that it is up to date.
<code bash>
# Get the latest package lists
sudo apt-get update
# Update the system to the latest
sudo apt-get upgrade
</code>
  * Make sure that the English language pack is installed
<code bash>
sudo apt-get -y install language-pack-en-base
</code>
  * Install Nginx
<code bash>
sudo apt-get -y install nginx
</code>
  * Make sure that the web server is started and running
<code bash>
sudo systemctl stop nginx.service
sudo systemctl start nginx.service
</code>
  * Using a browser, navigate to the IP address of the server on which you have installed Nginx to ensure that Nginx is providing content, e.g. http://127.0.0.1
 
==== Configure Nginx to interpret .php files ====
=== php-fpm ===
  * The default installation of Nginx does not support serving .php files.
  * We will install a program (actually a service) called **php-fpm**.
  * This service waits for requests for interpretation.
  * Since Ubuntu 22.04 is quite dated by now, we can not use the standard version of PHP (8.1) that comes with Ubuntu.
  * RADIUSdesk's CakePHP app is now using CakePHPv5 which requires a minimum of PHP 8.2.
  * We will add an external, well maintained, repository from which we will install PHP 8.3.
  * PHP 8.3 is the default version on Ubuntu 24.04, so it keeps things predictable and according to a convention.
<code bash>
sudo apt update && sudo apt upgrade -y
sudo apt install software-properties-common -y
sudo add-apt-repository ppa:ondrej/php -y
sudo apt install php8.3 -y
sudo apt install php8.3-fpm
sudo systemctl enable php8.3-fpm
sudo systemctl start php8.3-fpm
</code>

==== Change Nginx ====
  * Now that the php-fpm service is installed, we need to modify the default Nginx server to use it.
  * Edit the default server file:
<code bash>
sudo vi /etc/nginx/sites-enabled/default
</code>
  * Add //index.php// to this line:
<code bash>
# Add index.php to the list if you are using PHP
index index.php index.html index.htm index.nginx-debian.html;
</code>
  * Enable PHP processing by leaving this section uncommented. Note that we are using the UNIX socket and that we are using 8.3 and not 7.4, which was originally specified in the configuration file.
<code bash>
# Pass PHP scripts to FastCGI server
#
location ~ \.php$ {
    include snippets/fastcgi-php.conf;
    #
    #       # With php-fpm (or other unix sockets):
    fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
    #       # With php-cgi (or other tcp sockets):
    #       fastcgi_pass 127.0.0.1:9000;
}
</code>
  * Activate the hiding of .htaccess files.
<code bash>
# deny access to .htaccess files, if Apache's document root
# concurs with nginx's one
#
location ~ /\.ht {
    deny all;
}
</code>
  * Reload the configuration of the Nginx web server
<code bash>
sudo systemctl reload nginx.service
</code>
  * Create a test //.php// file to confirm that it works.
<code bash>
sudo vi /var/www/html/test.php
</code>
  * Content:
<code bash>
<?php
    phpinfo();
?>
</code>
  * Navigate to http://127.0.0.1/test.php and check that the page displays the PHP information.

-----------
==== Install MariaDB ====
=== Why MariaDB? ===
  * We have found that the version of MySQL that is comes by default with Ubuntu 22.04 causes problems with RADIUSdesk.
  * For this reason, we have installed MariaDB as an alternative.
  * MariaDB is an open-source relational database management system that is often used as an alternative to MySQL as the database part of the popular LAMP stack (Linux, Apache, MySQL, PHP/Python/Perl).
  * It is intended as an immediate replacement for MySQL.
  * Be sure to provide a root password for the MariaDB database when prompted if you are security conscious, otherwise just hit the ESC key.

<code bash>
sudo apt-get -y install mariadb-server php8.3-mysql
sudo systemctl enable mariadb
sudo systemctl restart mariadb
sudo systemctl status mariadb
</code>

=== Deactivate strict mode ===
  * On Ubuntu 22.04, the bundled version of MariaDB is on version 10.3, which has introduced some strict modes that have some issues with the RADIUSdesk database implementation.
  * We will disable the strict SQL mode in MariaDB by creating a new file /etc/mysql/conf.d/disable_strict_mode.cnf
<code bash>
sudo vi /etc/mysql/conf.d/disable_strict_mode.cnf
</code>
  * Enter these two lines:
<code bash>
[mysqld]
sql_mode=IGNORE_SPACE,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION
</code>
=== Enable the Event Scheduler ===
  * MariaDB and MySQL has a built in Event Scheduler (like CRON for a database) which is disabled by default.
  * We make use of this feature to automatically optimize some of the database tables.
  * We will enable the Event Scheduler in MariaDB by creating a new file /etc/mysql/conf.d/enable_event_scheduler.cnf
<code bash>
sudo vi /etc/mysql/conf.d/enable_event_scheduler.cnf
</code>
  * Enter these two lines:
<code bash>
[mysqld]
event_scheduler=on
</code>
  * Save the file.
  *  Restart the MySQL server
<code bash>
sudo systemctl restart mariadb
</code>
  * You can confirm that it is now enabled by checking the following from the SQL terminal:
<code bash>
sudo mysql -u root 
MariaDB [(none)]> SHOW GLOBAL VARIABLES LIKE 'event_scheduler';
+-----------------+-------+
| Variable_name   | Value |
+-----------------+-------+
| event_scheduler | ON    |
+-----------------+-------+
1 row in set (0.001 sec)
</code>

-----
==== Performance tuning for Nginx ====
=== Change the expiry date for certain files ===
  * Edit the file ///etc/nginx/sites-available/default// file:
<code bash>
sudo vi /etc/nginx/sites-available/default
</code>
  * Add the following within the server section:
<code bash>
location ~ ^/cake4/.+\.(jpg|jpeg|gif|png|ico|js|css)$ {
    rewrite ^/cake4/rd_cake/webroot/(.*)$ /cake4/rd_cake/webroot/$1 break;
    rewrite ^/cake4/rd_cake/(.*)$ /cake4/rd_cake/webroot/$1 break;
    access_log off;
    expires max;
    add_header Cache-Control public;
}
</code>
  * Only add the following information if you require backward compatibility (MESHdesk and APdesk).
<code bash>
location ~ ^/cake3/.+\.(jpg|jpeg|gif|png|ico|js|css)$ {
    rewrite ^/cake3/rd_cake/webroot/(.*)$ /cake3/rd_cake/webroot/$1 break;
    rewrite ^/cake3/rd_cake/(.*)$ /cake3/rd_cake/webroot/$1 break;
    access_log off;
    expires max;
    add_header Cache-Control public;
}
</code>
  * Reload Nginx:
<code bash>
sudo systemctl reload nginx.service
</code>
----------

==== Install RADIUSdesk  ====
  * In the first part, everything was prepared for the installation of **RADIUSdesk**.
  * This part explains the steps for installing the latest **RADIUSdesk**.
  * RADIUSdesk consists of three components.
    * **rd** directory with its contents contains all the HTML and JavaScript code and is used as the presentation layer.
    * **cake4** is a CakePHPv5 (used to be CakePHPv4) application and can be considered the engine room. This is where the data is processed before it is displayed by the presentation layer.
    * **login** is a directory with various login pages that are managed centrally via the **RADIUSdesk Dynamic Login Pages** applet.
  * Later we will create various symbolic links from locations within the **rdcore** directory to locations within the document root directory of the web server.

=== Required packages ===
  * Make sure that the following packages are installed.
<code bash>
sudo apt-get -y install php8.3-cli php8.3-mysql php8.3-gd php8.3-curl php8.3-xml php8.3-mbstring php8.3-intl php8.3-sqlite3 git wget
sudo systemctl restart php8.3-fpm
</code>
  * Check out the **rdcore** git repository.
<code bash>
cd /var/www
sudo git clone https://github.com/RADIUSdesk/rdcore.git
</code>
  * This will create an **rdcore** directory containing some subfolders.
  * Check out the CakePHPv5 API back-end application
<code bash>
cd /var/www 
sudo git clone https://github.com/RADIUSdesk/rd_cake5.git
</code>
  * It is recommended that you also include the RD Mobile UI.
  * Check out the **rd_mobile** git repository.
<code bash>
cd /var/www
sudo git clone https://github.com/RADIUSdesk/rd_mobile.git
</code>

=== Create soft links ===
  * We will create softlinks in the directory where Nginx provides the RADIUSdesk content.
<code bash>
cd /var/www/html
sudo ln -s ../rdcore/rd ./rd
sudo ln -s ../rd_cake5 ./cake4
#If backward compatibility is required for older firmware of MESHdesk
sudo ln -s ../rd_cake5 ./cake3
sudo ln -s ../rdcore/login ./login
sudo ln -s ../rdcore/AmpConf/build/production/AmpConf ./conf_dev
sudo ln -s ../rd_cake5/rd_cake/setup/scripts/reporting ./reporting
#For the RD Mobile UI
sudo ln -s ../rd_mobile/build/production/RdMobile ./rd_mobile
</code>

=== Change ownership ===
  * Change the ownership of the following files to www-data so that Nginx can make changes to the files/directories
<code bash>
sudo mkdir -p  /var/www/html/cake4/rd_cake/logs
sudo mkdir -p /var/www/html/cake4/rd_cake/webroot/files/imagecache
sudo mkdir -p /var/www/html/cake4/rd_cake/tmp
sudo chown -R www-data. /var/www/html/cake4/rd_cake/tmp
sudo chown -R www-data. /var/www/html/cake4/rd_cake/logs
sudo chown -R www-data. /var/www/html/cake4/rd_cake/webroot/img/realms
sudo chown -R www-data. /var/www/html/cake4/rd_cake/webroot/img/dynamic_details
sudo chown -R www-data. /var/www/html/cake4/rd_cake/webroot/img/dynamic_photos
sudo chown -R www-data. /var/www/html/cake4/rd_cake/webroot/img/access_providers
sudo chown -R www-data. /var/www/html/cake4/rd_cake/webroot/img/hardwares
sudo chown -R www-data. /var/www/html/cake4/rd_cake/webroot/files/imagecache
</code>

=== The database ===
  * Make sure that the time zone on the server is set to UTC
  * Fill the time zone data in the DB
<code bash>
#NOTE FAILING TO DO THIS STEP will break the RADIUS graphs
#Some error messages may appear in the output, which is not a problem - no need to worry
sudo su
mysql_tzinfo_to_sql /usr/share/zoneinfo | mysql -u root  mysql
</code>

  * Create an empty database called //rd//
<code bash>
sudo su
mysql -u root
create database rd;
GRANT ALL PRIVILEGES ON rd.* to 'rd'@'127.0.0.1' IDENTIFIED BY 'rd';
GRANT ALL PRIVILEGES ON rd.* to 'rd'@'localhost' IDENTIFIED BY 'rd';
exit;
</code>
  * Populate the database:
<code bash>
sudo mysql -u root rd < /var/www/html/cake4/rd_cake/setup/db/rd.sql
</code>

<alert type="warning">
  * RADIUSdesk is under active development and sometimes we add SQL patches.
  * The SQL patches are located under **/var/www/html/cake4/rd_cake/setup/db/**.
  * These patches are non-destructive and you can run them against the database
  * See the example below
<code bash>
sudo mysql -u root rd < /var/www/html/cake4/rd_cake/setup/db/8.068_add_email_sms_histories.sql 
</code>
  * Some of these patches may add new columns to existing database tables. In this case, it is recommended to clear the CakePHP models (tables) cache to ensure that the latest changes are also applied there:
<code bash>
sudo su
cd /var/www/rdcore/html/rd_cake/tmp/cache/models
rm *
exit
</code>
</alert>

=== Configure Nginx ===

  * Configure Nginx to rewrite some RdCore URLs that start with ///cake4/rd_cake//.
  * Edit ///etc/nginx/sites-enabled/default//
<code bash>
sudo vi /etc/nginx/sites-enabled/default
</code>
  * Insert this section directly under the **server_name** entry. (This is so that this rule is **hit** first for the reporting side. Due to performance issues, we no longer use CakePHP for reporting.
<code bash>
server_name _;
location /cake4/rd_cake/node-reports/submit_report.json {
    try_files $uri $uri/ /reporting/reporting.php;
}
</code>
  * If you need support for backward compatibility (MESHdesk and APdesk), add this section as well:
<code bash>
location /cake3/rd_cake/node-reports/submit_report.json {
    try_files $uri $uri/ /reporting/reporting.php;
}
</code>
  * Insert the following configuration block into the server section (you can add this towards the end):
<code bash>
location /cake4/rd_cake {
   rewrite ^/cake4/rd_cake(.+)$ /cake4/rd_cake/webroot$1 break;
   try_files $uri $uri/ /cake4/rd_cake/index.php$is_args$args;
}
</code>
  *  If you need support for backward compatibility (MESHdesk and APdesk), add this section as well:
<code bash>
location /cake3/rd_cake {
   rewrite ^/cake3/rd_cake(.+)$ /cake3/rd_cake/webroot$1 break;
   try_files $uri $uri/ /cake3/rd_cake/index.php$is_args$args;
}
</code>
  * Reload the Nginx:
<code bash>
sudo systemctl reload nginx
</code>

=== Important URLs ===  
  * The following URLs are important to reach the user interface
  * To load the optimized user interface, go to http://127.0.0.1/rd/build/production/Rd/
  * If you want to deliver the content directly from the webroot, proceed as follows:
<code bash>
sudo cp -R /var/www/html/rd/build/production/Rd/* /var/www/html/
</code>
  * To load the RD Mobile UI, go to http://127.0.0.1/rd_mobile

== Login credentials == 
  * By default you can log in with the following credentials
Username: **root** Password: **admin**

-----

===== Cron scripts =====
  * **RADIUSdesk** requires some scripts that are executed at regular intervals to maintain a healthy and functioning system.
  * To activate the cron scripts, execute the following command, which adds the **RADIUSdesk** cron scripts to the cron system
<code bash>
sudo cp /var/www/html/cake4/rd_cake/setup/cron/rd_cake5 /etc/cron.d/
</code>
  * If you want to change the default intervals at which the scripts are executed, simply edit the file /etc/cron.d/cron3.

===== Add LETSENCRYPT certificate =====
  * Instead of repeating the existing documentation, we simply add a URL with the corresponding instructions
  * Before you follow the instructions in the URL, you should first do the following
<code bash>
sudo apt-get update
sudo apt-get -y install software-properties-common
</code>
  * https://www.digitalocean.com/community/tutorials/how-to-secure-nginx-with-let-s-encrypt-on-ubuntu-22-04
===== Next steps =====
  * Make sure that you also install **FreeRADIUS**.
  * [[install_22_4_freeradius|Install FreeRADIUS]]