Ubuntu

36min
Installing Passwork on following OS:
Ubuntu 20.04
Ubuntu 22.04
On this page you can switch between blocks of code to view the commands applicable to your version of Ubuntu
1. Minimum system requirements
Passwork is not resource-heavy. How much disk space, RAM and CPU power you will need depends on the number of active users, the amount of stored data, and your requirements for fault-tolerance.
See the full system requirements﻿.
If your server has 2-4 GB of RAM, we recommend enabling the SWAP file for libraries to compile properly
﻿Enabling SWAP file on Linux﻿ 
2. Steps before installation
First, gain root access and update the local packages:
bash
sudo -i 
apt-get update
sudo -i 
apt-get update
﻿
Then, install the Git version control package, Apache2 web-server and curl data transfer tool:
bash
apt-get install -y git apache2 unzip curl
apt-get install -y git apache2 unzip curl
﻿
3. Installing PHP
Install the software-properties-common package and add the ppa:ondrej/php repository:
Shell
apt-get install -y software-properties-common
add-apt-repository -y ppa:ondrej/php
apt-get install -y software-properties-common
add-apt-repository -y ppa:ondrej/php
﻿
Then update the local packages and repositories:
Shell
apt-get update
apt-get update
﻿
And install PHP and its extensions:
Shell
apt-get install -y php8.2 php8.2-dev php8.2-ldap php8.2-xml php8.2-bcmath php8.2-mbstring php8.2-xml php8.2-curl php8.2-opcache php8.2-readline php8.2-zip php-pear
apt-get install -y php8.2 php8.2-dev php8.2-ldap php8.2-xml php8.2-bcmath php8.2-mbstring php8.2-xml php8.2-curl php8.2-opcache php8.2-readline php8.2-zip php-pear
﻿
3.1 Installing a PHP MongoDB driver
Install PHP MongoDB driver:
Shell
pecl install mongodb-1.21.0
pecl install mongodb-1.21.0
﻿
Create configuration files for PHP MongoDB startup and activation:
Shell
echo "extension=mongodb.so" | tee /etc/php/8.2/apache2/conf.d/20-mongodb.ini
echo "extension=mongodb.so" | tee /etc/php/8.2/cli/conf.d/20-mongodb.ini
echo "extension=mongodb.so" | tee /etc/php/8.2/apache2/conf.d/20-mongodb.ini
echo "extension=mongodb.so" | tee /etc/php/8.2/cli/conf.d/20-mongodb.ini
﻿
3.2 Installing the PHP Phalcon extension
Install the PHP Phalcon extension:
Shell
mkdir /tmp/install && cd /tmp/install && curl -LOf https://github.com/phalcon/cphalcon/releases/download/v5.3.1/phalcon-php8.2-nts-ubuntu-gcc-x64.zip && unzip phalcon-php8.2-nts-ubuntu-gcc-x64.zip && cp phalcon.so /usr/lib/php/20220829 && cd / && rm -rf /tmp/install
mkdir /tmp/install && cd /tmp/install && curl -LOf https://github.com/phalcon/cphalcon/releases/download/v5.3.1/phalcon-php8.2-nts-ubuntu-gcc-x64.zip && unzip phalcon-php8.2-nts-ubuntu-gcc-x64.zip && cp phalcon.so /usr/lib/php/20220829 && cd / && rm -rf /tmp/install
﻿
Create configuration files for PHP Phalcon startup and activation:
Shell
echo "extension=phalcon.so" | tee /etc/php/8.2/apache2/conf.d/30-phalcon.ini
echo "extension=phalcon.so" | tee /etc/php/8.2/cli/conf.d/30-phalcon.ini
echo "extension=phalcon.so" | tee /etc/php/8.2/apache2/conf.d/30-phalcon.ini
echo "extension=phalcon.so" | tee /etc/php/8.2/cli/conf.d/30-phalcon.ini
﻿
4. Installing MongoDB database
Download and convert the MongoDB GPG key into a file:
Bash
curl -fsSL https://www.mongodb.org/static/pgp/server-6.0.asc | \
   sudo gpg -o /usr/share/keyrings/mongodb-server-6.0.gpg \
   --dearmor
curl -fsSL https://www.mongodb.org/static/pgp/server-6.0.asc | \
   sudo gpg -o /usr/share/keyrings/mongodb-server-6.0.gpg \
   --dearmor
