Drupal Flake

A Nix-native way to get started with Drupal development. This is in early stages, but provides a fully functional local dev environment already.

This flake and context about what Nix is and how it works was presented at DrupalCon Atlanta.

Watch the video on Drupal.tv!

Flake location

The main location for this flake is now on Drupal.org - please file issues at https://www.drupal.org/project/drupal_flake. It is also mirrored at Github, at https://github.com/freelock/drupal-flake .

Any of the following will work to run or download this flake:

• git+https://git.drupalcode.org/project/drupal_flake#demo
• gitlab:project/drupal_flake?host=git.drupalcode.org#demo
• github:freelock/drupal-flake#demo

What works

Currently this flake:

• Uses Process Compose to launch:
  • A MariaDB server
  • Nginx
  • PHP-FPM
  • Drupal CMS install script
  • Script to add a setting.nix.php to connect to the MariaDB server
• Uses a .env file to specify project name, port, PHP version, docroot
• Provides a devShell that sets up drush to work with the installed site
• Provides xDebug configured to work with a trigger (e.g. a browser xdebug helper extension)
• Provides a template to make it easy to install and configure in an existing Drupal project
• Provides a "refresh-flake" command to update to the latest version of this project, inside the project you are using it in
• New! With start-detached, runs process-compose in the background, so you don't need to open a new shell for drush commands! You can still access the TUI using pc-attach

Demo run target

You can install a minimal installation of Drupal CMS with a single command, without even cloning this repo!

nix run git+https://git.drupalcode.org/project/drupal_flake#demo

On my machine with warmed caches, this takes about 2 1/2 minutes to download Drupal CMS, provision a dev runtime environment, install Drupal, and open your browser to the new site.

In the shell you run this in, the "init" task will print the admin username and password.

Install locally

You can run this locally by installing the template:

nix flake init -t git+https://git.drupalcode.org/project/drupal_flake

Once the template is installed, you can run the demo with either nix run or the "demo" command in the dev shell:

nix run .#demo

or

nix develop
start-demo

This will install a fresh copy of Drupal CMS if you don't have one, and launch it all in one go!

The demo setup is skipped if the web/index.php file already exists -- it then just starts up the servers, so this is entirely non-destructive and safe to run repeatedly.

Setting up a new project

With the flake installed locally, you can now set the base project name, port, domain, PHP version, and Drupal package to install using env vars, with --impure. This works on the command line ahead of nix run.

PROJECT_NAME=myproject PORT=9901 DRUPAL_PACKAGE=drupal/recommended-project:^10.4 nix run --impure .#demo

You can set these variables in a .env file - but this is subject to how Nix Flakes handle files -
if you are in a git directory, the .env file needs to be added to git or else Nix will ignore it entirely.

Copy the .env.example to .env and edit as desired.

Note on domain, port

To be able to resolve your site to localhost, you may need to add an entry to your /etc/hosts file. The DDev project has created a wildcard DNS that allows anything that ends in *.ddev.site to resolve to localhost. So by default the domain is set to the PROJECT_NAME.ddev.site, which should always work.

Ports must be higher than 1024, or else you need some sort of root access to be able to use them.

New setup-drupal, setup-settings commands

We've recently added a "setup-drupal" command that can quickly spin up a Drupal CMS or Drupal core project from scratch. This is really useful for testing or contrib development.

First, install Nix with flake support, and we highly recommend configuring direnv. With those available:

• nix flake init -t git+https://git.drupalcode.org/project/drupal_flake
• direnv allow (or nix develop if you don't have direnv)
• setup-drupal
• (accept the defaults or select install package/php version/port manually)
• direnv reload (or exit; nix develop to pick up the new environment)
• start-detached
• (wait 10 - 15 seconds for the database to become available)
• drush site:install ../recipes/byte (for core, you may need to composer require drush/drush to make it available)

... and you're off and running.

Using with existing projects

The Demo target installs a clean new copy of Drupal CMS -- but what about existing projects?

The project has evolved to the point that it's a really nice developer experience to use with existing projects:

1. cd into your site's root
2. run nix flake init -t git+https://git.drupalcode.org/project/drupal_flake to add the flake to your project
3. copy the .env.example to .env, and edit for the project name, port you want to use (must be unique to run multiple projects at once), php version, docroot, etc
4. if you use direnv (highly recommended!), direnv allow
5. if you do not use direnv, nix develop
6. run start-detached
7. the first run may take a few minutes to download all the necessary software -- later runs usually takes only a few seconds. You can check to see if it's up yet using pc-status, or after the software is loaded, you can view the setup using pc-attach (use the F10 key to exit the TUI)
8. once everything is up, drush should be fully functional (if it's installed in your project), so you can import a database backup using drush sqlc < path/to/db.sql or do a site install using drush site:install or following the link to open your browser
9. there are several other useful commands, enter ? to get a list

Test support

There is growing support for running tests in Drupal Flake -- see the "flake-help" command for setup instructions. We are currently using this to set up and run:

• PHPUnit
• Behat
• Playwright

... this is where the developer experience is really nice! You can run these commands directly, without needing to navigate in and out of a Docker container. Agents can run things directly, and you can use any shell tools without needing to install them inside dev containers.

Coming soon:

• SSL certs - possibly switch to Caddy
• Helper to run on standard ports (80, 443)
• Additional services -
  • Solr
  • PhpMyAdmin
  • Mailpit
  • Redis