Skip to content

Tooling

This page describes the development tools FedMS expects. The non-negotiable rule is: everything PHP-related goes through L3D.

L3D

LakeDrops DockerDrupalDevelopment (L3D) is a Docker-based development environment. It manages containers, volume mounts, SSH agent forwarding, and environment variables for you, and provides a single command-line entry point:

1
l3d <command>

What l3d wraps

Instead of Run
php … l3d php …
composer … l3d composer …
drush … l3d drush …
ahoy … l3d ahoy …
phpunit … l3d phpunit …
phpcs … l3d phpcs …
phpstan … l3d phpstan …
node / npm / npx / yarn … l3d <tool> …
bash (in container) l3d bash
drupalorg … l3d drupalorg …
glab … l3d glab …

Hard rule

Never run PHP, Composer, Drush, Ahoy, phpunit, phpcs, phpstan, node, npm, drupalorg, or glab directly on the host. Always prefix with l3d. This guarantees the right PHP version, the right Composer config, and the right access to SSH keys and credentials.

Where to run l3d from

Run l3d from the directory you are actually working in — do not cd to the project root first. L3D:

  1. Walks up from your current directory to find the project root (the directory with .env containing COMPOSE_PROJECT_NAME=).
  2. Detects the project root for you.
  3. Transitions back into your subdirectory inside the container before running the command.

This matters when you are working in a fedms_* module's own git repo — running l3d glab from inside the module operates on the module's repo, not the site's.

Bootstrap once per session

If the project root contains docker-compose.yml, bring the stack up to date at the start of a session:

1
l3d ahoy d4d update

Once per session is enough. It is fine to skip if you know the stack is already current.

Ahoy

Ahoy is a YAML-driven command runner. FedMS uses it to expose high-level operations.

Top-level Ahoy commands

From the site root:

1
2
3
4
5
6
7
l3d ahoy d4d update                     # boot/refresh docker stack
l3d ahoy fedms install                  # full fresh install of the site
l3d ahoy fedms update-config            # apply config updates idempotently
l3d ahoy fedms export-config            # export config across all FedMS modules + profile
l3d ahoy test phpcsmodule fedms_task    # run phpcs on a module
l3d ahoy test phpstanmodule fedms_task  # run phpstan on a module
l3d ahoy test phpunitmodule fedms_task  # run phpunit on a module

Module-level Ahoy commands

Some modules ship their own Ahoy:

1
2
3
4
# fedms_locale:
l3d ahoy fedms_locale extract-translation   # rebuild fedms_locale.de.po via potx
l3d ahoy fedms_locale import-translation    # locale:import de --override=all
l3d ahoy fedms_locale export-config         # export only fedms_locale config

Drush

Drush is the Drupal command-line tool. Most things you would do via the Drupal admin UI can also be done via Drush.

Common commands:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
l3d drush status                        # site status
l3d drush cr                            # cache rebuild
l3d drush cex                           # config export to sync dir
l3d drush cim                           # config import from sync dir
l3d drush updatedb                      # run pending DB updates
l3d drush en <module>                   # enable a module
l3d drush user:login                    # one-time login URL
l3d drush config:devel-export <module>  # export module config (config_devel)
l3d drush eca:trigger:custom-event id   # trigger an ECA custom event
l3d drush modeler_api:disable eca       # disable the ECA modeler temporarily
l3d drush modeler_api:enable eca        # re-enable

Composer

Composer is the PHP dependency manager. FedMS uses it heavily.

1
2
3
4
l3d composer install                              # install dependencies
l3d composer update                               # update all
l3d composer update fedms/task --with-deps        # update one package
l3d composer require fedms-recipe/send_email      # add a recipe

The FedMS Composer registry must be in your composer.json:

1
2
3
4
5
6
"repositories": {
  "fedms": {
    "type": "composer",
    "url": "https://gitlab.lakedrops.com/api/v4/group/fedms/-/packages/composer/"
  }
}

The Amplius tenant composer.json includes this automatically.

glab

glab is the GitLab CLI. FedMS uses it for MRs, issues, pipelines.

1
2
3
4
5
6
7
l3d glab mr create --fill --target-branch develop   # create an MR
l3d glab mr view 42                                  # view an MR
l3d glab issue list                                   # list issues for the current repo
l3d glab issue view 8                                 # view an issue
l3d glab ci status                                    # pipeline status
l3d glab ci view                                      # detailed pipeline view
l3d glab ci trace <job-name>                          # pull logs from a failed job

Run glab from the directory of the repo you want to target. If you want to operate on fedms_task's repo, cd into web/modules/contrib/fedms_task first.

Database access

Never call mysql or mariadb directly on the host. Always go through Docker Compose:

1
2
docker compose exec mariadb mariadb \
  -u root -p"${MYSQL_ROOT_PASSWORD}" "${MYSQL_DATABASE}"

Credentials are in .env at the project root.

For piping input (e.g. importing a dump):

1
2
docker compose exec -T mariadb mariadb \
  -u root -p"${MYSQL_ROOT_PASSWORD}" "${MYSQL_DATABASE}" < dump.sql

Mailpit

The Docker stack ships a mailpit service that catches all outbound mail in development. Open https://mailpit-<your-instance>.fedms.lakedrops.com (or your local mailpit URL) to inspect every message.

Common gotchas

Symptom Fix
l3d: command not found Ensure /usr/local/bin/l3d exists. See LakeDrops L3D installation.
Container not running l3d bash once to bootstrap; then retry.
Wrong PHP version Check PHP_VERSION in .env.
glab sees the wrong repo You're in the wrong directory. cd into the right repo.
ahoy test phpcsmodule eca_content fails Use the parent module name (eca). The command resolves to web/modules/contrib/<name>/.

Next steps