﻿
Add the /etc/apt/sources.list.d/mongodb-org-6.0.list repository line into the file:
Ubuntu 22.04
Ubuntu 20.04
echo "deb [ arch=amd64,arm64 signed-by=/usr/share/keyrings/mongodb-server-6.0.gpg ] https://repo.mongodb.org/apt/ubuntu jammy/mongodb-org/6.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-6.0.list
echo "deb [ arch=amd64,arm64 signed-by=/usr/share/keyrings/mongodb-server-6.0.gpg ] https://repo.mongodb.org/apt/ubuntu jammy/mongodb-org/6.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-6.0.list
﻿
Update the list of available packages:
Shell
apt-get update
apt-get update
﻿
Install MongoDB using the apt package manager:
Shell
apt-get install -y mongodb-org
apt-get install -y mongodb-org
﻿
Run mongod.service:
shell
systemctl start mongod.service
systemctl start mongod.service
﻿
And enable autostart:
shell
systemctl enable mongod.service
systemctl enable mongod.service
﻿
5. Managing and downloading the latest Passwork via Git
Go to /var/www/:
bash
cd /var/www/
cd /var/www/
﻿
Add a global Git configuration pointing to the safe directory:
bash
git config --global --add safe.directory /var/www
git config --global --add safe.directory /var/www
﻿
Initialize a Git repository at /var/www/:
bash
git init
git init
﻿
Add the remote Passwork repository:
bash
git remote add origin https://passwork.download/passwork/passwork.git
git remote add origin https://passwork.download/passwork/passwork.git
﻿
Get the remote repository for your local sever:
bash
git fetch
git fetch
﻿
The system will ask for your credentials, which are listed on your customer portal page. If you can't access the customer portal, let us know.
Switch to the v6 branch with the latest Passwork version:
bash
git checkout v6
git checkout v6
﻿
Give www-data owner privileges for the files and directories:
bash
find /var/www/ -type d -exec chmod 755 {} \;
find /var/www/ -type f -exec chmod 644 {} \;
chown -R www-data:www-data /var/www/
find /var/www/ -type d -exec chmod 755 {} \;
find /var/www/ -type f -exec chmod 644 {} \;
chown -R www-data:www-data /var/www/
﻿
6. Setting up Apache2 for HTTP access to Passwork
Open the virtual host configuration file for HTTP:
bash
nano /etc/apache2/sites-enabled/000-default.conf
nano /etc/apache2/sites-enabled/000-default.conf
﻿
Edit the file so it looks as follows:
bash
<VirtualHost *:80>
    ServerAdmin webmaster@localhost
    DocumentRoot /var/www/public
    <Directory /var/www/public>
        Options FollowSymLinks MultiViews
        AllowOverride All
        Order allow,deny
        allow from all
    </Directory>
    ErrorLog ${APACHE_LOG_DIR}/error.log
    CustomLog ${APACHE_LOG_DIR}/access.log combined
</VirtualHost>
<VirtualHost *:80>
    ServerAdmin webmaster@localhost
    DocumentRoot /var/www/public
    <Directory /var/www/public>
        Options FollowSymLinks MultiViews
        AllowOverride All
        Order allow,deny
        allow from all
    </Directory>
    ErrorLog ${APACHE_LOG_DIR}/error.log
    CustomLog ${APACHE_LOG_DIR}/access.log combined
</VirtualHost>
﻿
Enable the URL rewrite module and restart Apache2:
bash
a2enmod rewrite
service apache2 restart
a2enmod rewrite
service apache2 restart
﻿
You can open http://passwork.local or http://127.0.0.1 to test your Passwork connection
7. Passwork parameter checklist
When you connect to Passwork for the first time, you will need to go over the checklist that includes:
Automatic parameter checking
Checking connection to MongoDB database
Generating an encryption key for MongoDB
License verification
Leave all fields as they are if you are installing a new Passwork copy
After finishing the checklist, you will be offered to create the first Passwork user and set their login, password and email address for notifications.
This user is always local and the owner of Passwork by default, in case of assigning LDAP/SSO user an owner, it will automatically become local and you will not be able to authorise in Passwork
8. Setting up HTTPS connection
8.1 Generating a self-signed SSL certificate
Create a new directory to store the private key and the certificate in:
bash
mkdir /etc/apache2/ssl/
mkdir /etc/apache2/ssl/
﻿
 Use OpenSSL to generate a self-signed X.509 certificate for Apache2:
