Debian

info

Installing Passwork on following OS:

• Debian 11
• Debian 12

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:

bash

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

3. Installing PHP

Install packages for HTTPS repositories:

bash

apt-get install -y apt-transport-https lsb-release ca-certificates

Download and save the GPG key of the PHP repository:

bash

wget -O /etc/apt/trusted.gpg.d/php.gpg https://packages.sury.org/php/apt.gpg

Add the PHP repository to the apt sources list:

echo "deb https://packages.sury.org/php/ $(lsb_release -sc) main" > /etc/apt/sources.list.d/php.list

Update the local packages and repositories:

apt-get update

Install PHP and its extensions:

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 a PHP MongoDB driver:

pecl install mongodb-1.21.0

Create configuration files for PHP MongoDB startup and activation:

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:

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:

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 add the MongoDB GPG key:

Debian 11

wget -qO - https://www.mongodb.org/static/pgp/server-6.0.asc | sudo apt-key add -

Debian 12

curl -fsSL https://www.mongodb.org/static/pgp/server-7.0.asc | gpg -o /usr/share/keyrings/mongodb-server-7.0.gpg --dearmor

Add the MongoDB repository into the file:

Debian 11

echo "deb http://repo.mongodb.org/apt/debian buster/mongodb-org/6.0 main" | sudo tee /etc/apt/sources.list.d/mongodb-org-6.0.list

Debian 12

echo "deb [ signed-by=/usr/share/keyrings/mongodb-server-7.0.gpg ] http://repo.mongodb.org/apt/debian bookworm/mongodb-org/7.0 main" | tee /etc/apt/sources.list.d/mongodb-org-7.0.list

Update the list of available packages:

apt-get update

Install MongoDB using the apt package manager:

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/:

bash

cd /var/www/

Add a global Git configuration pointing to the safe directory:

bash

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

Initialize a Git repository at /var/www/:

bash

git init

Add the remote Passwork repository:

bash

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

Get the remote repository for your local sever:

bash

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:

bash

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/

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

Edit the file so it looks as follows:

bash

<VirtualHost *:80>
    ServerAdmin webmaster@localhost
    DocumentRoot /var/www/public
    <Directory /var/www/public>
        Options +FollowSymLinks -Indexes -MultiViews
        AllowOverride FileInfo
        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:

bash

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:

bash

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

• 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/*

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

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

bash

a2ensite default-ssl

Open the virtual host configuration file for HTTPS connection:

bash

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

• Add the <Directory> directive after ServerName:

bash

<Directory /var/www/public>
    Options +FollowSymLinks -Indexes -MultiViews
    AllowOverride FileInfo
    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:

bash

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 -Indexes -MultiViews
            AllowOverride FileInfo
            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:

bash

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:

bash

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

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 various threats.

Look through the overview of Security settings.