Created interactive DDEV setup

[webhdx]

Ibexa DXP 4.6 is compatible with DDEV but we don't have any ready to use configuration. There are more like some guidelines how to set everything up available in our doc. It isn't ideal because with every new project you have to start from scratch. To resolve this issue, I've created DDEV configuration which comes with a nice command line utility to configure every detail of your local setup.

Meet DDEV Interactive Installation Tool:

It was inspired by @reithor's https://github.com/reithor/ibexa-ddev-toolkit but takes a different approach and makes it much more user friendly.

Available services

• PHP: 8.3, 8.2, 8.1
• Node: 18, 20, 21, 22
• HTTP Servers: nginx-fpm, apache-fpm
• HTTP Cache: Varnish, Symfony's built in HTTP cache
• Database:
  • MariaDB: 10.11, 10.3
  • MySQL: 8
  • Postgres: 16, 15, 14, 13, 12, 11, 10
• App cache: Redis, Memcached, Filesystem
• Search engine: Elasticsearch, Solr, Legacy

Additional features

• Install Symfony Profiler
• Configure app environment: prod or dev
• Install Ibexa Cloud configuration
• Prompt for product edition when installing from ibexa/website-skeleton
• Install sample data using ibexa/test-fixtures (only for Ibexa employees)

How to use

Until it's merged and released, you can only use it via ibexa/website-skeleton which only supports 4.6.x-dev version.

There is an issue with asking for Composer credentials currently and you have to link your auth.json to ddev containers:

mkdir -p ~/.ddev/homeadditions/.composer && ln -s ~/.composer/auth.json ~/.ddev/homeadditions/.composer/auth.json

Our current installation method uses composer create-project but since we don't want to use Composer on host machine, installation has to be a little bit different:

git clone -b ddev [email protected]:ibexa/website-skeleton.git ibexa-dxp && cd ibexa-dxp && ddev start

It'll install into ibexa-dxp directory, feel free to use whatever you want. This name will be used as the project's name and in the URL pointing to that instance.

If you want to see debug information you have to set VERBOSE_INSTALL variable on both host machine and inside project constainers:

git clone -b ddev [email protected]:ibexa/website-skeleton.git ibexa-dxp && cd ibexa-dxp
ddev config --web-environment VERBOSE_INSTALL=true
export VERBOSE_INSTALL=true; ddev start

How it all works

Entire scripting is done in Bash and uses DDEV's build hooks to display the wizard when starting new project. My intention was to make it as user friendly as possible, which includes hiding all technical logs from the user. Some people are going to hate that so I made it possible to use VERBOSE_INSTALL=true variable to change the behavior.

There are multiple installation phases hooked to post-start:

ibexa-configurator

This is the wizard which lets you choose which services and versions to install. After confirming your setup it writes .ddev/.ibexa-instance-settings file with all settings as variables which makes it easy to source by next scripts in the pipeline.
The thing that makes the wizard nice and interactive is gum (https://github.com/charmbracelet/gum). It runs in web container therefore it doesn't add any requirements to the host system.

ibexa-setup

This script reconfigures ddev project based on selected configuration. It'll install required ddev addons, set .env.local variables to configure Ibexa DXP instance.

ibexa-installer

This is the last step in the pipeline and after ddev project is set up with required configuration and addons, ibexa-installer will attempt to install composer requirements, add sample data, install Ibexa Cloud configs and do final provisioning.
When everything is done, user is greeted details of their setup and instructions what to do next.

Requirements

• Container runtime like Docker, Colima or OrbStack installed on host system
• DDEV installed in your system: https://ddev.readthedocs.io/en/stable/users/install/ddev-installation/
• sed, awk available in terminal

Mac OS will use Mutagen for synchronizing files. It can work very fast but requires fast SSD and some RAM. OrbStack has the best performance on Mac OS but it's not free.

TODO

⚠️ It's still experimental and although most things are already working, there are outstanding issues I want to resolve before it goes public:

• Fix file permission issues on Solr, it's currently unusable
• Update banner with new logo design
• Update configuration overview table, some details are missing at the moment
• Make sure it also works for alpha/beta/RC releases
• Make sure it works with ibexa/{oss, headless, experience, commerce}-skeleton and correctly detects installation type and version
• Warn if updates.ibexa.co is inaccessible and stop the installation gracefully
• Check if number of restarts can be reduced in ibexa-setup.sh for time optimization
• ibexa/test-fixtures cannot be installed from stable release
• Use ibexa ddev addons (Solr, Varnish)
• Fix documentation to show how to run commands on ddev (i.e. OAuth 2 Server page)
• Move to ibexa/ddev package and create git submodule in ibexa/website-skeleton
• Use our virtual host configuration (https://github.com/ibexa/docker), currently uses ddev's standard httpd config [1]
• Allow selecting Redis, Memcache, Solr, Elasticsearch and Varnish versions. It uses whatever is shipped with the latest addons [2]

1. I've looked into it and some of our rewrite rules collide with additional DDEV routes (/phpstatus and /healthcheck). My first approach was copying vhost file from ibexa/post-install and applying modifications with sed but this is very error prone. We could just keep already modified copy as a part of ddev config but for the time being it feels like stock configuration is just okay. Our vhost mostly adds some security measures for production environments, it's not really relevant for local use.
2. DDEV does not support it out of the box. The only option is to use different addons providing different versions (like https://github.com/ddev/ddev-redis-7 and https://github.com/ddev/ddev-redis) but it usually means there are major differences in how these addons work.

Ideas

• Introduce external file storage for testing Flysystem

[adriendupuis]

I love it!

Could we choose the DXP version as well?
Even 3.3.* should work.

[webhdx]

@adriendupuis You won't be able to choose version using interactive menu. The idea is that you git clone skeleton that matches version you want to install i.e. git clone [email protected]:ibexa/oss-skeleton.git -b v4.6.5. This obviously won't work with older releases, only with those we start tagging after this PR is merged. If you really need some older version to be installed, you can also copy .ddev directory from website-skeleton. I've done it today for 3.3.36 and 3.3.37 to test a customer request.

[adriendupuis]

@webhdx OK. I didn't understand that it wasn't autonomous but come as a .ddev folder within an DXP edition skeleton.

[mnocon]

Assuming we want to share it with Partners eventually (I think we should, it would be great for them):

Storing the files directly in website-skeleton means that they cannot be easily updated (they are directly in the project, so we cannot easily modify them and distribute the updates).

What do you think about moving this configuration to a separate package (ibexa/ddev) and copying the files from the package to the project using recipes? Then it would be easier to update for partners running recipes:install, impoving the DX for them.

Just an idea, we might come back to this when we decide to share this.

[webhdx]

We can't use recipes because that would indicate you have to composer install the package on the host first. I was discussing it with @reithor and we are leaning more towards a git submodule. But it's a valid point that we should move it to a separate package.

[mnocon]

You're right 😞 I'd just like to make sure we have something that can be updated without jumping through too many hoops