Standard installation on Linux
Passwork is not demanding on server resources. The volumes of required resources (RAM, CPU, HDD) and the number of servers depend on the number of active users, the volume of stored data, as well as the requirements for system fault tolerance.
System requirements — Minimum system requirements
If the server has 2-4 GB RAM, it is recommended to enable a SWAP file to build all libraries correctly.
The standard installation on Linux uses Docker. Docker images are structured in such a way that all important data is stored in directories that are shared with the host machine, so you can stop, delete, and create new containers.
Configuration files are also stored in mounted directories, so you can make most configuration changes to components without modifying Docker images or containers directly. To do this, make changes to the configuration file of the necessary component and restart the container.
The assembly consists of 6 containers. Some containers are launched mandatory, while the other part can be enabled or disabled by changing the environment variable COMPOSE_PROFILES in the environment variables file .env:
Nginx — an image based on the official Nginx image. It is launched by default.
PHP — an image with PHP and PHP-FPM based on Ubuntu. It is launched by default.
Cron — a separate container based on the PHP image for running scheduled tasks. It is launched by default.
PSMDB — an image based on the official Percona Server for MongoDB image. Startup can be disabled if an external MongoDB/PSMDB is being used.
Postfix — an image with Postfix based on Ubuntu. It can be disabled if notifications are sent through PHP Mailer.
Certbot — the official Certbot image from Let's Encrypt. It is necessary if you are using a certificate from Let's Encrypt. It can be disabled if you are using other SSL certificates.
DEB-based
RPM-based
Download and install Docker. The minimum required version is 18.06.0. Official installation article — https://docs.docker.com/engine/installation/
Install and enable the Docker Compose plugin if it has not been installed previously. The official installation article — https://docs.docker.com/compose/install/linux/
We recommend using Docker installed not through snap
To install Passwork, you need to download and run the script that will install all the necessary components.
Create a directory and navigate to it:
Copy the installation script:
Check the hash of the file passwork_compose_install.sh to verify the authenticity of the file:
The system should display the message passwork_compose_install.sh: OK.
If you are installing not as root, make sure that the user is a member of the docker group.
You can check using the following method:
You can add a user to the docker group like this:
Give the script execution rights and run it:
The script uses apt or dnf, as well as curl. If a proxy server is used in your network, you need to add environment variables: export http_proxy=http://proxy.example.com:8080 export https_proxy=http://proxy.example.com:8080
Actions performed by the script
- Checking installed Docker
- Checking Docker version (above 18.06.0)
- Checking running Docker
- Checking user for membership in the docker group or having sudo rights
- Checking if Docker compose plugin is installed and enabled
- Checking the system for belonging to deb or rpm distribution
- Installing additional utilities for proper operation of scripts curl, unzip, and jq
- Requesting input of Passwork client certificate
- Checking the certificate for compliance with the format
- Checking the validity of the certificate
- Downloading and unpacking the archive with docker-compose build files
- Checking the environment variables file and adding the certificate number
- Executing the Passwork code update script
- Executing docker compose up -d
Process of executing the installation script
The script will check the rights of the current user, as well as the versions of the necessary components. In case of errors, the script will create a log in the format install_log_date.log and will place the errors in it.
During the execution, the certificate number will be requested from the customer portal:
After the script execution is completed
The script will automatically execute docker ps. Please check the list of running containers. If the containers were not started, please check the installation output and log. Example of correct output:
After building and running the containers, Passwork will be available at the following link: https://your_servername
By default, Passwork uses a self-signed certificate that is automatically generated during installation, so when you first open the page, you will see a message that the browser does not trust the site's certificate.
At the first step, the system will offer to choose the interface language.
The checklist of parameters will show if all components are installed on your server.
By default, Passwork in Docker connects to a service named db, so it is necessary to change the connection string on the third stage of the initial installation.
The connection string is mongodb://db:27017
Passwork will generate a new key for server encryption. If you are connecting Passwork to an existing database, specify the existing encryption key.
Do not enter a key that was generated outside of Passwork. Passwork uses special secure algorithms to generate new keys in appropriate formats. Using keys generated by third-party tools may result in incorrect operation.
You can download the license keys in your Passwork client portal or request them from managers.
- For certificates issued by a trusted issuer
- For certificates issued by the domain certification authorities of your organization
Rename and place your SSL certificate or certification chain in ./conf/ssl
privkey.pem — private key.
fullchain.pem — certificate\certification chain
You can configure Let's Encrypt if you don't have a certificate authority (certificate issued by a trusted center), but you have a public DNS name for the server.
Edit the file - .env change and add the following parameters:
Save the changes made and start the container.
Check the container logs for certificate acquisition.
Example of issuing a certificate
Recreate containers to update data using new certificates.
Passwork will be available via the HTTPS protocol using a certificate from Let's Encrypt.
update.sh — performs updates of the application code to the latest version available in your license.
db-backup.sh — performs backup to the backup folder.
db-restore.sh — performs backup restoration. If no backup name is provided, a list of available backups will be displayed.
collect-log.sh — performs the collection of component logs. It is required for debugging purposes and for sending logs to technical support service.
collect-conf.sh — collects configuration files of components. It is required for debugging purposes and for sending configuration files to technical support service.
docker compose stop — stop the service
docker compose restart — restart the service
docker compose start — start a stopped service
docker compose down — remove the service. Data, including the database and configuration files, will be preserved.
Most of the settings can be done through environment variables in .env or by modifying the configuration file of a separate component.
Parameter | Description | Default value |
CERT | Passwork certificate number. Used in the upgrade script to retrieve application files from the client portal | XXX-XXX-XXX-XXX-XXXXXXXXXXXX |
USE_LETSENCRYPT | Использовать certbot для выпуска SSL сертификатов или нет | false |
LETSENCRYPT_STAGING | Test mode for certbot. Useful for debugging, since Let's Encrypt has a limit on the number of requests. Defaults to true to avoid errors due to a misconfigured DNS record or others. It is recommended to use staging first. | true |
LETSENCRYPT_REG_EMAIL | Email for Let’s encrypt | |
DOMAIN | Domain for Let’s encrypt | |
ALIAS_CONTAINERS_NAME | Containers name prefix | "passwork_" |
COMPOSE_PROFILES | Compose profiles that allow you to enable/disable the startup of services | "local_notify,mongo" |
PHP_CONF_DIR | PHP config directory | ./conf/php |
PHP_LOG_DIR | PHP logs directory | ./log/php |
APP_DIR | Passwork application directory | ./www/latest (symlink to the latest version) |
APP_LOG_DIR | Application logs directory | ./log/app |
KEYS_DIR | The directory with the license keys as well as the main application configuration file | ./conf/keys |
NGINX_CONF_DIR | Nginx config directory | ./conf/nginx |
NGINX_LOG_DIR | Nginx logs directory | ./log/nginx |
SSL_DIR | Directory with SSL certificates | ./conf/ssl |
MONGO_DATA_DIR | Directory with mongo data | ./data/mongo |
CUSTOM_CA_DIR | Directory for additional root certificates (e.g. for LDAPS) | ./conf/custom_ca |
POSTFIX_LOG_DIR | Postfix logs directory | ./log/postfix |
POSTFIX_CONF_DIR | Postfix config directory | ./conf/postfix |
After making changes to the .env or configuration file of a specific component, it is necessary to restart the corresponding container.
To implement changes in config.ini, please execute.
