On Premises configuration: Requirements and installation

This documentation presents the steps for installing the LockSelf On-Premises solution.

____________________________________________________________________________________

To install your On Premises instance, you have two options:

• Install the application manually, following the steps outlined below
• Use our installation script, which lets you install the application in just a few minutes (and follows the same steps in this documentation).
  • Don't hesitate to ask your Account Manager for the script

If you opt for the script, you'll need to decide whether you want to set up your own MariaDB instance and create your database (see point 5 in the documentation). So you can:

• Or let the installation script generate the database on the machine.
• Or set up your MariaDB instance and create your database, and then, in the installation script, define your database information manually.

In all cases (manual installation or script), it will be important to:

1. Know the Linux environment.
2. Know how to handle a Docker environment and be comfortable with docker-compose.
3. Be familiar with "docker ps", "docker exec", "docker logs", "docker images", "docker load" and all basic docker commands.
4. Have already deployed and maintained MySQL/MariaDB environments.
5. Have an HTTPS stream between a user workstation and the LockSelf license verification server (required to activate the license key, see step 7)

1. Preamble

The LockSelf application uses two components:

• A PHP REST API
• A MariaDB database

The database and LockSelf API are deployed via Docker using the official MariaDB images (https://hub.docker.com/_/mariadb) and php:fpm-alpine (https://hub.docker.com/_/php) respectively.

The MariaDB image is deployed via Docker using the official MariaDB image (https://hub.docker.com/_/mariadb).

The MariaDB image is used without any particular modification.

The PHP image (Alpine base) is optimized:

• Nginx compilation and configuration
• Configuring PHP-FPM
• Supervord installation and configuration

All processes inside the application container run with user 'nobody'. As far as the MariaDB container is concerned, the user used is 'mysql'.

We advise against putting both parts (database and applicative) on the same server, and recommend the use of one of the following OS:

• Ubuntu (LTS)
• Debian (LTS)
• CentOS (LTS)
• RockyLinux (LTS)

We recommend the following configurations:

Both servers (database and application) must have the docker package installed. We won't explain how docker works in this procedure, you need to be initiated to this tool in order to correctly do the installation.

2. Prerequisites

Before you start installing the service, make sure you have the following:

• The domain name you wish to use. (ex: lockself.company.com)
• The SSL certificate, intermediate certificates and private key associated with this domain name. These certificates will be used by the application's web server to secure exchanges between the user and the application. As part of an SSO interconnection between an AD and LockSelf, these certificates will be used to generate the application's metadata, which will then be supplied to the AD. If your certificates contain Bag Attributes and Key Attributes, please delete them.
• The authentication and connection information for your SMTP (which will be used to send system emails relating to the use of the application)

If you want to set up an interconnection on a corporate directory, we use the SAMLv2 protocol. You therefore need to make sure you have an ADFS-type module for Active Directory, OpenID for OpenLDAP or the SAMLv2 modules included in Azure or Office 365.

3. Description of simplified infrastructure

4. Network flow matrix

The flows to be set up for the various servers are:

5. Installing the first component: The MariaDB database

5.1. Action to be taken on the database server - Step 1

There are three options for deploying the database container. It's up to you to choose which one you wish to use according to the company's recommendations.

5.1.1. Manual launch

docker run
--name mariadb \
-v /var/lib/mysql:/var/lib/mysql \
-e MYSQL_ROOT_PASSWORD=my-secret-pwd \
-e MYSQL_DATABASE=lockself \
-p 3306:3306 \
-d mariadb:10.6.X

• --name : corresponds to the name of the container once created
• -v: corresponds to the mounted volume enabling data persistence
• -e: MYSQL_ROOT_PASSWORD - replace "my-secret-pwd" with the password that will be associated with the root user when the container is first launched
• -e : MYSQL_DATABASE - "lockself" corresponds to the name of the database created when the container is first launched
• -p: enables the host server to forward requests on port 3306 to the container
• -d: allows the container to launch in background
• mariadb:10.6.X: corresponds to the version of the MariaDB image used

The option -e environment variables are taken into account only when the container is first started. If datas are present in /var/lib/mysql, these values will not be taken into account and will have no effect.

5.1.2. Launching via docker-composer

version: '3.8'
services:
 mariadb:
 image: mariadb:10.6.X
 restart: always
 volumes:
 - "/var/lib/mysql:/var/lib/mysql"
 ports :
 - "3306:3306"
 environment:
 MYSQL_ROOT_PASSWORD: my-secret-pwd
 MYSQL_DATABASE: lockself

docker-compose up -d --build

version: '3.7'

services:
 mariadb:
 image: mariadb:10.6.X
 ports:
 - target: 3306
 published: 3306
 protocol: tcp
 mode: host
 environment:
 MYSQL_ROOT_PASSWORD: my-secret-pwd
 MYSQL_DATABASE: lockself
 volumes:
 - "/var/lib/mysql:/var/lib/mysql"

Swarm can be used in a number of ways that we won't detail in this procedure. You can find full details of how it works on its official website: https://docs.docker.com/engine/swarm/

5.2. step 5.1 explanations

5.2.1. Mandatory point for correct application operation

In order to achieve data persistence, a volume mount is required in order to share the container's /var/lib/mysql folder (which contains the db's datas) with the host.

This mount point is done via the -v or volumes option depending on the launch mode chosen.

At step 5.1, we use the following mount point: /var/lib/mysql:/var/lib/mysql

Optional: In case SELinux is enabled on host servers, a modification of rights must be performed on the various files:

chcon -Rt svirt_sandbox_file_t /var/lib/mysql

In this example, MariaDB data that is stored in the container in the /var/lib/mysql folder will also be stored on the host in the /var/lib/mysql folder.

5.2.2. Find out more about volumes

https://docs.docker.com/storage/volumes/

5.3. Action to be performed on the database server - Step 2

This step is to be performed on the database server once the MariaDB container has been started, in order to prepare the add user script.

To do this, retrieve the script below and modify the following values:

• PASSWORD - To be replaced by the passwords you wish to associate with users.
• IP - To be replaced by the IP/Range of the application servers. Be careful to be sure of the output IP that will be used. Depending on the architecture, application servers may exit from the container IP (generally 172.X) or from the host server IP.

-- Create user www. It used by the application to read the db.
-- IP has to be modified with the IP/Range of the application servers.
-- PASSWORD has to be modified with the password you want to give to this user.
CREATE USER 'www'@'IP' IDENTIFIED BY 'PASSWORD';
-- Grant rights to the www user.
-- Replace IP with the IP/Range of the application servers.
GRANT SELECT,INSERT,UPDATE,DELETE ON lockself.* TO 'www'@'IP';

-- Create user lockself_migration. It used by the application to migrate the db.
-- IP has to be modified with the IP/Range of the application servers.
-- PASSWORD has to be modified with the password you want to give to this user.
CREATE USER 'lockself_migration'@'IP' IDENTIFIED BY 'PASSWORD';

-- Grant rights to the lockself_migration user.
-- Replace IP with the IP/Range of the application servers.
GRANT SELECT,INSERT,UPDATE,DELETE,ALTER,CREATE,DROP,INDEX ON lockself.* TO 'lockself_migration'@'IP';

Once you have modified the above script and adapted it to your needs, run the command below to create the users in the database:

docker exec -i mariadb sh -c 'exec mysql -uroot -pmy-secret-pwd' < create_user.sql

• mariadb is to be modified with the chosen container name (name chosen in step 5.1)
• my-secret-pwd is to be modified with the root password
• create_user.sql is to be modified with respect to the name of the file containing the above SQL script

6. Installing the second component: The LockSelf application

6.1. Preamble

First, we need to retrieve the package provided by the LockSelf teams and check its integrity. This package includes:

• The container image: lockself-api-X.X.X.tar.gz
• The container image signature: lockself-api-X.X.X.tar.gz.sig

6.2. Action to be taken on the application server - Step 1

The first step is to create an RSA key pair. These will be used by the LockSelf application. These keys are to be stored on the server, we'll use them in step 6.5.

openssl genpkey -out private.pem -aes256 -algorithm rsa -pkeyopt rsa_keygen_bits:4096

For the passphrase requested during execution of this command, we recommend a random passphrase of 32 alphanumeric characters with special characters. This passphrase will be requested in step 6.3.

openssl pkey -in private.pem -out public.pem -pubout

The first command creates the RSA private key (4096 bits) and encrypts it in AES256 with the specified passphrase.

The second extracts the associated public key.

6.3. Action to be taken on the application server - Step 2

Recover the script install_lockself.sh in the document appendix (13.1) on the server and run it. You will be prompted for several pieces of information. At the end of script execution, you'll get back a file named env which we'll use in step 6.5.

The generated environment file env contains, in particular, encryption salts and variables relating to your on-premises infrastructure.

6.4. Before container deployment

Before deploying the container, check that you have the following information available on the web server:

• The env file (for example in: /home/user/lockself/env) generated by the install_lockself.sh script (Step 6.3)

• In a folder (for example: /home/user/lockself/ssl/), SSL certificates (as a reminder: In case your certificates contain Bag Attributes and Key Attributes, please remove):

  • The certificate followed by the certification chain under the name: ssl-certificate.crt
  • The unencrypted private key under the name: ssl-certificate.key
  • Only as part of an SSO connection:
    • The certificate WITHOUT the certification chain under the name: sp.crt

• In a folder (for example: /home/user/lockself/jwt/) the RSA key pair generated in step 6.2:

  • The private key under the name: private.pem
  • The public key under the name: public.pem

• A folder that will be used to store files and make them permanent if the container is restarted (for example: /home/user/lockself/files).

• Optional: In case SELinux is enabled on host servers, a modification of rights must be performed on the various files:
  • chcon -Rt svirt_sandbox_file_t /home/user/lockself/jwt
  • chcon -Rt svirt_sandbox_file_t /home/user/lockself/ssl
  • chcon -Rt svirt_sandbox_file_t /home/user/lockself/env

  • chcon -Rt svirt_sandbox_file_t /home/user/lockself/files

6.5. Action to be taken on the application server - Step 3

Upload the LockSelf image to the web server:

docker load --input lockself-api-X.X.X.tar.gz

There are three options for deploying the application container. It's up to you to choose which one you want to use according to the company's recommendations.

6.5.1. Manual launch

docker run \
 --name lockself-api-3 \
 -v /home/user/lockself/jwt:/usr/local/var/www/html/config/jwt \
 -v /home/user/lockself/ssl:/usr/local/etc/nginx/ssl \
 -v /home/user/lockself/env:/usr/local/var/www/html/.env \
 -v /home/user/lockself/files:/usr/local/var/www/html/var/glutton \
 -v /home/user/lockself/ssl/sp.crt:/usr/local/var/www/html/vendor/onelogin/php-saml/certs/sp.crt \
 -v /home/user/lockself/ssl/ssl-certificate.key:/usr/local/var/www/html/vendor/onelogin/php-saml/certs/sp.key
 -p 80:8080 \
 -p 443:4443 \
 -d lockself-api-v3:X.X.X

• --name: corresponds to the name of the container once created
• -v: corresponds to mounted volumes
• -p: enables the host to forward requests on port 80 and 443 to the container
• -d: allows the container to launch in background
• lockself-api-v3:X.X.X: corresponds to the version of the LockSelf image used

If you want to use docker-compose to start the application container, you can use the configuration file docker-compose.yml below:

version: '3.8'

services:
 lockself-api-3:
 image: lockself-api-v3:X.X.X
 restart: always
 volumes:
 - "/home/user/lockself/jwt:/usr/local/var/www/html/config/jwt"
 - "/home/user/lockself/ssl:/usr/local/etc/nginx/ssl"
 - "/home/user/lockself/env:/usr/local/var/www/html/.env"
 - "/home/user/lockself/files:/usr/local/var/www/html/var/glutton"
 - "/home/user/lockself/ssl/sp.crt:/usr/local/var/www/html/vendor/onelogin/php-saml/certs/sp.crt"
 - "/home/user/lockself/ssl/ssl-certificate.key:/usr/local/var/www/html/vendor/onelogin/php-saml/certs/sp.key"
 ports :
 - "80:8080"
 - "443:4443"

Once the configuration file has been retrieved from the host server, you can start the container via the following command:

docker-compose up -d --build

version: '3.7'

services:
 lockself-api-3:
 image: lockself-api-v3:X.X.X
 ports:
 - target: 8080
 published: 80
 protocol: tcp
 mode: host
 - target: 4443
 published: 443
 protocol: tcp
 mode: host
 volumes:
 - "/home/user/lockself/jwt:/usr/local/var/www/html/config/jwt"
 - "/home/user/lockself/ssl:/usr/local/etc/nginx/ssl"
 - "/home/user/lockself/env:/usr/local/var/www/html/.env"
 - "/home/user/lockself/files:/usr/local/var/www/html/var/glutton"
 - "/home/user/lockself/ssl/sp.crt:/usr/local/var/www/html/vendor/onelogin/php-saml/certs/sp.crt"
 - "/home/user/lockself/ssl/ssl-certificate.key:/usr/local/var/www/html/vendor/onelogin/php-saml/certs/sp.key"

Swarm can be used in a number of ways that we won't detail in this procedure. You can find full details of how it works on its official website: https://docs.docker.com/engine/swarm/

Database migrations (including structure creation) will be done automatically when the container is launched. Check that this is started by executing the command:

• docker logs -f CONTAINER_ID

7. Create the administrator account

Once the infrastructure is in place, you'll have the opportunity to create your administrator account. To do this, go to the URL below and fill in the requested information:

https://FQDN/external/users/validate-account/index.html?firstCo

Where FQDN is the domain name you operate

Request the license key from your Account Manager.

In order to activate the license key, you will need to have a computer with an internet connection to our licensing system. The domain name and IP of this server can be provided by your Account Manager.

8. Backup

Two items are important to save in a safe place once installation is complete:

• The env file generated in step 6.3.
  • This file contains the configuration files essential for the proper operation of your installation. Once generated, these files cannot be regenerated identically. If you were to lose these, the information contained in the database would become indecipherable.
• The database

We recommend applying encryption (symmetrical or asymmetrical) for the backup of these two components.

9. Interconnecting the application in SSO

In order to connect the application in SSO, you can follow the following documentation: SSO interconnection configuration

9.1. Group synchronization

If you send user groups via the Federation and want them to be synchronized in LockSelf, you'll need to change the following parameter in the env file: (make sure the claim groups is sent by the Federation):

intercoAd=0 by intercoAd=1

If you don't want to retrieve all the groups in your directory, you can choose a prefix where only groups with this prefix will be retrieved by LockSelf. The following variable is to be replaced in the env file:

intercoAdPrefix='' by intercoAdPrefix='MY_PREFIX'

Then restart the container.

9.2 Verify connection

If all the steps have been performed correctly, you will be able to make a connection from the SSO tab of the application.

10. Appendices

Appendix 1 - install_lockself.sh

#!/bin/bash
# This script will configure your LockSelf installation
# It will create an env file. This file will be mount in your container.
# Maintain: LockSelf SAS <contact@lockself.com>

if [ -f $PWD/env ]
then
printf "You already have a LockSelf installation. Be careful not to lose the '~/env' file. Without it, it will be impossible to access your datas. If you're sure to would reinstall LockSelf, delete the ~/env file and relaunch this script."
exit 1
fi
printf " _ _ _____ _ __ \n"
printf "| | | | / ____| |/ _|\n"
printf "| ___ ___| | _| (___ ___| | |_ \n"
printf "| / _ \ / __| |/ /\___ \ / _ \ | _|\n"
printf "|___| (_) | (__| < ____) | __/ | | \n"
printf "|______\___/ \___|_|\_\_____/ \___|_|_| \n\n"

printf "Welcome to the LockSelf's on-premises installation program\n"
printf "First, we will configure the database informations (applicative account - step 5.3):\n\n"

while [[  class="token variable">$dbHost == "" ]]
do
printf "DB Host: >" && read dbHost
done
while [[ $dbName == "" ]]
do
printf "DB Name: >" && read dbName
done
while [[ $dbUser == "" ]]
do
printf "DB User (applicative account): >" && read dbUser
done
while [[ $dbPassword variable">$dbPassword == "" ]]
do
printf "DB Password (applicative account): >" && read -s dbPassword
done
while [[ $dbPassword2 == "" ]]
do
printf "\nVerify your DB Password (applicative account): >" && read -s dbPassword2
done
if [[ $dbPassword != $dbPassword2 ]]
then
printf "\nThe two passwords are not corresponding. Please relaunch the installation."
exit 1
fi
printf "\n\nNow, lets configure the database informations for the user lockself_migration: (step 5.3)\n"
while [[ $dbPasswordPhinx == "" ]]
do
printf "DB Password lockself_migration: >" && read -s dbPasswordPhinx
done
while [[ $dbPassword2Phinx == "" ]]
do
printf "\nVerify your DB Password lockself_migration: >" && read -s dbPassword2Phinx
done
if [[ $dbPasswordPhinx != $dbPassword2Phinx ]]
then
printf "\nThe two passwords are not corresponding. Please relaunch the installation."
exit 1
fi
printf "\n\nPlease now enter the passphrase chosen for the JWT: (step 6.2)\n"
while [[ $jwtPassphrase == "" ]]
do
printf "Write your JWT Passphrase: >" && read -s jwtPassphrase
done
while [[ $jwtPassphrase2 == "" ]]
do
printf "\nVerify your JWT Passphrase: >" && read -s jwtPassphrase2
done
if [[ $jwtPassphrase != $jwtPassphrase2 ]]
then
printf "The two passwords are not corresponding. Please relaunch the installation."
exit 1
fi
printf "\n\nLet's configure the SMTP connection (it will be used to send the system email):\n"
while [[ $smtpHost == "" ]]
do
printf "SMTP Host: >" && read smtpHost
done
while [[ $smtpPort == "" ]]
do
printf "SMTP Port: >" && read smtpPort
done
while [[ $smtpAuth == "" ]]
do
printf "SMTP Auth: (true or false) >" && read smtpAuth
done
if [ $smtpAuth == "true" ]
then
while [[ $smtpUsername == "" ]]
do
printf "SMTP Username: >" && read smtpUsername
done
while [[ $smtpPassword == "" ]]
do
printf "SMTP Password: >" && read smtpPassword
done
else
smtpUsername=""
smtpPassword=""
fi
while [[ $smtpSsl == "" ]]
do
printf "SMTP SSL: (ssl or tls or null) >" && read smtpSsl
done
if [ $smtpSsl == "null" ]
then
smtpSsl=""
fi
while [[ [$smtpNoReply == "" ]]
do
printf "No-reply address: (ex: no-reply@company.com) >" && read smtpNoReply
done
printf `date`
printf "\nSMTP configuration terminated\n"
printf "\n\nLast thing, specify the domain you want to use:"
while [[ $domain == "" ]]
do
printf "\nDomain: (ex: lockself.company.com) > " && read domain
done
/bin/cat <<EOF > $PWD/env
###> symfony/framework-bundle ###
APP_ENV=prod
APP_DEBUG=0
APP_SECRET=62ab7ba420f13ef7f912d270c2a40ee0
###< symfony/framework-bundle ###

###> lexik/jwt-authentication-bundle ###
JWT_SECRET_KEY=%kernel.project_dir%/config/jwt/private.pem
JWT_PUBLIC_KEY=%kernel.project_dir%/config/jwt/public.pem
JWT_PASSPHRASE="$jwtPassphrase"
JWT_TTL=604800
###< lexik/jwt-authentication-bundle ###

###> doctrine/doctrine-bundle ###
DATABASE_URL='mysql://$dbUser:$dbPassword@$dbHost:3306/$dbName'
###< doctrine/doctrine-bundle ###

###> robmorgan/phinx ###
PHINX_USER='lockself_migration'
PHINX_PASSWORD='$dbPasswordPhinx'
PHINX_HOST='$dbHost'
PHINX_PORT='3306'
PHINX_DB_NAME='$dbName'
###< robmorgan/phinx ###

###> LockSelf ###
debug=0
domain=$domain
saltPassword1="$(LC_ALL=C tr -dc 'A-Za-z0-9!#%&()+,-./:;<=>?@[\]^_{|}~' </dev/urandom | head -c 16 ; echo)"
saltPassword2="$(LC_ALL=C tr -dc 'A-Za-z0-9!#%&()+,-./:;<=>?@[\]^_{|}~' </dev/urandom | head -c 16 ; echo)"
saltPin1="$(LC_ALL=C tr -dc 'A-Za-z0-9!#%&()+,-./:;<=>?@[\]^_{|}~' </dev/urandom | head -c 16 ; echo)"
saltPin2="$(LC_ALL=C tr -dc 'A-Za-z0-9!#%&()+,-./:;<=>?@[\]^_{|}~' </dev/urandom | head -c 16 ; echo)"
keyPin="$(LC_ALL=C tr -dc 'A-Za-z0-9!#%&()+,-./:;<=>?@[\]^_{|}~' </dev/urandom | head -c 32 ; echo)"
ivPin="$(LC_ALL=C tr -dc 'A-Za-z0-9!#%&()+,-./:;<=>?@[\]^_{|}~' </dev/urandom | head -c 16 ; echo)"
saltApiHash1="$(LC_ALL=C tr -dc 'A-Za-z0-9!#%&()+,-./:;<=>?@[\]^_{|}~' </dev/urandom | head -c 16 ; echo)"
saltApiHash2="$(LC_ALL=C tr -dc 'A-Za-z0-9!#%&()+,-./:;<=>?@[\]^_{|}~' </dev/urandom | head -c 16 ; echo)"
sampleHash="$(LC_ALL=C tr -dc 'A-Za-z0-9!#%&()+,-./:;<=>?@[\]^_{|}~' </dev/urandom | head -c 16 ; echo)"
blockConnexionInSecond=900
pinLength=6
saltTransfer1="$(LC_ALL=C tr -dc 'A-Za-z0-9!#%&()+,-./:;<=>?@[\]^_{|}~' </dev/urandom | head -c 16 ; echo)"
saltTransfer2="$(LC_ALL=C tr -dc 'A-Za-z0-9!#%&()+,-./:;<=>?@[\]^_{|}~' </dev/urandom | head -c 16 ; echo)"
saltTransferProtectedEmail1="$(LC_ALL=C tr -dc 'A-Za-z0-9!#%&()+,-./:;<=>?@[\]^_{|}~' </dev/urandom | head -c 16 ; echo)"
saltTransferProtectedEmail2="$(LC_ALL=C tr -dc 'A-Za-z0-9!#%&()+,-./:;<=>?@[\]^_{|}~' </dev/urandom | head -c 16 ; echo)"
saltDeposit1="$(LC_ALL=C tr -dc 'A-Za-z0-9!#%&()+,-./:;<=>?@[\]^_{|}~' </dev/urandom | head -c 16 ; echo)"
saltDeposit2="$(LC_ALL=C tr -dc 'A-Za-z0-9!#%&()+,-./:;<=>?@[\]^_{|}~' </dev/urandom | head -c 16 ; echo)"
saltMail1="$(LC_ALL=C tr -dc 'A-Za-z0-9!#%&()+,-./:;<=>?@[\]^_{|}~' </dev/urandom | head -c 16 ; echo)"
saltMail2="$(LC_ALL=C tr -dc 'A-Za-z0-9!#%&()+,-./:;<=>?@[\]^_{|}~' </dev/urandom | head -c 16 ; echo)"
bucket=
providerAccessKey=
providerSecretKey=
providerRegion=
providerEndpoint=
provider=LOCAL
depositTokenTime=15
noReplyEmail='$smtpNoReply'
colorBtn='#39499b'
companyName="LockSelf"
nameDepositBox="Access to a deposit box"
newFileDeposit="New file uploaded"
newTransfer="New protected file received"
apiVersion=3
intercoAd=0
intercoAdPrefix=''
importOrganization=0
importOrganizationSendEmail=0
intercoAdOrganizations=0
###< LockSelf ###

###> symfony/swiftmailer-bundle ###
MAILER_URL=smtp://$smtpHost:$smtpPort?encryption=$smtpSsl&username=$smtpUsername&password=$smtpPassword
###< symfony/swiftmailer-bundle ###

###> ovh/ovh ###
smsApplicationKey=
smsApplicationSecret=
smsConsumerKey=
smsEndpoint=
###< ovh/ovh ###

###> knplabs/knp-snappy-bundle ###
WKHTMLTOPDF_PATH=/usr/local/bin/wkhtmltopdf
WKHTMLTOIMAGE_PATH=/usr/local/bin/wkhtmltoimage
###< knplabs/knp-snappy-bundle ###

EOF

printf "\n\nStep 6.3 terminated. If you want to review your config file, like your smtp or database configuration, you can check the 'env' file which is created by this script or you can continue the deployment guide."

Updated December 10, 2024 16:31