Explicit Craft CMS support

[JPBarringer]

Is your feature request related to a problem? Please describe.
I manage a lot of Craft CMS (and Bedrock/WP) sites. It would be nice if DDEV had a Craft recipe/support built in.
(craftcms.com)

Describe the solution you'd like
Built-in detection of and support for Craft sites. It's basically just a composer-managed LAMP app but it would be nice if existing .env files could be parsed (and new environment variables set or .env generated) for setup.

Describe alternatives you've considered
Building it myself. -- not super familiar with the process here or with golang, however. (Or with setting environment variables in the container.)

Craft also has their own local, containerized runtime called Nitro. But I'd prefer to standardize around a single local dev setup.

Additional context
Installation instructions: https://craftcms.com/docs/3.x/installation.html
Configuration: https://craftcms.com/docs/3.x/config/
Craft has a full-featured CLI: https://craftcms.com/docs/3.x/console-commands.html

It occurs to me that handling .env files and/or setting env variables in the container might be useful for Bedrock (WP) support as well – no need to modify wp-config in that case.

[rfay]

Absolutely awesome! What usually goes with explicit CMS support is a specific nginx config, auto-detection, and settings creation, along with optional nonstandard defaults, like db or php version and automated testing . If you can lay those out it will help this move forward. A PR would be lovely... That's how we got Magento and Magento 2.

[rfay]

Another interim step would be to just do a quick start in the docs.

[JPBarringer]

Awesome!

To start:

• An example nginx conf can be found here https://github.com/nystudio107/nginx-craft/blob/master/sites-available/basic_localdev.com.conf (This is the one that the Craft devs point to)
• Requirements are here: https://craftcms.com/docs/3.x/requirements.html Ideally:
  • PHP 7.4+ (Will require 8.0 for v4)
  • Postgres 10+
  • Composer 2+
  • (Note, these are all for Craft 3)
• Autodetection: Not sure the best way, but probably the most highly conserved element will be the entry in composer.json: "craftcms/cms": "^3.0.0", (version may be higher) or else the presence of /vendor/craftcms/.
• Web root is usually /web but can be reconfigured by setting CRAFT_BASE_PATH (in /index.php)
• Testing: I haven't really done much with this in local dev but the docs are here: https://craftcms.com/docs/3.x/testing/. There may be other Craft users who can do more with this.
• Here is one of the craft demo sites that may be useful for manual testing: https://github.com/craftcms/happy-lager

Some of this is outside my comfort zone but I'm happy to learn and to put time in on this if it helps. Also totally happy to stand back and let the expert(s) figure it out if that's easier.

[rfay]

A great start!

[juban]

Hi @rfay @JPBarringer

I will gladly help here, if i can.

In my experience however, there is not much to do (nothing in fact) to support Craft CMS in ddev out of the box.
Just create a standard ddev config (php project type) and specify the web-root (web by default) and you will be up and running. That's all. Additional packages could be be necessary for specific plugins from time to time, but that's a per project concern.
The only additional requirement is that you should create an additional FQDNS to add a .test local domain in order to make Craft allow to run locally without a licence warning.
Beside setting up an according .env file to connect to the ddev database which is pretty standard, I can't think of very specific thing related to Craft in ddev.

@JPBarringer could you specify what configuration did you found missing for Craft using ddev?

[mikesnoeren]

I have to agree with @juban, I'm working with Craft daily and have to say the support for Craft in DDEV is phenomenal. Haven't experienced any issues running Craft 2, 3 or 4 with the default PHP project type. Everything is set up as it should be set up and everything works flawlessly (and really fast, too!)

If you want to see (or use) an example of a Craft 4 + DDEV project, I've set up a scaffolding project you might want to check out.

[jamesmacwhite]

With the announcement of Craft CMS retiring their docker based environment Nitro, I'm sure the Craft CMS dev team will be interested in providing smooth Craft CMS support. DDEV has even been touted as a replacement for those currently running Nitro (me included) to move to DDEV.

Although it does look like the plain PHP project option seems to work well without specifics.

[rfay]

Reasons for explicit CraftCMS support:

• Explicitly craft custom commands like ddev craft
• Explicit nginx config
• Settings management

[juban]

Hi @rfay

• craft command is present now in the latest ddev version thanks to Ben Crocker. Agreed on that one, it was not mandatory, but nice to have.
• What do you mean by "Explicit Ngnix config"? As far as I know, there's no specific configuration required for Craft with DDEV which will work out of the box.
• "Settings management": could you elaborate what settings are you referring to?

I've been using DDEV with Craft (v2, v3 and v4) for almost 4 years now without any issues and no specific DDEV setup needed.

The only thing I do is adding image processing libs to ease the use of certain Craft plugins like ImageOptimize (by adding jpegoptim, optipng, gifsicle, webp to webimage_extra_packages).

Don't get me wrong, I'm not saying there's no room for improvements in DDEV documentation regarding Craft, in the QuickStart section for instance, but I'm wondering if we really need these specific extra configurations (maybe a bit overkill IMO).

[rfay]

• The ddev craft command now shows for everybody who uses the php project type, which increases the complexity level and isn't necessary.
• I don't know that craft will need any custom nginx, and none has been requested. Most CMSs eventually need something.
• Settings management: Craft has specific requirements for connecting to the database, for example. I know that people using craft are used to setting this up themselves, but when I tried it out it was unfamiliar to me. On supported CMSs, DDEV automatically sets up the database location and credentials.
• upload_dir should be set for Craft.