bash
openssl req -x509 -nodes -days 365 -newkey rsa:2048 -subj '/CN=your.domain.name' -addext 'subjectAltName=DNS: your.domain.name' -keyout /etc/apache2/ssl/apache.key -out /etc/apache2/ssl/apache.crt
openssl req -x509 -nodes -days 365 -newkey rsa:2048 -subj '/CN=your.domain.name' -addext 'subjectAltName=DNS: your.domain.name' -keyout /etc/apache2/ssl/apache.key -out /etc/apache2/ssl/apache.crt
﻿
Common Name (CN) — Specify the IP of your server or host. This field is important, as the certificate should match the domain or IP of your website
subjectAltName (SAN) — Alternative domain name or IP
Give root access to the user to secure the private key and the certificate:
bash
chmod 600 /etc/apache2/ssl/*
chmod 600 /etc/apache2/ssl/*
﻿
8.2 Configuring a virtual host to access Passwork via HTTPS
Activate the SSL module in Apache for the server to support HTTPS:
bash
a2enmod ssl
a2enmod ssl
﻿
Enable the website's virtual host configuration file with the SSL settings:
bash
a2ensite default-ssl
a2ensite default-ssl
﻿
Open the virtual host configuration file for HTTPS connection:
bash
nano /etc/apache2/sites-enabled/default-ssl.conf
nano /etc/apache2/sites-enabled/default-ssl.conf
﻿
Find the section that starts with <VirtualHost _default_:443> and edit it as follows:
Add the ServerName directive (server name or IP) and :443 port under the ServerAdmin line:
bash
ServerAdmin webmaster@localhost
ServerName passwork.local:443
ServerAdmin webmaster@localhost
ServerName passwork.local:443
﻿
Add the <Directory> directive after ServerName:
bash
<Directory /var/www/public>
        Options FollowSymLinks MultiViews
        AllowOverride All
        Order allow,deny
        allow from all
    </Directory>
<Directory /var/www/public>
        Options FollowSymLinks MultiViews
        AllowOverride All
        Order allow,deny
        allow from all
    </Directory>
﻿
Locate the following changes and update the paths of files which were generated previously, or specify the private key and certificate location:
bash
SSLCertificateFile /etc/apache2/ssl/apache.crt
SSLCertificateKeyFile /etc/apache2/ssl/apache.key
SSLCertificateFile /etc/apache2/ssl/apache.crt
SSLCertificateKeyFile /etc/apache2/ssl/apache.key
﻿
After editing the file, check if the virtual host configuration file matches the example:
bash
<IfModule mod_ssl.c>
    <VirtualHost _default_:443>
        ServerAdmin webmaster@localhost
        ServerName passwork.local:443
        DocumentRoot /var/www/public
        <Directory /var/www/public>
            Options FollowSymLinks MultiViews
            AllowOverride All
            Order allow,deny
            allow from all
        </Directory>
        SSLEngine on
        SSLCertificateFile /etc/apache2/ssl/apache.crt
        SSLCertificateKeyFile /etc/apache2/ssl/apache.key
    </VirtualHost>
</IfModule>
<IfModule mod_ssl.c>
    <VirtualHost _default_:443>
        ServerAdmin webmaster@localhost
        ServerName passwork.local:443
        DocumentRoot /var/www/public
        <Directory /var/www/public>
            Options FollowSymLinks MultiViews
            AllowOverride All
            Order allow,deny
            allow from all
        </Directory>
        SSLEngine on
        SSLCertificateFile /etc/apache2/ssl/apache.crt
        SSLCertificateKeyFile /etc/apache2/ssl/apache.key
    </VirtualHost>
</IfModule>
﻿
Restart Apache2 to apply the changes:
bash
systemctl restart apache2
systemctl restart apache2
﻿
Check the HTTPS connection to Passwork using https://passwork.local﻿
8.3 Setting up Passwork for work over HTTPS
When using a secure SSL connection (HTTPS), client browsers require certain flags to process Passwork data. These flags are called session.cookie_secure and disableSameSiteCookie.

If these flags are not set, browsers will not be able to establish connections and the connection will be rejected, which can lead to authorisation errors — "The session of this browser tab is out of date".
Enable the ;session.cookie_secure parameter in /etc/php/8.2/apache2/php.ini:
bash
sed -i '/session.cookie_secure =/c session.cookie_secure = On' /etc/php/8.2/apache2/php.ini
sed -i '/session.cookie_secure =/c session.cookie_secure = On' /etc/php/8.2/apache2/php.ini
﻿
Set the disableSameSiteCookie parameter in /var/www/app/config/config.ini to Off:
bash
sed -i '/disableSameSiteCookie =/c disableSameSiteCookie = Off' /var/www/app/config/config.ini
sed -i '/disableSameSiteCookie =/c disableSameSiteCookie = Off' /var/www/app/config/config.ini
﻿
Do not set these parameters or reset them to their original value if you change your mind about using SSL and work over the HTTP protocol
9. Configure background tasks
Background tasks are tasks that are executed by the scheduler in the background. For example, LDAP synchronisation, loading favicons, and other tasks that are time-consuming, persistent, or resource-allocating.
See a guide on setting up background tasks﻿.
10. Set up security
Before modifying security settings, we strongly recommend to make sure that Passwork is stable and works correctly, and to back up the files you are making changes to
Server security is an important part of ensuring the protection of valuable company data and resources. It is a process that requires planning and execution to ensure maximum protection against possible threats.
See our overview of Passwork security settings﻿.
Offline installation
Debian