• Documentation >
• Getting started >
• Install with DDEV

Install with DDEV

This guide provides a step-by-step walkthrough of installing Ibexa DXP by using DDEV. DDEV is an open-source tool that simplifies the process of setting up local PHP development environments.

Requirements

Before you start the installation, ensure that you have the following software installed:

• Docker
• DDEV

Installation

1. Create a DDEV project directory

Start by creating a new directory for your DDEV project by using the following command, where <my-ddev-project> stands for your desired directory name:

mkdir my-ddev-project && cd my-ddev-project

2. Configure DDEV

Configure PHP version and document root

Next, configure your DDEV environment with the following command:

ddev config --project-type=php --php-version 8.3 --nodejs-version 20 --docroot=public

This command sets the project type to PHP, the PHP version to 8.3, the document root to public directory, and creates the document root if it doesn't exist.

Use another database type (optional)

By default, DDEV uses MariaDB.

To use PostgreSQL instead, run the following command:

ddev config --database=postgres:14

To use MySQL instead, run the following command:

ddev config --database=mysql:8.0

You can also use other versions of MariaDB, Mysql or PostgreSQL. See DDEV database types documentation for available version ranges.

Configure database connection

Now, configure the database connection for your Ibexa DXP project. Depending on your database of choice (MySQL or PostgreSQL), use the appropriate command below.

Note

Those commands set a DATABASE_URL environment variable inside the container which overrides the variable from .env.

To use .env.local file instead of server-level environment variables, see Using dotenv.

MariaDB / MySQLPostgreSQL

ddev config --web-environment-add DATABASE_URL=mysql://db:db@db:3306/db

To ensure consistent character set when performing operations both in Symfony context and with the ddev mysql client add the following database server configuration.

Create the file .ddev/mysql/utf8mb4.cnf with the following content:

[mysqld]
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_520_ci

ddev config --web-environment-add DATABASE_URL=postgresql://db:db@db:5432/db

Enable Mutagen (optional)

If you're using macOS or Windows, you might want to enable Mutagen to improve performance. You can do this by running the following command:

ddev config --performance-mode=mutagen

See DDEV performance documentation for more.

Change port mapping (optional)

By default, DDEV uses ports 80 and 443. You can set different ports with a command like the following:

ddev config --router-http-port=8080 --router-https-port=8443

3. Start DDEV

Proceed by starting your DDEV environment with the following command:

ddev start

Tip

If you forgot some part of configuration, you can set it by using ddev config later, but afterwards you have to restart DDEV with ddev restart.

4. Composer authentication

Next, you need to set up authentication tokens by modifying the Composer configuration. You must run the following command after executing ddev start, because the command runs inside the container. Replace <installation-key> and <token-password> with your actual installation key and token password.

ddev composer config --global http-basic.updates.ibexa.co <installation-key> <token-password>

This authentication doesn't persist if the project is restarted (by ddev restart or ddev composer create). You can back up the authentication file (auth.json) by using the following command:

ddev exec "mkdir -p .ddev/homeadditions/.composer; cp ~/.composer/auth.json .ddev/homeadditions/.composer"

If you want to reuse an existing auth.json file, see Using auth.json.

5. Create project

Once DDEV is running, use Composer to create a new Ibexa DXP project. Remember to replace <edition> and <version> with your desired edition and version.

ddev composer create ibexa/<edition>-skeleton:<version>

Tip

Consider adding the Symfony Debug bundle which fixes memory outage when dumping objects with circular references. ddev composer require --dev symfony/debug-bundle

6. Install the platform and its database

Once you've made this change, you can proceed to install Ibexa DXP.

ddev php bin/console ibexa:install
ddev php bin/console ibexa:graphql:generate-schema

7. Open browser

Once the above steps are completed, open the Ibexa DXP's webpage by running the ddev launch command.

Tip

You can also see the project URL in the ddev start output.

8. Start using Ibexa DXP

You can now start using Ibexa DXP and implement your own website on the platform.

You can edit the configuration and code in the DDEV project directory. You can use commands listed in the documentation by prefixing them with ddev exec or by opening a terminal inside the container by using ddev ssh. For example, if a guideline invites you to run php bin/console cache:clear, you can do it in the DDEV container in one of the following ways:

• run ddev php bin/console cache:clear
• enter ddev ssh and run php bin/console cache:clear after the new prompt

Other options for configuration

DDEV offers several ways to get the same result, offering different levels of flexibility or adaptability to your development environment.

Tip

Learn more about the DDEV commands:

• run ddev --help to list all commands
• run ddev help <command> to get usage details about a specific command

Learn more about DDEV configuration from ddev config command documentation and advanced configuration files documentation.

Using auth.json

An auth.json file can be used for one project, or globally for all projects, with the DDEV homeaddition feature.

