Page History

...

1. Point your web browser to the location where you uploaded the contents of blesta (e.g. https://yourdomain.com/path_to_blesta/).
2. Follow the on screen instructions to complete installation.
3. Once installation completes, you'll be prompted to create your administrator user and enter your license key or start a free trial.

Command Line Installation

Follow these steps to install Blesta via the command line.

...

For interactive mode run 

php ./index.php install

...

If Blesta is not installed in the document root on your web server, it is important to note that the "Root Web Directory" setting will be inaccurate unless you install Blesta while your current working directory is set to the document root:

cd /to/your/web/server/document/root/
php ./path/to/blesta/index.php install

For automatic mode run

php ./index.php install -dbhost DATABASE_HOST -dbname DATABASE_NAME -dbuser DATABASE_USER -dbpass DATABASE_PASS -hostname WEBSITE_HOSTNAME -docroot DOCUMENT_ROOT_PATH

...

The full absolute path to the web server's document root (e.g. /var/www/html/). This should not be set to Blesta's installed directory unless Blesta is installed in document root. If this value is not set, it will be set based on your current working directory, which will not be accurate unless the current working directory is the document root.

...

Once completed, you'll be logged in for the first time automatically. For subsequent logins, see Logging In. You may also want to enable Two-Factor Authentication.

5. Set up a Cron Job

Once installation is complete, a cron job must be created to automate tasks within Blesta. Go to [Settings] > [System] > Automation, and copy the "Cron Command", for use in creating a cron job on your server. Most hosting control panels provide an easy way to create cron jobs, follow the documentation for your control panel to complete this important step. The cron job should run every 5 minutes. Once the cron has been configured, verify that the status icon turns green and displays the last time run on the System Automation page within Blesta.

Image Removed

System Configuration

There are a number of configuration settings that may be set before or after installation.

Requiring index.php in URLs

By default Blesta does not include index.php as part of any URL request, thanks to the use of .htaccess mod_rewrite rules. If your server does not support mod_rewrite Blesta requires index.php to be included in all URLs. To force Blesta to include index.php in all URLs simply rename or delete the .htaccess file included with Blesta in your root web directory.

Changing the path to the Admin area

By default the path to the Admin area begins with /admin/. To change this locate routes.php in /installpath/config/routes.php and modify the value of the "Route.admin" configuration. For example, to change the path of the admin area to /staff/ set the following:

Configure::set("Route.admin", "staff");

Changing the path to the Client area

By default the path to the Client area begins with /client/. To change this locate routes.php in /installpath/config/routes.php and modify the value of the "Route.client" configuration. For example, to change the path of the client area to /customers/ set the following:

Configure::set("Route.client", "customers");

Forcing HTTPS

If your server supports mod_rewrite, you can enable HTTPS redirects by uncommenting the following lines (remove the '#' symbols) from the .htaccess file included with Blesta.

#RewriteCond %{HTTPS} !=on
#RewriteRule ^ https://%{HTTP_HOST}%{REQUEST_URI} [R=307,NE,L]

Common Installation Issues

Errors

...

• You must apply the correct hotfix files to your installation.

...

• You may not have the ionCube loader installed correctly, or you may not have applied the correct hotfix files over your Blesta installation.

...

If the credentials are correct you may have MySQL old_passwords enabled. Disable old_passwords for your database or update your user's password:

% mysql
% SET SESSION old_passwords=0;
% SET PASSWORD FOR 'username'@'localhost' = PASSWORD('password');

The following is an example PHP script to perform automatic (not interactive) installation via the web URL:

<?php
#
# This makes a POST request to the Blesta installer
#

$post = [
    'agree' => 'yes',
    'host' => 'localhost',
    'port' => '3306',
    'database' => 'blesta',
    'user' => 'user',
    'password' => 'password',
];

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'myblestadomain.com/install/process');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($post));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$errors = curl_error($ch);
curl_close($ch);

echo "RESPONSE: ";
print_r($response);

