Install Ibexa DXP¶
Installation for production is only supported on Linux.
To install Ibexa DXP for development on macOS or Windows, see the installation guide for macOS and Windows.
Installing Ibexa OSS
This installation guide details the steps to install Ibexa DXP for users who have a subscription agreement with Ibexa.
If you want to install Ibexa OSS, you do not need authentication tokens or an account on updates.ibexa.co,
but must adapt the steps shown here to the product edition and the
Prepare work environment¶
To install Ibexa DXP you need a stack with your operating system, MySQL and PHP.
You can install it by following your favorite tutorial, for example: Install LAMP stack on Ubuntu.
- Node.js and Yarn for asset management.
gitfor version control.
- to use search in the shop front end, you must install a search engine.
For production you also need Apache or nginx as the HTTP server (Apache is used as an example below).
Before getting started, make sure you review other requirements to see the systems we support and use for testing.
Install a recent stable version of Composer, the PHP command line dependency manager. Use the package manager for your Linux distribution. For example, on Ubuntu:
To verify that you have the most recent stable version of Composer, you can run:
Install Composer locally
If you want to install Composer inside your project root directory only, run the following command in the terminal:
If you do so, you must replace
php -d memory_limit=-1 composer.phar in all commands below.
Install Ibexa DXP¶
Set up authentication tokens¶
Ibexa DXP subscribers have access to commercial packages at updates.ibexa.co. The site is password-protected. You must set up authentication tokens to access the site.
Log in to your service portal on support.ibexa.co, go to your Service Portal, and look for the following on the Maintenance and Support agreement details screen:
- Select Create token (this requires the Portal administrator access level).
- Fill in a label describing the use of the token. This will allow you to revoke access later.
- Save the password, you will not get access to it again!
Save the authentication token in
auth.json to avoid re-typing it
Composer will ask whether you want to save the token every time you perform an update.
If you prefer, you can decline and create an
auth.json file globally
COMPOSER_HOME directory for machine-wide use:
To store your credentials per project, add the credentials to the
You then need to add the contents of this variable to
Different tokens for different projects on a single host
If you configure several projects on one machine, make sure that
you set different tokens for each of the projects in their respective
After this, when running Composer to get updates, you will be asked for a username and password. Use:
- as username - your Installation key found on the Maintenance and Support agreement details page in the service portal
- as password - the token password you retrieved in step 3 above.
Authentication token validation delay
You can encounter some delay between creating the token and being able to use it in Composer. It might take up to 15 minutes.
Support agreement expiry
If your Support agreement expires, your authentication token(s) will no longer work. They will become active again if the agreement is renewed, but this process may take up to 24 hours. (If the agreement is renewed before the expiry date, there will be no disruption of service.)
To use Composer to instantly create a project in the current folder with all the dependencies, run the following command:
Using PHP 8
If you are using PHP 8, use a different set of commands:
If you added credentials to the
at this point add this variable to
auth.json (for example, by running
echo $COMPOSER_AUTH > auth.json).
You can set different version constraints:
specific tag (
3.3.2), version range (
~3.3.2), stability (
^[email protected]), etc.:
If you are deploying your installation on Platform.sh, run the following command:
This command provides the necessary configuration for using Platform.sh.
Add project to version control¶
It is recommended to add your project to version control.
First, create a
.gitignore file based on the
.gitignore.dist provided in the project.
Then, initiate your project repository:
Change installation parameters¶
At this point configure your database via the
DATABASE_URL in the
depending of the database you are using:
Encoding database password
The password entered in
DATABASE_URL must either be URL encoded, or not contain any special characters that would require URL encoding.
For more information, see Encoding database password.
Add entropy to improve cryptographic randomness¶
Choose a secret
and provide it in the
APP_SECRET parameter in
It should be a random string, made up of at least 32 characters, numbers, and symbols.
This is used by Symfony when generating CSRF tokens,
and for creating signed URIs when using ESI (Edge Side Includes).
The app secret is crucial to the security of your installation. Be careful about how you generate it, and how you store it. Here's one way to generate a 64 characters long, secure random string as your secret, from command line:
Do not commit the secret to version control systems, or share it with anyone who does not strictly need it. If you have any suspicion that the secret may have been exposed, replace it with a new one. The same goes for other secrets, like database password, Varnish invalidate token, JWT passphrase, etc.
After changing the app secret, make sure that you clear the application cache and log out all the users. For more information, see Symfony documentation.
It is recommended to store the database credentials in your
.env.local file and not commit it to the Version Control System.
DATABASE_VERSION you can also configure the database server version (for a MariaDB database, prefix the value with
If you want an installation with PostgreSQL instead of MySQL, refer to Using PostgreSQL.
Install and configure a search engine¶
You may choose to replace the default search engine with either Solr or Elasticsearch.
Shop front end requirement
Search in the shop front end requires that you have either Solr or Elasticsearch as a search engine.
Follow How to set up Solr search engine to install Solr.
Do the following steps to enable Elasticsearch:
- Download and install Elasticsearch
- Verify that the Elasticsearch instance is up
- Set the default search engine
- Configure the search engine
- Push the templates
Configure the following parameter in the
Create a database¶
Install Ibexa DXP and create a database with:
Before executing the command make sure that the database user has sufficient permissions.
If Composer asks for your token, you must log in to your GitHub account and generate a new token (edit your profile and go to Developer settings > Personal access tokens > Generate new token with default settings). This operation is performed only once, when you install Ibexa DXP for the first time.
Run post-installation script¶
Run the post-installation script with the following command:
Use PHPs built-in server¶
For development you can use the built-in PHP server.
Your PHP web server will be accessible at
You can also use Symfony CLI:
Prepare installation for production¶
To use Ibexa DXP with an HTTP server, you need to set up directory permissions and prepare a virtual host.
Set up permissions¶
For development needs, the web user can be made the owner of all your files (for example with the
www-data web user):
public/var must be writable by CLI and the web server user.
Future files and directories created by these two users will need to inherit those permissions.
For security reasons, in production, the web server cannot have write access to other directories than
Skip the step above and follow the link below for production needs instead.
You must also make sure that the web server cannot interpret the files in the
var directory through PHP.
To do so, follow the instructions on setting up a virtual host below.
To set up permissions for production, it is recommended to use an ACL (Access Control List). See Setting up or Fixing File Permissions in Symfony documentation for information on how to do it on different systems.
Set up virtual host¶
Prepare a virtual host configuration for your site.
You can copy the example vhost file
/etc/apache2/sites-available as a
.conf file and modify it to fit your project.
/<your installation directory>/public as the
Directory, or ensure
BASEDIR is set in the environment.
Uncomment the line that starts with
#if [APP_ENV] and set the value to
dev, depending on the environment that you are configuring,
APP_ENV is set in the environment.
When the virtual host file is ready, enable the virtual host and disable the default:
Finally, restart the Apache server. The command may vary depending on your Linux distribution. For example, on Ubuntu use:
You can use this example vhost file
and modify it to fit your project. You will also need the
ibexa_params.d files that should reside in a subdirectory below where the main file is,
as is shown here.
/<your installation directory>/public as the
root, or ensure
BASEDIR is set in the environment.
APP_ENV is set to
dev in the environment, depending on the environment that you are configuring, and uncomment the line that starts with
When the virtual host file is ready, enable the virtual host and disable the default. Finally, restart the nginx server. The command may vary depending on your Linux distribution.
Open your project in the browser by visiting the domain address, for example
You should see the welcome page.
See the Security checklist for a list of security-related issues you should take care of before going live with a project.
Enable Date-based Publisher¶
To enable delayed publishing of Content using the Date-based Publisher, you must set up cron to run the
bin/console ibexa:scheduled:run command periodically.
For example, to check for publishing every minute, add the following script:
echo '* * * * * cd [path-to-ibexa-dxp]; php bin/console ibexa:cron:run --quiet --env=prod' > ezp_cron.txt
For 5-minute intervals:
echo '*/5 * * * * cd [path-to-ibexa-dxp]; php bin/console ibexa:cron:run --quiet --env=prod' > ezp_cron.txt
Next, append the new cron to user's crontab without destroying existing crons.
Assuming the web server user data is
crontab -u www-data -l|cat - ezp_cron.txt | crontab -u www-data -
Finally, remove the temporary file:
Enable the Link manager¶
To make use of the Link Manager, you must set up cron.
JMS payment secret ¶
To provide the
JMS_PAYMENT_SECRET secret for the Ibexa Commerce payment system, run
and use the generated secret.
If you want to host your application on Ibexa Cloud, follow the Install on Ibexa Cloud procedure.