For example, you can copy an auth.json file to a DDEV project: cp <path-to-an>/auth.json .ddev/homeadditions/.composer

Alternatively, the Composer global auth.json can be the DDEV global auth.json with the help of a symbolic link: mkdir -p ~/.ddev/homeadditions/.composer && ln -s ~/.composer/auth.json ~/.ddev/homeadditions/.composer/auth.json

If the DDEV project has already been started, you need to run ddev restart.

The use of an auth.json file replaces step 4. Composer authentication.

Using Dotenv

Instead of using environment variables inside the container, a .env.local file can be added to the project.

The following example shows the use of .env.local with database configuration:

• Skip step 2. Configure DDEV / Configure database connection.
• Modify step 5. Create Ibexa DXP project to insert the database setting:

  ddev composer create ibexa/commerce-skeleton --no-install;
  echo "DATABASE_URL=mysql://db:db@db:3306/db" >> .env.local;
  ddev composer install;
  

Precedence

For the same variable, its server level environment value overrides its application level .env value. To switch a variable from ddev config --web-environment-add command to .env.local file, you have to do either of the following:

• remove it from under the web_environment: key in .ddev/config.yaml file then restart the project
• rebuild the project from scratch

Nginx Server Blocks

Even if Ibexa DXP works with the default Nginx configuration that comes with DDEV, it's recommended to use a dedicated one.

Copy the Server Blocks template as a new Nginx configuration:

cp vendor/ibexa/post-install/resources/templates/nginx/vhost.template .ddev/nginx_full/ibexa.conf
cp -r vendor/ibexa/post-install/resources/templates/nginx/ibexa_params.d .ddev/nginx_full/

Then, replace the placeholders with the appropriate values in .ddev/nginx_full/ibexa.conf:

Placeholder	Value
%PORT%	80
%HOST_LIST%	*.ddev.site
%BASEDIR%	/var/www/html
%BODY_SIZE_LIMIT_M%	0
%TIMEOUT_S%	90s
%FASTCGI_PASS%	unix:/var/run/php-fpm.sock
%BINARY_DATA_HANDLER%	empty string

Because of path resolution inside DDEV's Nginx, you must replace one more thing: ibexa_params.d with sites-enabled/ibexa_params.d.

You can, for example, do it with sed:

sed -i 's/%PORT%/80/' .ddev/nginx_full/ibexa.conf;
sed -i 's/%HOST_LIST%/*.ddev.site/' .ddev/nginx_full/ibexa.conf;
sed -i 's/%BASEDIR%/\/var\/www\/html/' .ddev/nginx_full/ibexa.conf;
sed -i 's/%BODY_SIZE_LIMIT_M%/0/' .ddev/nginx_full/ibexa.conf;
sed -i 's/%TIMEOUT_S%/90s/' .ddev/nginx_full/ibexa.conf;
sed -i 's/%FASTCGI_PASS%/unix:\/var\/run\/php-fpm.sock/' .ddev/nginx_full/ibexa.conf;
sed -i 's/%BINARY_DATA_HANDLER%//' .ddev/nginx_full/ibexa.conf;
sed -i 's/ibexa_params.d/sites-enabled\/ibexa_params.d/' .ddev/nginx_full/ibexa.conf;

If you want to use HTTPS, you must add the following rule to avoid mixed content (HTTPS pages linking to HTTP resources): fastcgi_param HTTPS $fcgi_https;

For example, you can append it to Ibexa's FastCGI config:

echo 'fastcgi_param HTTPS $fcgi_https;' >> .ddev/nginx_full/ibexa_params.d/ibexa_fastcgi_params

Switch to Apache and its virtual host

To use Apache instead of the default Nginx, run the following command:

ddev config --webserver-type=apache-fpm

Ibexa DXP can't run on Apache without a dedicated virtual host.

To set the Apache virtual host, override .ddev/apache/apache-site.conf with Ibexa DXP's config. You can do it manually or by using a script.

Manual procedure

Copy the virtual host template as the new Apache configuration:

cp vendor/ibexa/post-install/resources/templates/apache2/vhost.template .ddev/apache/apache-site.conf

Then, replace the placeholders with the appropriate values in .ddev/apache/apache-site.conf:

Placeholder	Value
%IP_ADDRESS%	*
%PORT%	80
%HOST_NAME%	my-ddev-project.ddev.site
%HOST_ALIAS%	*.ddev.site
%BASEDIR%	/var/www/html
%BODY_SIZE_LIMIT%	0
%TIMEOUT%	0
%FASTCGI_PASS%	unix:/var/run/php-fpm.sock

You can, for example, do it with sed:

