Ubuntu

info

Installing Passwork on following OS:

• Ubuntu 20.04
• Ubuntu 22.04

warning

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 Technical requirements.

info

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:

shell

sudo -i 
apt-get update

Then, install the Git version control package, Apache2 web-server and curl data transfer tool:

shell

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

Then update the local packages and repositories:

shell

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

3.1 Installing a PHP MongoDB driver

Install PHP MongoDB driver:

shell

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

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

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

4. Installing MongoDB database

Download and convert the MongoDB GPG key into a file:

shell

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

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

Ubuntu 20.04

echo "deb [ arch=amd64,arm64 signed-by=/usr/share/keyrings/mongodb-server-6.0.gpg ] https://repo.mongodb.org/apt/ubuntu focal/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

Install MongoDB using the apt package manager:

shell

apt-get install -y mongodb-org

Run mongod.service:

shell

systemctl start mongod.service

And enable autostart:

shell

systemctl enable mongod.service

5. Managing and downloading the latest Passwork via Git

Go to /var/www/:

shell

cd /var/www/

Add a global Git configuration pointing to the safe directory:

shell

git config --global --add safe.directory /var/www

Initialize a Git repository at /var/www/:

shell

git init

Add the remote Passwork repository:

shell

git remote add origin https://passwork.download/passwork/passwork.git

Get the remote repository for your local sever:

shell

git fetch

warning

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:

shell

git checkout v6

Give www-data owner privileges for the files and directories:

shell

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:

shell

nano /etc/apache2/sites-enabled/000-default.conf

Edit the file so it looks as follows:

shell

<VirtualHost *:80>
    ServerAdmin webmaster@localhost
    DocumentRoot /var/www/public
    <Directory /var/www/public>
        Options +FollowSymLinks -Indexes -MultiViews
        AllowOverride All
        Require all granted
    </Directory>
    ErrorLog ${APACHE_LOG_DIR}/error.log
    CustomLog ${APACHE_LOG_DIR}/access.log combined
</VirtualHost>

Enable the URL rewrite module and restart Apache2:

shell

a2enmod rewrite
service apache2 restart

info

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

info

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.

danger

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:

shell

mkdir /etc/apache2/ssl/

Use OpenSSL to generate a self-signed X.509 certificate for Apache2:

shell

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:

shell

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:

shell

a2enmod ssl

Enable the website's virtual host configuration file with the SSL settings:

shell

a2ensite default-ssl

Open the virtual host configuration file for HTTPS connection:

shell

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:

shell

ServerAdmin webmaster@localhost
ServerName passwork.local:443

• Add the <Directory> directive after ServerName:

shell

<Directory /var/www/public>
    Options +FollowSymLinks -Indexes -MultiViews
    AllowOverride All
    Require all granted
</Directory>

• Locate the following changes and update the paths of files which were generated previously, or specify the private key and certificate location:

shell

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:

shell

<IfModule mod_ssl.c>
    <VirtualHost _default_:443>
        ServerAdmin webmaster@localhost
        ServerName passwork.local:443
        DocumentRoot /var/www/public
        <Directory /var/www/public>
            Options +FollowSymLinks -Indexes -MultiViews
            AllowOverride All
            Require all granted
        </Directory>
        SSLEngine on
        SSLCertificateFile /etc/apache2/ssl/apache.crt
        SSLCertificateKeyFile /etc/apache2/ssl/apache.key
    </VirtualHost>
</IfModule>

Restart Apache2 to apply the changes:

shell

systemctl restart apache2

info

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:

shell

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:

shell

sed -i '/disableSameSiteCookie =/c disableSameSiteCookie = Off' /var/www/app/config/config.ini

info

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 Background tasks.

10. Set up security

warning

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 Security settings.

LLM version