Debian

info

Instructions for installing Passwork on OS:

• Debian 11
• Debian 12

danger

The instructions use switchable code blocks to separate commands according to the operating system versions

1. Minimum system requirements

Passwork is not demanding on system resources, and the required number of servers depends on the number of active users, the volume of stored data, and system fault tolerance requirements.

Familiarize yourself with the full system requirements.

info

If the server has 2-4 GB of RAM, we recommend enabling a SWAP file.

2. Basic actions before installation

Obtain root privileges and update the local package database:

shell

sudo -i 
apt-get update

Install the Apache2 web server and the curl data transfer utility:

shell

apt-get install -y apache2 unzip curl zip jq

3. PHP installation

Install packages for working with HTTPS repositories:

shell

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

Obtain and save the GPG key of the PHP repository:

shell

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:

shell

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

Update the local package and repository list:

shell

apt update

Install PHP and extension modules:

shell

apt install -y php8.3 php8.3-cli php8.3-bcmath php8.3-fpm php8.3-curl php8.3-gd php8.3-intl php8.3-ldap php8.3-mbstring php8.3-mysql php8.3-opcache php8.3-pgsql php8.3-soap php8.3-zip php8.3-sqlite3 php8.3-xml php8.3-dev php-pear

Make sure the php8.3-fpm service is running:

shell

systemctl status php8.3-fpm

Start and enable the service to auto-start if it is stopped:

shell

systemctl start php8.3-fpm
systemctl enable php8.3-fpm

3.1 Installing PHP MongoDB driver

Install the PHP MongoDB driver:

shell

pecl install mongodb

Create configuration files to load and enable PHP MongoDB:

shell

echo "extension=mongodb.so" | tee /etc/php/8.3/fpm/conf.d/20-mongodb.ini
echo "extension=mongodb.so" | tee /etc/php/8.3/cli/conf.d/20-mongodb.ini

4. MongoDB database installation

Download and add the MongoDB GPG key:

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

Debian 11

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 to the file:

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

Debian 11

echo "deb [ signed-by=/usr/share/keyrings/mongodb-server-7.0.gpg] http://repo.mongodb.org/apt/debian bullseye/mongodb-org/7.0 main" | sudo tee /etc/apt/sources.list.d/mongodb-org-7.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

Start the mongod.service service:

shell

systemctl start mongod.service

Enable the service to auto-start:

shell

systemctl enable mongod.service

5. Obtaining and configuring Passwork

Online

Obtain the script:

wget

wget https://repos.passwork.pro/repository/linux/scripts/passwork.sh

curl

curl -O https://repos.passwork.pro/repository/linux/scripts/passwork.sh

danger

The Passwork installation script should not be located in the directory with the application server files.

Assign execution rights to the script:

chmod +x passwork.sh

By default, the passwork.sh script will perform:

• Creating a hidden .script_env file in the current directory;
• Creating a passwork_archive directory for Passwork backups;
• Obtaining the latest available Passwork version, signature, and public key;
• Installing the previously obtained archive into /var/www/

info

To use a non-standard installation path, disable certificate verification, or change behavior, you can use script launch parameters.

Run the script:

sudo ./passwork.sh

On the first run, the script will request an API key and perform basic environment checks:

Example of successful script execution:

Offline

Obtain the script on another machine with Internet access:

wget

wget https://repos.passwork.pro/repository/linux/scripts/passwork.sh

curl

curl -O https://repos.passwork.pro/repository/linux/scripts/passwork.sh

PowerShell

(New-Object System.Net.WebClient).DownloadFile("https://repos.passwork.pro/repository/linux/scripts/passwork.sh", "$PWD\passwork.sh")

info

Or obtain the passwork.sh script manually using the link

danger

The Passwork installation script should not be located in the directory with the application server files.

Assign execution rights to the script:

chmod +x passwork.sh

Before running passwork.sh, you need to:

• Obtain Passwork version 7 from our Customer Portal (Mandatory);
• Place it in the launch directory or use the --input argument to specify the location (Mandatory);
• Obtain the archive signature and public key of Passwork (optional if using the --skip argument).

By default, the passwork.sh script will perform:

• Creating a passwork_archive directory for Passwork backups;
• Extracting the Passwork archive;
• Installing the previously obtained archive into /var/www/

info

To use a non-standard installation path, disable certificate verification, or change behavior, you can use script launch parameters.

After preparation, run the passwork.sh script:

sudo ./passwork.sh -offline

Example of successful offline script execution:

6. Web server configuration for HTTPS protocol

info

To ensure correct operation, it is necessary to use the HTTPS protocol. Using HTTP will lead to errors.

6.1 Generating self-signed SSL certificate

Create a new directory to store the private key and certificate:

shell

mkdir /etc/apache2/ssl/

Generate a self-signed X.509 certificate for Apache2 using OpenSSL:

shell

openssl req -x509 -nodes -days 365 -newkey rsa:2048 -subj '/CN=your.domain.name' -keyout /etc/apache2/ssl/apache.key -out /etc/apache2/ssl/apache.crt

• Common Name (CN) — It is important here to specify the IP address of your server or the hostname, as your certificate must match the domain (or IP address) for the website;

Set root user access rights to protect the private key and certificate:

shell

chmod 600 /etc/apache2/ssl/*

6.2 Virtual host configuration for HTTPS access

danger

Before configuring the web server with enabled SSL termination, it is recommended to familiarize yourself with the configuration features.

Enable the SSL module in Apache2, allowing the server to support the HTTPS protocol:

shell

a2enmod ssl

Enable the virtual host configuration file for the site with SSL connection settings:

shell

a2ensite default-ssl

Open the virtual host configuration file for the HTTPS connection:

shell

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

Make the following changes:

• Add the ServerName line and change www.example.com to the server's IP address or domain (depending on the value specified in the certificate's Common Name);
• Uncomment the DocumentRoot line and change the path to the root directory of Passwork (/var/www/public);

shell

ServerAdmin webmaster@localhost
ServerName passwork:443
DocumentRoot /var/www/public

• Add the <Directory> directive after ServerName:

shell

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

• Update the paths to the certificate files generated earlier:

shell

SSLCertificateFile /etc/apache2/ssl/apache.crt
SSLCertificateKeyFile /etc/apache2/ssl/apache.key

• Change the .php file handler, specifying proxying requests to the php-fpm socket:

shell

<FilesMatch \.php$>
    SetHandler "proxy:unix:/run/php/php8.3-fpm.sock|fcgi://localhost/"
</FilesMatch>

• After making changes, check that the virtual host configuration file matches the example:

shell

<VirtualHost *:443>
    ServerName passwork: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

    ErrorLog ${APACHE_LOG_DIR}/error.log
    CustomLog ${APACHE_LOG_DIR}/access.log combined
        
    <FilesMatch \.php$>
        SetHandler "proxy:unix:/run/php/php8.3-fpm.sock|fcgi://localhost/"
    </FilesMatch>
</VirtualHost>

Enable modules and restart services:

shell

a2enmod rewrite proxy_fcgi setenvif
systemctl restart php8.3-fpm
systemctl restart apache2

7. Passing checklist

When first connecting to Passwork, you need to go through the parameter checklist, during which the following will be performed:

• Checking necessary parameters
• Connecting to the MongoDB database

danger

Change the MongoDB connection to the address — mongodb://localhost:27017

• Randomly generated key for encrypting data in MongoDB
• License key verification

After passing the checklist, you will be prompted to create the first user in Passwork, where you need to specify the login, password, and email address for sending notifications.

info

Additional component parameters, security settings, and Passwork system configuration are available in the advanced settings section.