Skip to main content
Version: 7.0

Ubuntu

info

Passwork installation guide on the OS:

  • Ubuntu 20.04
  • Ubuntu 22.04
  • Ubuntu 24.04
danger

The guide uses 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.

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

sudo -i 
apt-get update

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

apt-get install -y apache2 unzip curl zip jq

3. PHP installation

Install the software-properties-common package and add the ppa:ondrej/php repository:

apt-get install -y software-properties-common
add-apt-repository -y ppa:ondrej/php

Update the local package and repository list:

apt-get update

Install PHP and extension modules:

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

Ensure that the php8.3-fpm service is running:

systemctl status php8.3-fpm

Start and enable the service autostart if it is stopped:

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

3.1 Installing PHP MongoDB driver

Install the PHP MongoDB driver:

pecl install mongodb

Create configuration files to load and enable PHP MongoDB:

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 convert the MongoDB GPG key to a file:

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

Add the repository line to the file:

echo "deb [ arch=amd64,arm64 signed-by=/usr/share/keyrings/mongodb-server-8.0.gpg ] https://repo.mongodb.org/apt/ubuntu noble/mongodb-org/8.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-8.0.list

Update the list of available packages:

apt-get update

Install MongoDB using the apt package manager:

apt-get install -y mongodb-org

Start the mongod.service service:

systemctl start mongod.service

Enable service autostart:

systemctl enable mongod.service

5. Obtaining and configuring Passwork

Online

Obtain the script:

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

  • Creation of a hidden .script_env file in the current directory;
  • Creation of the passwork_archive directory for Passwork backups;
  • Downloading the latest available Passwork version, signature, and public key;
  • Installing the previously obtained archive to /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 script launch

Example of successful script execution:

Successful script execution
Offline

Obtain the script on another machine with Internet access:

wget https://repos.passwork.pro/repository/linux/scripts/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:

  • Creation of the passwork_archive directory for Passwork backups;
  • Unpacking the Passwork archive;
  • Installing the previously obtained archive to /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:

Successful offline script execution

6. Web server configuration for HTTPS protocol

info

To ensure proper 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:

mkdir /etc/apache2/ssl/

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

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 to specify your server's IP address or hostname here, as your certificate must match the domain (or IP address) for the website;

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

chmod 600 /etc/apache2/ssl/*

6.2 Configuring virtual host for HTTPS access

danger

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

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

a2enmod ssl

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

a2ensite default-ssl

Open the virtual host configuration file for HTTPS connection:

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 Passwork root directory (/var/www/public);
ServerAdmin webmaster@localhost
ServerName passwork:443
DocumentRoot /var/www/public
  • Add the <Directory> directive after ServerName:
<Directory /var/www/public>
Options +FollowSymLinks -Indexes -MultiViews
AllowOverride FileInfo
Require all granted
</Directory>
  • Update the paths to the certificate files generated earlier:
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:
<FilesMatch \.php$>
SetHandler "proxy:unix:/run/php/php8.3-fpm.sock|fcgi://localhost/"
</FilesMatch>
  • After making changes, verify that the virtual host configuration file matches the example:
<IfModule mod_ssl.c>
<VirtualHost _default_: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>
</IfModule>

Enable modules and restart services:

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

7. Completing parameter checklist

When first connecting to Passwork, you need to complete 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 completing the checklist, you will be prompted to create the first user in Passwork, where you need to specify a login, password, and email address for sending notifications.

info

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