Skip to main content
This documentation is for Passwork version 6.0, no longer supported.

See documentation for version 7.0.
Version: 6.0

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:

sudo -i 
apt-get update

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

apt-get install -y git apache2 unzip curl

3. Installing PHP

Install packages for HTTPS repositories:

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

Download and save the GPG key of the PHP repository:

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:

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:

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:

systemctl start mongod.service

And enable autostart:

systemctl enable mongod.service

5. Managing and downloading the latest Passwork via Git

Go to /var/www/:

cd /var/www/

Add a global Git configuration pointing to the safe directory:

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

Initialize a Git repository at /var/www/:

git init

Add the remote Passwork repository:

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

Get the remote repository for your local sever:

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:

git checkout v6

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

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:

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

Edit the file so it looks as follows:

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

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:

mkdir /etc/apache2/ssl/

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

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:

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:

a2enmod ssl

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

a2ensite default-ssl

Open the virtual host configuration file for HTTPS connection:

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:
ServerAdmin webmaster@localhost
ServerName passwork.local:443
  • Add the <Directory> directive after ServerName:
<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:
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:
<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:

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:

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:

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.