sed -i 's/%IP_ADDRESS%/*/' .ddev/apache/apache-site.conf
sed -i 's/%PORT%/80/' .ddev/apache/apache-site.conf
sed -i 's/%BASEDIR%/\/var\/www\/html/' .ddev/apache/apache-site.conf
sed -i 's/%BODY_SIZE_LIMIT%/0/' .ddev/apache/apache-site.conf
sed -i 's/%TIMEOUT%/0/' .ddev/apache/apache-site.conf
sed -i 's/%FASTCGI_PASS%/unix:\/var\/run\/php-fpm.sock/' .ddev/apache/apache-site.conf

If you want to use HTTPS, you must add the following rule to avoid mixed content (HTTPS pages linking to HTTP resources): SetEnvIf X-Forwarded-Proto "https" HTTPS=on

You can, for example, do it with sed:

sed -i 's/DirectoryIndex index.php/DirectoryIndex index.php\n\n    SetEnvIf X-Forwarded-Proto "https" HTTPS=on/' .ddev/apache/apache-site.conf

Finally, restart the project:

ddev restart

Scripted procedure

Generate the virtual host with vhost.sh:

curl -O https://raw.githubusercontent.com/ibexa/docker/main/scripts/vhost.sh
bash vhost.sh --template-file=vendor/ibexa/post-install/resources/templates/apache2/vhost.template \
  --ip='*' \
  --host-name='my-ddev-project.ddev.site' \
  --host-alias='*.ddev.site' \
  --basedir='/var/www/html' \
  --sf-env=dev \
  > .ddev/apache/apache-site.conf
sed -i 's/php5-fpm.sock/php-fpm.sock/' .ddev/apache/apache-site.conf
sed -i 's/DirectoryIndex index.php/DirectoryIndex index.php\n    SetEnvIf X-Forwarded-Proto "https" HTTPS=on/' .ddev/apache/apache-site.conf
rm vhost.sh

Then, restart the project:

ddev restart

Run an already existing project

To run an existing project, you need to:

1. Configure the DDEV project.
2. Start the DDEV project.
3. Add Composer authentication.
4. Install dependencies packages with Composer.
5. Populate the contents, which could mean:
   • getting a clean database with ddev php bin/console ibexa:install and adding some data with Ibexa data migration, or
   • injecting a dump with ddev import-db and copying related binary files into public/var.

The following examples run an already version-controlled project and have the right content structure (but no content):

# Clone the version-controlled project and enter its local directory
git clone <repository> my-ddev-project && cd my-ddev-project
# Exclude the whole `.ddev/` directory from version control (some DDEV config could have been committed and shared, see notice below)
.ddev/ >> .gitignore
# Configure the DDEV project then start it
ddev config --project-type=php --php-version 8.1 \
  --docroot=public \
  --web-environment-add DATABASE_URL=mysql://db:db@db:3306/db \
  --http-port=8080 --https-port=8443
ddev start
# Configure Composer authentication
ddev composer config --global http-basic.updates.ibexa.co <installation-key> <token-password>
# Install the dependencies packages
ddev composer install
# Populate the database with a clean install
ddev php bin/console ibexa:install
# Add some content types using a migration file (previously created on another installation) and update the GraphQL schema
ddev php bin/console ibexa:migrations:migrate --file=project_content_types.yaml
ddev php bin/console ibexa:graphql:generate-schema
# Open the project in the default browser which should display the default SiteAccess frontpage
ddev launch

Notice that the example adds the whole .ddev/ directory to .gitignore, but you can also version parts of it. Some DDEV configs can be shared among developers. For example, a common .ddev/config.yaml can be committed for everyone and locally extended or overridden.

Compared to running a clean install like described in Installation steps, you can proceed as follows:

• In 1. Create a DDEV project directory, you can use an existing directory that contains an Ibexa DXP project instead of creating an empty directory.
• In 5. Create Ibexa DXP project, use only ddev composer install instead of ddev composer create.
• Populate the database with Ibexa data migration or ddev import-db.

Hostnames and domains

If the local project needs to answer to real production domains (for example, to use the existing hostname to SiteAccess or hostname element to SiteAccess mappings), you can use additional hostnames.

Caution

As this feature modifies domain resolution, the real website may be unreachable until the hosts file is manually cleaned.

Cluster or Ibexa Cloud

You can use DDEV to locally simulate a production cluster.

• See Clustering with DDEV to add Elasticsearch, Solr, Redis, or Memcached to your DDEV installation.
• See DDEV and Ibexa Cloud to locally run an Ibexa DXP project by using DDEV.

Stop or remove the project

If you need to stop the project to start it again later, use ddev stop. Then, use ddev start to run the project in the same state.

If you want to fully remove the project:

• delete the DDEV elements without backup: ddev delete --omit-snapshot && rm -rf ./ddev
• remove the project folder: cd .. && rm -r my-ddev-project

If additional hostnames have been used, you must clean the hosts file.

To learn more about removing all projects at once or DDEV itself, see Uninstalling DDEV.