echo "ERRORS: ";
var_dump($errors);

NOTE! If the web server is not Apache, or is missing mod_rewrite, the curl URL must be pre-pended with index.php, e.g. myblestadomain.com/index.php/install/process

Command Line Installation

Follow these steps to install Blesta via the command line.

1. In a shell, cd to the directory you uploaded the contents of blesta.
2. The CLI installer can be run in interactive mode, or non-interactive mode by passing parameters.

   1. For interactive mode run 

      Code Block
      php ./index.php install

      
      

      Info
      title Root Web Directory Setting
      If Blesta is not installed in the document root on your web server, it is important to note that the "Root Web Directory" setting will be inaccurate unless you install Blesta while your current working directory is set to the document root: Code Block title Installing from the web server's document root cd /to/your/web/server/document/root/ php ./path/to/blesta/index.php install

      
      

   2. For automatic mode run

      Code Block

      php ./index.php install -dbhost DATABASE_HOST -dbport DATABASE_PORT -dbname DATABASE_NAME -dbuser DATABASE_USER -dbpass DATABASE_PASS -hostname WEBSITE_HOSTNAME -docroot DOCUMENT_ROOT_PATH With staff user creation (Fully Scripted) v5.10+: php ./index.php install -dbhost DATABASE_HOST -dbport DATABASE_PORT -dbname DATABASE_NAME -dbuser DATABASE_USER -dbpass DATABASE_PASS -hostname WEBSITE_HOSTNAME -docroot DOCUMENT_ROOT_PATH -domain DOMAIN -licensekey LICENSE_KEY -firstname FIRST_NAME -lastname LAST_NAME -email EMAIL -username USERNAME -password PASSWORD

      
      

      Parameter	Description	Version Added
      -dbhost	The database hostname (usually localhost)	3.0
      -dbport	The database port (usually 3306)	3.0
      -dbname	The database name	3.0
      -dbuser	The database user	3.0
      -dbpass	The database password	3.0
      -hostname	The website hostname. For example, billing.domain.com. The is the hostname where Blesta will be accessed from. If not set, will attempt to detect the hostname from server configuration, which in many cases will not be accurate.	3.0
      -docroot	The full absolute path to the web server's document root (e.g. /var/www/html/). This should not be set to Blesta's installed directory unless Blesta is installed in document root. If this value is not set, it will be set based on your current working directory, which will not be accurate unless the current working directory is the document root. Info This value can be changed from within Blesta, after installation, under Settings > System > General > "Root Web Directory".	4.6
      -domain	(Optional) The domain to be used in template email addresses. Info This value is used to determine email addresses for templates and can be changed under Settings > Company > Emails.	5.10
      -licensekey	(Optional) The license key for Blesta. If none is provided, a trial license will befetched.	5.10
      -firstname	The First Name of the first Staff user.	5.10
      -lastname	The Last Name of the first Staff user.	5.10
      -email	The email address for the first Staff user.	5.10
      -username	The username for the first Staff user.	5.10
      -password	The password for the first Staff user.	5.10

      
      

3. Once installation completes, direct your web browser to https://yourdomain.com/path_to_blesta/admin/ to create your administrator user and enter your license key or start a free trial.

Once completed, you'll be logged in for the first time automatically. For subsequent logins, see Logging In. You may also want to enable Two-Factor Authentication.

5. Set up a Cron Job

Once installation is complete, a cron job must be created to automate tasks within Blesta. Go to [Settings] > [System] > Automation, and copy the "Cron Command", for use in creating a cron job on your server. Most hosting control panels provide an easy way to create cron jobs, follow the documentation for your control panel to complete this important step. The cron job should run every 5 minutes. Once the cron has been configured, verify that the status icon turns green and displays the last time run on the System Automation page within Blesta.

Image Added

System Configuration

There are a number of configuration settings that may be set before or after installation.

Requiring index.php in URLs

