Administration - rodekruis/EspoCRM-knowledge-base GitHub Wiki

On this page you can find here information on:

Advanced Pack

The Advanced Pack can be installed following these steps:

Buy the Advanced Pack with the Red Cross discount.
It will be available on the EspoCRM Portal
At "Product Releases" on the Home page, Download the desired version of the Advanced Pack
In your EspoCRM instance, go to "Administration" > "Extensions"
Upload the file that was downloaded from the EspoCRM Portal

NB. For updating the Advanced Pack, follow step 2 to 5.

Setting binary logs expiry policy

The default retention rate of mysql binary logs is 30 days, which can result in large files. Therefore it is good practice to change this value.

Assuming the docker containers are running:

First check the current disk usage by running command

df -h

To change the binlog file, you will need to get the MySQL root password first from the dockercompose file:

cat /var/www/espocrm/docker-compose.yml

Then copy the root mysql password to be found as MYSQL_ROOT_PASSWORD

Next, go into the docker container of the mysql and execute bash:

sudo docker exec -ti espocrm-mysql /bin/bash

Then, execute as root:

mysql -u root -p

Fill in the root mysql password you copied in the first step, then:

SET PERSIST binlog_expire_logs_seconds=864000;

This will set the expiry date to 10 days: 10 days * 24 hours * 60 minutes * 60 seconds = 864000 seconds

If you want to save more space, and you are running a daily backup of the entire virtual machine (including the SQL) in Azure, then you can set the expiry date to 3 days: 3 days * 24 hours * 60 minutes * 60 seconds = 259200 seconds

SET PERSIST binlog_expire_logs_seconds=259200;

If you want to free up space you can purge old binlog files, by logging in to the mysql server

PURGE BINARY LOGS BEFORE '2023-01-01 00:00:00';

Exit the root of MySQL:

exit

You can always check how much space the bin logs are taking by going to:

cd /var/www/espocrm/data/mysql/data/

Then check the files in the folder and their size by doing:

ls -lh

Preallocate disk space

As a contingency measure, it is adviced to preallocate disk space by creating a mock file with a certain size. The goal of this file is to have something you can delete once the drive is full. If not, you might need to manually delete the binlogs before you can restart the mysql container (you cannot start the container if there is not disk space to write to). You can create this 500MB mock file by executing the following command in your home folder:

fallocate -l 500M testfile.img

Then, if needed, you can delete this file by

rm testfile.img

Disable binlogs through docker compose file.

You can also disable the binary logging for the mysql container all together, please make sure you understand the risks.

If you want to disable binary logging, please change your docker-compose file /var/www/espocrm/docker-compose.yml accordingly under the command section like below.

  espocrm-mysql:
    image: mysql:8
    container_name: espocrm-mysql
    command:
      - '--default-authentication-plugin=mysql_native_password'
      - '--disable-log-bin'
      - '--skip-log-bin'
    restart: always
    environment:
      MYSQL_ROOT_PASSWORD: mysqlRootPassword
      MYSQL_DATABASE: espocrm
      MYSQL_USER: espocrm
      MYSQL_PASSWORD: mysqlPassword
    volumes:
      - ./data/mysql/data:/var/lib/mysql
    networks:
      - internal

Then recreate the containers by running sudo docker-compose up -d in /var/www/espocrm/.

Then test if if worked by executing show variables like 'log_bin'; in the sql server. Output should look like this:

mysql> show variables like 'log_bin';
+---------------+-------+
| Variable_name | Value |
+---------------+-------+
| log_bin       | OFF   |
+---------------+-------+
1 row in set (0.11 sec)

Setting the GET api limit

The default api limit is 200 records, and the api does not support pagination. This is changend in the config.php file.

Go to your home espo folder (for dockerised installations its /var/www/espocrm/data/espocrm)

Go to the data folder

Then: sudo nano config.php (or any other type of editor)

Find recordListMaxSizeLimit and change the number to the desired numer

Close and save.

Access logs via SSH (Putty)

The logs are useful to check for numerous reasons:

Check errors related to API calls
more to add..

In one of the newest versions of EspoCRM, you can access the logs via the admin UI, so the below docs are not necessary anymore

If you want to access logs via the VM, these can be accessed via the following steps:

Install Putty https://www.putty.org/
Open Putty and fill in Host Name (for example dchtest.510.global). Leave Port to 22 and Connection type to SSH.
Click on Open and a new window should appear
Fill in login credentials. The password will be invisible when you add this. You can paste the password by right-clicking on the password field.
Navigate to /var/www/espocrm/data/espocrm/data/logs via: First go up 2 directories and navigate to the folder containing the logs:

cd ../../var/www/espocrm/data/espocrm/data/logs