In doing support for people I've run across a couple of situations where DDEV could make craft usage easier for folks that don't already know everything about craft, and I'd like to capture those so will continue to update above.

[juban]

OK, makes sense. I guess we could come up with a specific Craft CMS support which could add the craft command and add a default .env file with a db connections preset. You convinced me :)

That said, all in all, Craft is a pretty easy living CMS for developers and does not require much specific setup (if not none), and I can confirm that the default Ngnix configuration just work just fine as is.

[mikesnoeren]

The default upload_dir setting could be configured in a craft specific project type as ddevs default doesn't seem to be working for me? It should always be <docroot>/upload

How I know it doesn't work?

I haven't set the upload_dir setting and all my uploads are getting synced into mutagen which slows down the project significantly. I do however have a custom docroot (public_html), could that be the cause?

[rfay]

Ah yes, upload_dir. Added that to the list above. DDEV has no idea where upload_dir is by default in a craft project that's set to project type php. Added to the list. And for other project types, DDEV would have figured it out even with a custom docroot.

[juban]

Ah yes, upload_dir. Added that to the list above. DDEV has no idea where upload_dir is by default in a craft project that's set to project type php. Added to the list. And for other project types, DDEV would have figured it out even with a custom docroot.

Well in fact, there is none as Craft do not assume anything about your projet needs. It's up to developer or admin to choose the "upload_dir" (somewhere within the web folder, but not necessarily). In fact, you can even define multiple folders.

[rfay]

How is the upload dir configured? In most CMSs, configuration like this is provided somewhere in code.

Can the database configuration be provided in code, like Drupal does settings.php or WordPress does wp-config.php?

[juban]

In Craft, you define Volumes and Assets elements using the project configuration.
Using a fresh Craft projet, there are none defined, it's a blank page where developer have to define everything based on the project needs. That's why there is not much we can define on DDEV side without an opinionated approch, which is not really in the Craft spirit.

[juban]

Regarding database configuration, as said before, the best place would be the .env file to define CRAFT_DB_DRIVER, CRAFT_DB_SERVER, CRAFT_DB_USER and so on.
The config/db.php file is where database connection is defined. That said, I'm not a big fan of the Wordpress approach where DDEV overrides the wp-config file in order to connect to the according DDEV database. The .env approach seems a better fit for Craft IMO.

[rfay]

So a Craft project type could create a .env file like is done for Laravel...

[rfay]

Could you please provide links to the docs about upload_dir and db config?

[juban]

So a Craft project type could create a .env file like is done for Laravel...

Exactly 👍

Could you please provide links to the docs about upload_dir and db config?

For the DB part: https://craftcms.com/docs/4.x/config/db-settings.html
Note that, there was a change in the environment variables names convention between Craft 3 and Craft 4 where variables have been prefixed with CRAFT_ (for instance CRAFT_DB_SERVER instead of DB_SERVER previously). So maybe, there will be a need for a separate DDEV Craft 3 and Craft 4 setup, but Craft 4 is fastly taking over it seems.

For assets management, there is no documentation for an upload_dir parameter per say because there's no such thing.
You can find documentation about the various general configuration settings here: https://craftcms.com/docs/4.x/config/#general-config-settings
But, there’s no much sense to change or set that on a DDEV level I think.
The upload_dir will change from project to project.
For instance, I actually use a custom DDEV craft-sync provider where I change a craftmedia and clearfolders environment variable depending on the project.

Something like:

environment_variables:
    projectpath: /var/www/staging/${DDEV_PROJECT}/current
    craftmedia: web/media
    clearfolders: 'library'

auth_command:
    command: |
        set -eu -o pipefail
        tsh --proxy=myteleportserver.com ls
    service: host

db_pull_command:
    command: |
        set -eu -o pipefail
        tsh ssh myserver.com php8.0 ${projectpath}/craft db/backup ${projectpath}/db.sql
        tsh ssh myserver.com gzip -c "${projectpath}/db.sql > ${projectpath}/db.sql.gz"
        tsh scp myserver.com:${projectpath}/db.sql.gz .ddev/.downloads/
    service: host

files_pull_command:
    command: |
        set -eu -o pipefail
        tsh ssh myserver.com tar --dereference -czf ${projectpath}/files.tar.gz -C ${projectpath}/${craftmedia} .
        tsh scp myserver.com:${projectpath}/files.tar.gz .ddev/.downloads/
    service: host

files_import_command:
    command: |
        set -eu -o pipefail
        mkdir -p ${craftmedia}
        rm -rf ${craftmedia}/{${clearfolders}}
        tar -zxf .ddev/.downloads/files.tar.gz -C ${craftmedia}
    service: host

⚠️ Beware:

• Please note that there could be more than on "uploads" roots in some situations.
• Do not confuse the resourceBasePath and resourceBaseUrl with the Volumes and Assets configuration, they are not related!

[rfay]

TYPO3 also can have more than one "uploads", and Drupal has both public and private, so DDEV's single dir is a long-term mistake :)

Thanks for the help!

[khalwat]

We got you :)

#4176