By default Blesta does not include index.php as part of any URL request, thanks to the use of .htaccess mod_rewrite rules. If your server does not support mod_rewrite Blesta requires index.php to be included in all URLs. To force Blesta to include index.php in all URLs simply rename or delete the .htaccess file included with Blesta in your root web directory.

Changing the path to the Admin area

By default the path to the Admin area begins with /admin/. To change this locate routes.php in /installpath/config/routes.php and modify the value of the "Route.admin" configuration. For example, to change the path of the admin area to /staff/ set the following:

Configure::set("Route.admin", "staff");

Changing the path to the Client area

By default the path to the Client area begins with /client/. To change this locate routes.php in /installpath/config/routes.php and modify the value of the "Route.client" configuration. For example, to change the path of the client area to /customers/ set the following:

Configure::set("Route.client", "customers");

Forcing HTTPS

If your server supports mod_rewrite, you can enable HTTPS redirects by uncommenting the following lines (remove the '#' symbols) from the .htaccess file included with Blesta.

#RewriteCond %{HTTPS} !=on
#RewriteRule ^ https://%{HTTP_HOST}%{REQUEST_URI} [R=307,NE,L]

Common Installation Issues

Errors

• During installation, you receive a blank page that reads "The file /blesta/app/models/license.php is corrupted." or "The file /blesta/app/app_controller.php is corrupted."
  
  • You must apply the correct hotfix files to your installation.
• During installation, you receive a blank white page (or a 500 Internal Server Error).
  • You may not have the ionCube loader installed correctly, or you may not have applied the correct hotfix files over your Blesta installation.
• Connection FAILED. Ensure that you have created the database and that the credentials are correct.
  • Check to ensure the hostname, database name, user, and password you entered are correct and try again.

  • If the credentials are correct you may have MySQL old_passwords enabled. Disable old_passwords for your database or update your user's password:

    Code Block
    language bash
    % mysql % SET SESSION old_passwords=0; % SET PASSWORD FOR 'username'@'localhost' = PASSWORD('password');

    
    

• Call to undefined function crypt_random() on line 1660 in /home/user/blesta/vendors/phpseclib/Crypt/RSA.php
  • The line number and path may be different. This error has most commonly been seen with Nginx installations. The issue has to do with a missing include_path in php.ini.
  • Edit your php.ini to add the include_path to your PHP binary.
  • Please see this forum thread for more details on this issue, and to download a test script to confirm whether your server is affected by this issue.