Use ls to see the list of available logs
Open specific log (for example 'espo-2022-12-15.log') by following command: cat espo-2022-12-15.log

Protip: you can get more descriptive logs by enabling the debug mode.

Setting up backup schedule for VM

Preparation

Create a VM in Azure

Setup back up configuration

Navigate to the VM in Azure Portal
In the left menu navigate to "Backup"

First select a Recovery Services Vault. Note that you do not always have to create a new vault. Look in the dropdown list if there is a vault in which you could store the backups. If not, select "Create new"
If "Create new" give your vault a sensible name and select the Resource Group the VM is also stored in
Choice a Policy sub type
- Trusted Azure VM's cannot be backed up using the Standard Policy sub type
Decide how often you want to make a backup. If this does not correspond to the described Policy Details (below on page) then create a new policy.
- Give your new policy a sensible name
- Define the interval at which backups should be created
- "Retain instant recovery snapshot(s) for" can be left to 7 days
- "Retention of daily backup point For" can be left to 30 days
- The rest can be left blank
Review the Policy Details
If everything looks okay then finalize with "Enable backup"
This will immediately deploy the new resources and start making an initial backup

Automated security updates

How to configure automated Linux security updates in a VM hosting EspoCRM.

From the Azure Portal, select your VM > Operations > Updates > Update settings.
Under Patch orchestration select Customer Managed Schedules then Save.
From the Maintenance Configuration weekly-security-updates, select Settings > Resources > + Add > your VM > Ok. Critical security updates will be installed each Sunday, at midnight CET (UTC+01:00).

Renew SSL Certificate (Automatically)

The renewal of the certificate can be done with one command from the VM

sudo /var/www/espocrm/command.sh cert-renew

To run this command automatically every day, use systemd-run

sudo systemd-run --no-ask-password --on-calendar=23:35 --unit=certbot-renew.service sudo /var/www/espocrm/command.sh cert-renew

Single Sign On Active Directory

Based on the following manual. More background information on Entra ID can be found here.

