How to Install UVdesk Helpdesk System on Ubuntu 20.04 LTS
Introduction
UVdesk is an open-source helpdesk system designed to offer multi-channel customer service. With the help of UVdesk, you can respond to support tickets from various online platforms in one single place.
This article explains how to install UVdesk Open Source 1.1.0 on an Ubuntu 20.04 LTS cloud server instance at Vultr.
Prerequisites
Before you begin, you need to:
- Deploy an Ubuntu 20.04 LTS server instance at Vultr with at least 4 GB of memory. And this article uses 203.0.113.100 as an example IPv4 address for the server instance.
- Prepare a domain name, such as helpdesk.example.com, for accessing the UVdesk helpdesk system.
1. Set Up DNS Records
If you are hosting the apex domain name example.com at Vultr, set up DNS records as follows to bind example.com, www.example.com, and helpdesk.example.com to the UVdesk server's IPv4 address 203.0.113.100:
|table|100| |thead| |tr| |th|20|Type| |th|20|Name| |th|20|Data| |th|20|TTL(seconds)| |th|20|Priority| |tbody| |tr| |td|A| |td| | |td|203.0.113.100| |td|300| |td| | |tr| |td|A| |td|www| |td|203.0.113.100| |td|300| |td| | |tr| |td|A| |td|helpdesk| |td|203.0.113.100| |td|300| |td| | |tr| |td|MX| |td| | |td|example.com| |td|300| |td|10| |tr| |td|NS| |td| | |td|ns1.vultr.com| |td|300| |td| | |tr| |td|NS| |td| | |td|ns2.vultr.com| |td|300| |td| |
To learn more about managing DNS through Vultr, see the introduction to Vultr DNS.
Instructions on setting up DNS records on other platforms may vary.
2. Prepare the System
Open your favorite terminal program on your desktop machine, such as PuTTY on Windows or iTerm2 on macOS, and log in to the UVdesk server instance as root with the initial password you found on the Server Details page.
After logging in, perform the tasks listed in this section to prepare the system.
Check if any swap space is in use on the system:
# swapon -sIf the system has swap allocated, skip to the next task. Otherwise, create a swap file of 2GB to smooth system operations:
# fallocate -l 2g /swap
# chmod 600 /swap
# mkswap /swap
# swapon /swap
# echo '/swap none swap defaults 0 0' | tee -a /etc/fstab
# free -mChange the system-provided password of the root user to a private and strong one, such as r00tyHvM%2kaz8E3:
# echo 'root:r00tyHvM%2kaz8E3' | chpasswd && history -d -1Add a non-root user with sudo privileges, such as uvdesk, and also set up a strong password for it, such as sud04QeXb$x#6&Cw:
# useradd -ms /bin/bash uvdesk
# echo 'uvdesk:sud04QeXb$x#6&Cw' | chpasswd && history -d -1
# echo 'uvdesk ALL=(ALL) NOPASSWD: ALL' | tee -a /etc/sudoers.d/designated
# chmod 0440 /etc/sudoers.d/designatedCreate UFW firewall rules to allow only traffic on 22(SSH), 80(HTTP), and 443(HTTPS) ports:
# ufw default deny
# ufw allow 22
# ufw allow 80
# ufw allow 443
# ufw enable
Command may disrupt existing ssh connections. Proceed with operation (y|n)? y:key_enter:
# ufw status verboseUpdate the system, and reboot the server instance to apply all updates:
# apt update
# apt upgrade -y
# apt autoremove -y
# shutdown -r nowAfter the server instance gets up and running again, log in as the newly created sudo user uvdesk to move on.
3. Install MariaDB 10.7
UVdesk Open Source 1.1.0 requires a Relational Database Management System (RDBMS), and this article prefers MariaDB 10.7, the latest stable release of MariaDB.
Set up the MariaDB 10.7 Advanced Package Tool (APT) repository:
$ sudo apt-get install software-properties-common dirmngr apt-transport-https -y
$ sudo apt-key adv --fetch-keys 'https://mariadb.org/mariadb_release_signing_key.asc'
$ sudo add-apt-repository 'deb [arch=amd64,arm64,ppc64el,s390x] https://mirrors.xtom.com/mariadb/repo/10.7/ubuntu focal main'Install MariaDB 10.7 server:
$ sudo apt update
$ sudo apt install mariadb-server -yStart the MariaDB service and make it automatically start on boot:
$ sudo systemctl start mariadb.service
$ sudo systemctl enable mariadb.serviceRun an official script to secure the installation of MariaDB 10.7 server:
$ sudo mariadb-secure-installationReply to questions as follows to enhance the security of the MariaDB 10.7 installation:
Enter current password for root (enter for none): :key_enter:
Switch to unix_socket authentication [Y/n] n:key_enter:
Change the root password? [Y/n] n:key_enter:
Remove anonymous users? [Y/n] y:key_enter:
Disallow root login remotely? [Y/n] y:key_enter:
Remove test database and access to it? [Y/n] y:key_enter:
Reload privilege tables now? [Y/n] y:key_enter:Find possible locations of the MariaDB configuration files:
$ mysql --help | grep "Default options" -A 1
Default options are read from the following files in the given order:
/etc/my.cnf /etc/mysql/my.cnf ~/.my.cnfCreate a global MariaDB configuration file at the first location:
$ sudo nano /etc/my.cnfPopulate the file as follows to set utf8mb4 as the default character set for MariaDB 10.7:
[client]
default-character-set = utf8mb4
[mysql]
default-character-set = utf8mb4
[mysqld]
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ciPress Ctrl+O, Enter, and Ctrl+X to save the configuration file and quit.
Restart the MariaDB service to load new settings:
$ sudo systemctl restart mariadb.service4. Install PHP 8.0
Create a third-party PHP Personal Package Archives (PPA) repository:
$ LC_ALL=C.UTF-8 sudo add-apt-repository ppa:ondrej/php -y
$ sudo apt update
$ sudo apt upgrade -yInstall required PHP 8.0 packages for UVdesk, including the FastCGI Process Manager (FPM) extension for working with Nginx:
$ sudo apt install php8.0 php8.0-bcmath php8.0-common php8.0-curl php8.0-fpm php8.0-gd php8.0-imap php8.0-intl php8.0-ldap php8.0-mailparse php8.0-mbstring php8.0-mysql php8.0-mongodb php8.0-opcache php8.0-soap php8.0-tidy php8.0-xml php8.0-zip -y
$ php -v
PHP 8.0.17 (cli) (built: Mar 20 2022 17:04:09) ( NTS )
Copyright (c) The PHP Group
Zend Engine v4.0.17, Copyright (c) Zend Technologies
with Zend OPcache v8.0.17, Copyright (c), by Zend TechnologiesSet up the proper timezone according to the location of your server instance:
$ sudo sed -i 's#;date.timezone =#date.timezone = America/Los_Angeles#' /etc/php/8.0/fpm/php.ini
$ sudo sed -i 's#;date.timezone =#date.timezone = America/Los_Angeles#' /etc/php/8.0/cli/php.iniFor other timezones, refer to the PHP Timezones List page.
Increase the memory limit for PHP-FPM 8.0 from 128MB to 1GB:
$ sudo sed -i 's/memory_limit = 128M/memory_limit = 1G/' /etc/php/8.0/fpm/php.iniIncrease execution time to 60 seconds for both PHP-FPM and PHP-CLI:
$ sudo sed -i 's/max_execution_time = 30/max_execution_time = 60/' /etc/php/8.0/fpm/php.ini
$ sudo sed -i 's/max_execution_time = 30/max_execution_time = 60/' /etc/php/8.0/cli/php.iniChange PHP-FPM 8.0 settings to make it work with Nginx:
$ sudo sed -i 's/user = www-data/user = nginx/' /etc/php/8.0/fpm/pool.d/www.conf
$ sudo sed -i 's/group = www-data/group = nginx/' /etc/php/8.0/fpm/pool.d/www.conf
$ sudo sed -i 's/listen.owner = www-data/listen.owner = nginx/' /etc/php/8.0/fpm/pool.d/www.conf
$ sudo sed -i 's/listen.group = www-data/listen.group = nginx/' /etc/php/8.0/fpm/pool.d/www.confStart the PHP-FPM 8.0 service and make it automatically start on boot:
$ sudo systemctl start php8.0-fpm.service
$ sudo systemctl enable php8.0-fpm.service5. Install Nginx 1.21.6
UVdesk Open Source 1.1.0 needs to work with a web server, such as Apache or Nginx. This article prefers the latest mainline release of Nginx, which is Nginx 1.21.6 for now.
Install dependencies for installing Nginx:
$ sudo apt install curl gnupg2 ca-certificates lsb-release ubuntu-keyring -yImport the official Nginx GPG signing key:
$ curl https://nginx.org/keys/nginx_signing.key | gpg --dearmor \
| sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/nullIdentify the GPG signing key stored in the downloaded file:
$ gpg --dry-run --quiet --import --import-options import-show /usr/share/keyrings/nginx-archive-keyring.gpgMake sure that the output contains the full fingerprint 573BFD6B3D8FBC641079A6ABABF5BD827BD9BF62. Otherwise, delete the downloaded file and re-do the import.
Set up the mainline Nginx APT repository:
$ echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \
http://nginx.org/packages/mainline/ubuntu `lsb_release -cs` nginx" \
| sudo tee /etc/apt/sources.list.d/nginx.listSet up repository pinning to prefer official Nginx mainline packages to distribution-provided ones:
$ echo -e "Package: *\nPin: origin nginx.org\nPin: release o=nginx\nPin-Priority: 900\n" \
| sudo tee /etc/apt/preferences.d/99nginxInstall the mainline version of Nginx, which is Nginx 1.21.6 for now:
$ sudo apt update
$ sudo apt install nginx -yConfirm the installation of Nginx:
$ nginx -V
nginx version: nginx/1.21.6
built by gcc 9.3.0 (Ubuntu 9.3.0-10ubuntu2)
built with OpenSSL 1.1.1f 31 Mar 2020
TLS SNI support enabled
...Start the Nginx service and make it automatically start on boot:
$ sudo systemctl start nginx.service
$ sudo systemctl enable nginx.service6. Get a Let's Encrypt Certificate
Valid TLS certificates are indispensable for enabling HTTPS access to a website. If you don't have any valid TLS certificate yet, follow instructions below to get free Let's Encrypt certificates for helpdesk.example.com, www.example.com, and example.com.
Update the snapd program:
$ sudo snap install core; sudo snap refresh coreRemove any existing Certbot programs installed from other sources to avoid possible conflicts:
$ sudo apt-get remove certbot
$ sudo sed -i '/certbot-auto/d' /etc/crontab
$ sudo rm -f /usr/local/bin/cert-bot
$ sudo rm -rf /opt/eff.orgInstall Certbot using the snapd program:
$ sudo snap install --classic certbotCreate a symbolic link in the /usr/bin directory pointing to the newly installed Certbot program:
$ sudo ln -s /snap/bin/certbot /usr/bin/certbotGet Let's Encrypt certificates for helpdesk.example.com, www.example.com, and example.com through Certbot and its Nginx plugin:
$ sudo certbot certonly --nginx --email admin@example.com --agree-tos --no-eff-email -d helpdesk.example.com -d www.example.com -d example.comThe Certbot program has set up automatic certificate renewals by default to prevent the Let's Encrypt TLS certificates from expiring in 90 days. Use the commands listed below to confirm these renewals are on schedule:
$ sudo certbot renew --dry-run
$ sudo systemctl list-timers | grep snap.certbot.renew.service7. Install Composer 2.3.3
UVdesk uses Composer to manage dependencies. Use the following commands to install Composer 2.3.3, the latest stable release of Composer for now:
$ cd
$ php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
$ php -r "if (hash_file('sha384', 'composer-setup.php') === '906a84df04cea2aa72f40b5f787e49f22d4c2f19492ac310e8cba5b96ac8b64115ac402c8cd292b8a03482574915d1a8') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"
$ php composer-setup.php
$ php -r "unlink('composer-setup.php');"
$ sudo mv composer.phar /usr/local/bin/composer
$ composer -V
Composer version 2.3.3 2022-04-01 22:15:35Notice: The instructions listed above are only for installing Composer 2.3.3. Always check for the proper instructions for installing a newer version of Composer on the official Composer Download page.
8. Install UVdesk 1.1.0
Create a MariaDB Database for UVdesk
Log in to the MariaDB shell as root:
$ sudo mysql -u rootIn the MariaDB shell, create a database named uvdesk, a database user named uvdesk, and the database user's password uv8jTm9LHtez0MKn:
MariaDB [(none)]> CREATE DATABASE uvdesk CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
MariaDB [(none)]> CREATE USER 'uvdesk'@'localhost' IDENTIFIED BY 'uv8jTm9LHtez0MKn';
MariaDB [(none)]> GRANT ALL PRIVILEGES ON uvdesk.* TO 'uvdesk'@'localhost' IDENTIFIED BY 'uv8jTm9LHtez0MKn' WITH GRANT OPTION;
MariaDB [(none)]> FLUSH PRIVILEGES;
MariaDB [(none)]> EXIT;Configure Nginx to Host UVdesk
Create required directories for hosting the UVdesk site:
$ sudo mkdir /etc/nginx/{sites-available,sites-enabled,modules-enabled}
$ sudo mkdir /var/www/
$ sudo chown uvdesk:uvdesk /var/www/Back up preset Nginx configuration files:
$ sudo mv /etc/nginx/nginx.conf /etc/nginx/nginx.conf.bak
$ sudo mv /etc/nginx/conf.d/default.conf /etc/nginx/conf.d/default.conf.bakGenerate a 2048-bit Diffie-Hellman parameters file to increase SSL security:
$ sudo openssl dhparam -out /etc/nginx/dhparam.pem 2048Create the main Nginx configuration file:
$ sudo nano /etc/nginx/nginx.confPopulate the file with:
user nginx;
pid /run/nginx.pid;
worker_processes auto;
worker_rlimit_nofile 65535;
# Load modules
include /etc/nginx/modules-enabled/*.conf;
events {
multi_accept on;
worker_connections 65535;
}
http {
charset utf-8;
sendfile on;
tcp_nopush on;
tcp_nodelay on;
server_tokens off;
log_not_found off;
types_hash_max_size 2048;
types_hash_bucket_size 64;
client_max_body_size 16M;
# MIME
include mime.types;
default_type application/octet-stream;
# Logging
access_log /var/log/nginx/access.log;
error_log /var/log/nginx/error.log warn;
# SSL
ssl_session_timeout 1d;
ssl_session_cache shared:SSL:10m;
ssl_session_tickets off;
# Diffie-Hellman parameter for DHE ciphersuites
ssl_dhparam /etc/nginx/dhparam.pem;
# Mozilla Intermediate configuration
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;
# OCSP Stapling
ssl_stapling on;
ssl_stapling_verify on;
resolver 1.1.1.1 1.0.0.1 8.8.8.8 8.8.4.4 208.67.222.222 208.67.220.220 valid=60s;
resolver_timeout 2s;
# Load configurations
include /etc/nginx/conf.d/*.conf;
include /etc/nginx/sites-enabled/*;
}Press Ctrl+O, Enter, and Ctrl+X to save and quit.
Create the Nginx configuration file for helpdesk.example.com:
$ sudo nano /etc/nginx/sites-available/helpdesk.example.com.confPopulate the file with:
server {
listen 443 ssl http2;
listen [::]:443 ssl http2;
server_name helpdesk.example.com;
set $base /var/www/helpdesk.example.com;
root $base/public;
# SSL
ssl_certificate /etc/letsencrypt/live/helpdesk.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/helpdesk.example.com/privkey.pem;
ssl_trusted_certificate /etc/letsencrypt/live/helpdesk.example.com/chain.pem;
# . files
location ~ /\.(?!well-known) {
deny all;
}
# index.php
index index.php;
# index.php fallback
location / {
try_files $uri $uri/ /index.php?$query_string;
}
# favicon.ico
location = /favicon.ico {
log_not_found off;
access_log off;
}
# robots.txt
location = /robots.txt {
log_not_found off;
access_log off;
}
# assets, media
location ~* \.(?:css(\.map)?|js(\.map)?|jpe?g|png|gif|ico|cur|heic|webp|tiff?|mp3|m4a|aac|ogg|midi?|wav|mp4|mov|webm|mpe?g|avi|ogv|flv|wmv)$ {
expires 7d;
access_log off;
}
# svg, fonts
location ~* \.(?:svgz?|ttf|ttc|otf|eot|woff2?)$ {
add_header Access-Control-Allow-Origin "*";
expires 7d;
access_log off;
}
# gzip
gzip on;
gzip_vary on;
gzip_proxied any;
gzip_comp_level 6;
gzip_types text/plain text/css text/xml application/json application/javascript application/rss+xml application/atom+xml image/svg+xml;
# handle .php
location ~ \.php$ {
fastcgi_pass unix:/var/run/php/php-fpm.sock;
# 404
try_files $fastcgi_script_name =404;
# default fastcgi_params
include fastcgi_params;
# fastcgi settings
fastcgi_index index.php;
fastcgi_buffers 8 16k;
fastcgi_buffer_size 32k;
# fastcgi params
fastcgi_param DOCUMENT_ROOT $realpath_root;
fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
fastcgi_param PHP_ADMIN_VALUE "open_basedir=$base/:/usr/lib/php/:/tmp/";
}
}
# Redirect HTTP to HTTPS
server {
listen 80;
listen [::]:80;
server_name helpdesk.example.com;
location / {
return 301 https://helpdesk.example.com$request_uri;
}
}
# Disallow direct access to the server's IPv4 and IPv6 addresses
server {
listen 80 default_server;
listen [::]:80 default_server;
server_name "";
return 444;
}Press Ctrl+O, Enter, and Ctrl+X to save and quit.
Create a symbolic link to enable the configuration file for helpdesk.example.com:
$ sudo ln -s /etc/nginx/sites-available/helpdesk.example.com.conf /etc/nginx/sites-enabled/Test newly created Nginx configurations and restart the Nginx service:
$ sudo nginx -t
$ sudo systemctl restart nginx.servicePoint your favorite web browser to http://helpdesk.example.com/ to verify URL redirects you setup earlier. If all goes well, it should switch to https://helpdesk.example.com/.
Install UVdesk 1.1.0
Use Composer to install dependencies for UVdesk:
$ cd /var/www
$ composer clear-cache
$ composer create-project uvdesk/community-skeleton helpdesk.example.comDuring the installation, reply to questions as follows:
...
WARNING doctrine/doctrine-bundle (>=2.4): From github.com/symfony/recipes:master
Do you want to include Docker configuration from recipes? (defaults to y): y:key_enter:
...
WARNING google/recaptcha (>=1.1): From github.com/symfony/recipes-contrib:master
The recipe for this package comes from the "contrib" repository, which is open to community contributions.
Do you want to execute this recipe? (defaults to n): y:key_enter:Install the acl utility:
$ sudo apt install aclGrant permissions on specific directories and files for both the command line user uvdesk and the Nginx user nginx:
$ sudo setfacl -dR -m u:nginx:rwX -m u:uvdesk:rwX /var/www/helpdesk.example.com/var
$ sudo setfacl -R -m u:nginx:rwX -m u:uvdesk:rwX /var/www/helpdesk.example.com/var
$ sudo setfacl -dR -m u:nginx:rwX -m u:uvdesk:rwX /var/www/helpdesk.example.com/public
$ sudo setfacl -R -m u:nginx:rwX -m u:uvdesk:rwX /var/www/helpdesk.example.com/public
$ sudo setfacl -dR -m u:nginx:rwX -m u:uvdesk:rwX /var/www/helpdesk.kpwiki.com/config
$ sudo setfacl -R -m u:nginx:rwX -m u:uvdesk:rwX /var/www/helpdesk.kpwiki.com/config
$ sudo setfacl -m u:nginx:rwX -m u:uvdesk:rwX /var/www/helpdesk.kpwiki.com/.envRestart the Nginx service:
$ sudo systemctl restart nginx.servicePoint your favorite web browser to http://helpdesk.example.com/ again to start the UVdesk web installation wizard.
- On the Welcome page, click the LET'S BEGIN button.
- On the System Requirements page, make sure the system meets all requirements and click the PROCEED button.
- On the Database Configuration page, input database user credentials as follows, and click the PROCEED button:
- Server: 127.0.0.1
- Port: 3306
- Username: uvdesk
- Password: uv8jTm9LHtez0MKn
- Database: uvdesk
- On the Create Super Admin Account page, input the administrator's credentials and click the PROCEED button:
- Name: John Doe
- Email: admin@example.com
- Password: admin4Est@7sfz8G
- Confirm Password: admin4Est@7sfz8G
- On the Website Configuration page, input member and customer panel prefixes, and click the PROCEED button:
- Member Panel Prefix: member
- Customer Panel Prefix: customer
- On the last page, click the INSTALL NOW button to begin the installation.
Notice: If the installation fails because of an SQL error "SQLSTATE[42S02]: Base table or view not found: 1146 Table 'uvdesk.uv_support_role' doesn't exist," use commands listed below to fix the problem:
$ cd /var/www/helpdesk.example.com/
$ php bin/console doctrine:migrations:diff
$ php bin/console doctrine:migrations:migrate
$ php bin/console c:c
$ sudo shutdown -r nowThen refresh the UVdesk web installation wizard page http://helpdesk.example.com/ to perform the installation again.
Next Steps
Having the UVdesk helpdesk system installed, log in as the administrator you created earlier from UVdesk Support Center, and then set up a mailbox to send and receive emails from UVdesk.