• The email failed to send due to a configuration issue. Occurs when trying to send an email, and email is configured correctly.
  • Disable SELinux (Via SSH run as root "echo 0 > /selinux/enforce" Then, so that it remains off after boot, edit /etc/sysconfig/selinux and set SELINUX=disabled
  • If you MUST run SELinux (not recommended) you can run the following command instead "setsebool -P httpd_can_sendmail 1"
• Mod rewrite is not enabled, or htaccess is not supported by this server.
  
  • Make sure mod_rewrite is loaded in Apache and that AllowOverrides is set to All in your httpd.conf for your virtualhost
  • Make sure MultiViews is disabled in your virtualhost in httpd.conf. (If you receive this error and the URL in your browser is ~/install/ this is almost certainly the issue)
• Cron does not work, outputs error "Undefined variable: argv on line"...
  • Edit your php.ini file and set register_argc_argv to "on". Restart the web server.
  • If running CloudLinux, you may need to edit the php.ini for alt-php. The location of the php.ini will be something like: /opt/alt/php54/etc/php.ini (Note the version php54, php55, etc) Then, run the following command to rebuild: cagefsctl --rebuild-alt-php-ini
• I get a white page at /settings/company/billing/invoices/ after upgrading to version 4
  
  • Remove ~/helpers/html. This directory was removed in v4 and may be causing the issue. You might also see the error "Cannot declare class Html, because the name is already in use in ..."
• I get an "Undefined index: total" or "Error while sending QUERY packet" or "PDOStatement::execute(): send of 113 bytes failed with errorno=32 Broken pipe"
  
  • It's possible max_allowed_packets and/or wait_timeout values are too low in your MySQL config. Edit /etc/my.cnf (default location) and set max_allowed_packets to a value of 128M or higher, and wait_timeout to a value of 3600 or higher.
• After I install, when I try to login it automatically logs me out. I may see a flash of the Dashboard before I'm redirected.
  • Make sure the PHP extension Suhosin is disabled.
• I get an error about open_basedir restriction: realpath(): open_basedir restriction in effect
  
  • We recommend disabling open_basedir. For Plesk, see https://support.plesk.com/hc/en-us/articles/213919825-How-to-change-PHP-parameter-for-all-domains- and set open_basedir to "none". For cPanel see https://documentation.cpanel.net/display/76Docs/PHP+open_basedir+Tweak
  • The alternative is to add additional paths to open_basedir to satisfy Blesta, including /dev/urandom, /tmp, and your users home directory (i.e. /home/username/)

IIS

• Submitting data reloads the current page

  • There is an issue with your web.config file. Try the following web.config file:

    Code Block

    <?xml version="1.0"?> <configuration> <system.webServer> <rewrite> <rules> <rule name="Main Rule" stopProcessing="true"> <match url=".*" /> <conditions logicalGrouping="MatchAll"> <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" /> <add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" /> </conditions> <action type="Rewrite" url="index.php" /> </rule> </rules> </rewrite> </system.webServer> </configuration>

    Next, update /core/ServiceProviders/MinphpBridge.php and make the following change:

    Code Block
    // $htaccess = file_exists($rootWebDir . '.htaccess'); $htaccess = true;

    
    

Nginx

• For pretty URL's (without /index.php/ in every URI) you will need to add a custom Nginx configuration. For a community provided example configuration, please see https://www.blesta.com/forums/index.php?/topic/9320-nginx-config/ or use the following (recommended) configuration

  • 
    

    Code Block

    # Redirect HTTP to HTTPS server { listen 0.0.0.0:80 default_server ssl http2; # IPv4 listen [::]:80 default_server ssl http2; # IPv6 server_name account.yourdomain.com; # Hostname return 301 https://$host$request_uri; } # Run Blesta on SSL server { listen 0.0.0.0:443 default_server ssl http2; # IPv4 listen [::]:443 default_server ssl http2; # IPv6 server_name account.yourdomain.com; # Hostname root /var/www/account.yourdomain.com; # Installation directory # SSL cert/key pair ssl_certificate /etc/ssl/certs/account.yourdomain.com.crt; ssl_certificate_key /etc/ssl/private/account.yourdomain.com.key; # iFrame protection add_header X-Frame-Options SAMEORIGIN; location / { try_files $uri /index.php; rewrite ^(.*)/install\.php$ /$1/install/ redirect; } location = /index.php { fastcgi_pass unix:/run/php/php7.3-fpm.sock; # PHP socket fastcgi_param SCRIPT_FILENAME $document_root/index.php; # Blesta /index.php fastcgi_param SCRIPT_NAME $fastcgi_script_name; include fastcgi_params; } location ~ /\. { log_not_found off; return 404; } location ~* \.(php|pdt|txt)$ { log_not_found off;

...

• The line number and path may be different. This error has most commonly been seen with Nginx installations. The issue has to do with a missing include_path in php.ini.
• Edit your php.ini to add the include_path to your PHP binary.
• Please see this forum thread for more details on this issue, and to download a test script to confirm whether your server is affected by this issue.

...

• Disable SELinux (Via SSH run as root "echo 0 > /selinux/enforce" Then, so that it remains off after boot, edit /etc/sysconfig/selinux and set SELINUX=disabled
• If you MUST run SELinux (not recommended) you can run the following command instead "setsebool -P httpd_can_sendmail 1"

...

• Make sure mod_rewrite is loaded in Apache and that AllowOverrides is set to All in your httpd.conf for your virtualhost
• Make sure MultiViews is disabled in your virtualhost in httpd.conf. (If you receive this error and the URL in your browser is ~/install/ this is almost certainly the issue)

...

• Edit your php.ini file and set register_argc_argv to "on". Restart the web server.
• If running CloudLinux, you may need to edit the php.ini for alt-php. The location of the php.ini will be something like: /opt/alt/php54/etc/php.ini (Note the version php54, php55, etc) Then, run the following command to rebuild: cagefsctl --rebuild-alt-php-ini

...

• Remove ~/helpers/html. This directory was removed in v4 and may be causing the issue. You might also see the error "Cannot declare class Html, because the name is already in use in ..."

...

• It's possible max_allowed_packets and/or wait_timeout values are too low in your MySQL config. Edit /etc/my.cnf (default location) and set max_allowed_packets to a value of 128M or higher, and wait_timeout to a value of 3600 or higher.

...

• Make sure the PHP extension Suhosin is disabled.

...

• We recommend disabling open_basedir. For Plesk, see https://support.plesk.com/hc/en-us/articles/213919825-How-to-change-PHP-parameter-for-all-domains- and set open_basedir to "none". For cPanel see https://documentation.cpanel.net/display/76Docs/PHP+open_basedir+Tweak
• The alternative is to add additional paths to open_basedir to satisfy Blesta, including /dev/urandom, /tmp, and your users home directory (i.e. /home/username/)

IIS

• Submitting data reloads the current page
  For pretty URL's (without /index.php/ in every URI) you will need to add a custom Nginx configuration. For a community provided example configuration, please see https://www.blesta.com/forums/index.php?/topic/9320-nginx-config/ or use the following (recommended) configuration

  • There is an issue with your web.config file. Try the following web.config file:

    Code Block
    <?xml version="1.0"?> <configuration> <system.webServer> <rewrite> <rules> <rule name="Main Rule" stopProcessing="true"> return 404; } }

    
    

    Expand
    title Here's an additional configuration for systems with TLS 1.3 support (Running OpenSSL 1.1.1+)
    Code Block server { listen <matchurl=".*"/> 80 default_server; listen [::]:80 default_server; <conditions logicalGrouping="MatchAll"> server_name _; access_log /path/to/.logs/access.log main; error_log /path/to/.logs/errors.log warn; <addinput="{REQUEST_FILENAME}" matchType="IsFile" negate="true" /> root /path/to/site/public; index index.php index.html; location / { try_files $uri $uri/ /index.php?q=$uri&$args; } <addinput="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" /> error_page 500 502 503 504 /50x.html; location = /50x.html { root /var/lib/nginx/html; } location ~ </conditions> \.php$ { try_files $uri =404; <action type="Rewrite" url="index.php" /> fastcgi_split_path_info ^(.+\.php)(/.+)$; </rule> fastcgi_pass 127.0.0.1:9000; </rules> </rewrite> </system.webServer> </configuration>

    Next, update /core/ServiceProviders/MinphpBridge.php and make the following change:

    Code Block
    // $htaccess = file_exists($rootWebDir . '.htaccess');$htaccess = true;

  Nginx

  • • Code Block

      # Redirect HTTP to HTTPS server { listen 0.0.0.0:80 default_server ssl http2; # IPv4 listen [::]:80 default_server ssl http2; # IPv6 server_name account.yourdomain.com; # Hostname return 301 https://$host$request_uri; } # Run Blesta on SSL server { listen 0.0.0.0:443 default_server ssl http2; # IPv4 listen [::]:443 default_server ssl http2; # IPv6 server_name account.yourdomain.com; # Hostname root /var/www/account.yourdomain.com; # Installation directory # SSL cert/key pair ssl_certificate /etc/ssl/certs/account.yourdomain.com.crt; ssl_certificate_key /etc/ssl/private/account.yourdomain.com.key; # iFrame protection add_header X-Frame-Options SAMEORIGIN; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; fastcgi_param SCRIPT_NAME $fastcgi_script_name; fastcgi_index index.php; include fastcgi_params; } location ~* \.(jpg|jpeg|gif|png|css|js|ico|xml)$ { expires 5d; } if ($scheme != https) { return 307 https://domain.tld$request_uri; } } server { listen 443 ssl; listen [::]:443 ssl; server_name _; access_log /path/to/.logs/access.log main; error_log /path/to/.logs/errors.log warn; root /path/to/site/public; index index.php index.html; location / { try_files $uri $uri/ /index.php?q=$uri&$args; } error_page 500 502 503 504 /50x.html; location = /50x.html { root /var/lib/nginx/html; } location ~ \.php$ { location try_files / $uri { =404; try_files $uri /index.php fastcgi_split_path_info ^(.+\.php)(/.+)$; fastcgi_pass 127.0.0.1:9000; rewrite ^(.*)/install\.php$ /$1/install/ redirect fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; } fastcgi_param SCRIPT_NAME $fastcgi_script_name; location = / fastcgi_index index.php { ; include fastcgi_ pass unix:/run/php/php7.3-fpm.sock; # PHP socket params; } location ~* \.(jpg|jpeg|gif|png|css|js|ico|xml)$ { expires 5d; } ssl_certificate fastcgi_paramSCRIPT_FILENAME $document_root/index.php; # Blesta /index.php /etc/letsencrypt/live/domain.tld/fullchain.pem; fastcgi_param SCRIPT_NAME $fastcgi_script_name ssl_certificate_key /etc/letsencrypt/live/domain.tld/privkey.pem; ssl_dhparam /etc/letsencrypt/dhparam.pem; includefastcgi_params ssl_buffer_size 8k; ssl_protocols } TLSv1.2 TLSv1.3; location ~ /\. { ssl_ciphers ECDH+AESGCM:ECDH+AES256:ECDH+AES128:DH+3DES:!ADH:!AECDH:!MD5; ssl_prefer_server_ciphers on; ssl_ecdh_curve secp384r1; log ssl_ not session_ found tickets off; ssl_stapling on; ssl_stapling_verify on; resolver 8.8.8.8; return 404; } add_header Strict-Transport-Security 'max-age=31536000; includeSubDomains; preload'; if ($host location ~* \.(php|pdt|txt)$ { log_not_found off; return 404; } } != domain.tld) { return 307 https://domain.tld$request_uri; } }

      
      

  • Next, update /core/ServiceProviders/MinphpBridge.php and make the following change:

    Code Block
    // $htaccess = file_exists($rootWebDir . '.htaccess'); $htaccess = true;

    
    

  Litespeed

  • Installation of Blesta times out.
    • Increase the timeout by taking the following action:  Navigate to WebAdmin CP > Configuration > Server > Tuning, and change Connection Timeout to 300.

  Lighttpd

  • This sample configuration is community provided:

    • Edit lighttpd.conf

      Code Block
      server.modules += ( "mod_redirect") server.modules += ( "mod_rewrite") #if blesta install is http://<mydomain>.<mytld>/clients/ url.rewrite-if-not-file = ( "^/clients/(.*)$" => "/clients/index.php" ) url.redirect = ( "^(.*)/clients/install.php$" => "$1/clients/install/" )

    Next, update /core/ServiceProviders/MinphpBridge.php and make the following change:

    Code Block// $htaccess = file_exists($rootWebDir . '.htaccess'); $htaccess = true;

    • 
      

  Cron Issues

  • Cron does not seem to complete normally and Settings > Company > Automation shows some hung tasks.
    • Try disabling your cron job, and running the cron manually under Settings > System > Automation. If it runs correctly, you may have a memory issue in your CLI environment with Zend Memory Manager. Some users have reported that appending export USE_ZEND_ALLOC=0; to the beginning of their cron job resolved the issue. When using this method, your cron may look something like this: export USE_ZEND_ALLOC=0; /usr/bin/php /home/user/public_html/blesta/index.php cron

  ...