Log in to the Azure portal or Entra Admin Center (for non-Azure, 365 tenants
Select the “Azure Active Directory” option from the left-hand menu
Select the “App registrations” option
Click on the “New registration” button
Enter a name for the app (e.g. EspoCRM)
Click on the “Register” button to create the app and get the “Application (client) ID”.

Now that you have the necessary information from the Azure portal, you can configure EspoCRM for Office 365 integration. To do this, follow these steps:

In your EspoCRM instance, go to Administration -> Authentication and change the Authentication Method to “OIDC”.
Disable 'Only one auth token per user'
If your Active Directory SSO has 2 factor authentication then disable 'Enable 2-Factor Authentication' (or you will have double 2FA). Otherwise enable.
Enable 'Disable password recovery'. Passwords have to be recovered through the Active Directory regular process
In the Azure Portal, in the App Registration, go to API permissions. Set the following permissions:
Scroll down to the “OIDC” section in EspoCRM and enter the “Application (client) ID” that you copied from the Azure Portal into the “Client ID” field.
In the Azure Portal, go to the “Certificates & secrets” tab on the left-hand side and click on the “New client secret” button to create a new secret key for your app.
Copy the value of the newly created secret key and paste it into the “Client Secret” field in the “OIDC” section of EspoCRM.
In the Azure Portal, go to the “Authentication” tab on the left-hand side and paste the “Authorization Redirect URI” that you copied from EspoCRM into the “Web Redirect URIs” section.
In the Azure Portal, go to the Overview page, and in the right screen, click Endpoints
In EspoCRM, copy the “OAuth 2.0 authorization endpoint (v2)” value from the “Endpoints” section of your Azure app and paste it into the “Authorization Endpoint” field in the “OIDC” section.
Copy the “OAuth 2.0 authorization endpoint (v2)” value from the “Endpoints” section of your Azure app and paste it into the “Authorization Endpoint” field in the “OIDC” section, inside EspoCRM.
Similarly, copy the “OAuth 2.0 token endpoint (v2)” value and paste it into the “Token Endpoint” field.
Open the “OpenID Connect metadata document endpoint” in your browser, copy the value of the “jwks_uri” parameter, and paste it into the “JSON Web Key Set Endpoint” field in EspoCRM. Also, copy the value of the “end_session_endpoint” parameter and paste it into the “Logout URL” field in EspoCRM.
Change content of Username Claim in EspoCRM to email. Thanks to that username will be matched by email address from Microsoft.
Ensure all Users in Espocrm have their Email address as username (can be migrated using a report and workflow, or a formula script)
Disable checkbox under Create User, unless you want all users in the Active Directory to have access to the CRM by default
Enable checkbox under Allow OIDC login for admin users.
Enable fall back login for admin users. Disable for regular users
If you want to configure the Name in EspoCRM interface, make sure to disable checkbox of Sync (this prevents this field be synced with Azure)
Finally click on the “Save” button in EspoCRM.

You need to make a change in the EspoCRM config. Login to the terminal through SSH and edit the configuration file

Navigate to and open config.php with the following commands:

cd ../../

cd var/www/espocrm/data/espocrm/data

sudo nano config.php

In data/config.php, add 'oidcAuthorizationPrompt' => 'login'.
Save the file (Ctrl + X and Y and Enter)

Now open your espocrm instance, and test the login. The login page should look like this:

Set up outbound email configuration

[!IMPORTANT] The recommended service to handle emails is SendGrid, see how to set it up.

In general, you need to set up Simple Mail Transfer Protocol. Users can set it up in Preferences as well as in their Personal Email Accounts. An administrator can also allow to use System SMTP (make it shared).

You need to check with your IT department what email account you can use for EspoCRM.

To setup SMTP, do the following:

Go to Administration > Outbound Emails.
Enter your SMTP Host name; in SMTP security field select TLS for a secure connection. A proper SMTP Port will be set automatically.
Enter the password.
Click on Send Test Email to check whether everything was specified correctly.

If the connection is successful, you will receive test email on the specified email address.

Increase disk size

Problems with your EspoCRM instance arise when the disk is full, you will probably get an Error 500 and things won't work. More information on what happens?

To solve, follow the next steps:

Review the disk usage to see if indeed the disk is full
If full, increase the disk size

Review disk usage

Log in to the VM
Run the following command: df -h
The output will show you the amount of disk space available per file/folder
Inspect if /dev/root is on 100%

Increase disk size

In Azure, go to the VM
Stop the VM
- Important! The EspoCRM instance will not be accessible, so make sure to inform the correct people and plan well
Go to Settings > Disks
Select the disk that needs to be increased in size
Go to Settings > Size + performance
Select the new disk size needed
Click on "Resize"
Start VM again
- Review if EspoCRM is live again, update relevant people

Also see: Resize a managed disk in the Azure portal

Increase PHP memory limit

When running large flows, it is possible to run into PHP memory limits.

These are the steps you can take to increase the PHP memory limit:

Go to the espocrm docker container
- SSH into the VM
- Make sure docker container is running, by executing docker ps (might need to do sudo docker ps)
- Go into the espocrm docker container, by executing docker exec -it espocrm /bin/bash
- To leave the container, use CTRL+D
Review the current memory limit, by using one of these methods:
- Execute from anywhere in the docker container
  
  a. php -r "echo ini_get('memory_limit').PHP_EOL;"
  
  b. php -i | grep "memory_limit"
c. Go to the file and inspect
- Go to the correct folder: cd usr/local/etc/php/conf.d
- Open the espocrm.ini file by executing cat espocrm.ini
- Review the memory_limit in the file
Update memory limit
- Execute from conf.d folder nano espocrm.ini
  - If nano not installed use: sudo apt-get update and then sudo apt-get install nano
- Change the memory_limit in the file (e.g. to "512M")
- Save changes, by using ctrl+O
- Click Enter to confirm you want to save this in espocr.ini
- Close the editor by using ctrl+x
Review memory limit again, as explained in step 2, you can also see this under Administration -> System Requirements -> memory_limit

Upgrade EspoCRM version

Keeping your software up to date is important because software updates improve existing features, patch security flaws, add new security features and fix bugs. Using outdated software can lead to security vulnerabilities, which cybercriminals and hackers can exploit to gain unauthorized access to your accounts, data and device.

Before upgrading

Review release notes and check if anything changed that could potentially cause issues.
Review if there is enough disk space for the upgrade
- SSH into VM
- Review system information that is shown, or run df -h
Make a backup of the VM
- Go to the VM in Azure > Backup + disaster recovery > Backup > Backup now
If an external database is used: make a backup of the database
- Go to the database in Azure > Settings > Backup and restore > Backup now
Review if the current PHP version of the system is compatible with the EspoCRM version you're going to upgrade to
- In your EspoCRM instance, go to Administration > System requirements > Check your PHP version
- Compare to PHP version supported by version you want to upgrade to; the PHP version required by the latest EspoCRM release can be found here
- If necessary, upgrade PHP:
  - SSH into the VM
  - Run sudo apt-get update && sudo apt-get upgrade
Enable maintenance mode in EspoCRM: Administration > Settings > Maintenance Mode
Disable cron in EspoCRM: Administration > Settings > Disable Cron

Upgrade

SSH into the VM
Run sudo /var/www/espocrm/command.sh upgrade

After upgrading

Disable maintenance mode in EspoCRM
Enable cron in EspoCRM
Review if everything still works as expected