Project Browser setup on DDEV

These instructions describe setting up Drupal with Project Browser on DDEV for local testing and development.

Method 1: Set up inside a Drupal install

It is assumed that DDEV is already set up on your computer. For instructions for DDEV setup for Windows/Mac/Linux, please visit the DDEV website user guide.

1. From command prompt go to the directory where you keep projects (in this example, "development" is assumed). You may need to create it if you haven’t already. E.g.:

   mkdir -p ~/development && cd ~/development

2. Create a new directory for Project Browser. Note, you should pick a folder name that can form a valid domain name. Underscores are not allowed. E.g.:

   mkdir project-browser && cd project-browser

3. Initialize the DDEV project:

   ddev config --project-type=drupal --php-version=8.3 --docroot=web

4. Start DDEV:

   ddev start

5. Next, we need to install the Drupal core:

   ddev composer create drupal/recommended-project

   For Drupal 10:

   ddev composer create drupal/recommended-project:^10

6. OPTIONAL: You can install Drush here if you like. NOTE: There used to be an issue with symlinks working with Project Browser and Package Manager, but those have largely been mitigated now, so you can install Drush.

   ddev composer require drush/drush

7. If you want to just see the current state of Project Browser, you can download it with Composer. You need to set your minimum-stability in your composer.json file to alpha:

   ddev composer config minimum-stability alpha

   Then download Project Browser:

   ddev composer require drupal/project_browser:^2

   If you want to develop for Project Browser, then you need to clone the Project Browser into your site:

   Create and navigate to a directory called "contrib" in the modules directory. From the repository root (e.g. ~/development/project-browser):

   mkdir web/modules/contrib && cd web/modules/contrib

   Follow the Git instructions to clone project browser to your site.

8. Install Automatic Updates:

   ddev composer require 'drupal/automatic_updates:^3.1'

9. If you installed Drush, you may use it for site installation and enabling modules. If not, we’ll need to launch Drupal in the browser to install. Run from the command prompt:

   ddev launch

10. Follow prompts in browser to install Drupal.

11. When logged in as admin (which you should be on completion of installation), select “Extend” from top menu bar.

12. Use filter box to find “Package Manager”, select it, and click “Install”. Note you may get a warning about available updates. You can ignore this.

13. Use filter box to find “Project Browser”, select it, click “Install”. Install the main Project Browser module. You can ignore “Project Browser Devel” and “Project Browser Source Example”.

14. Select “Configuration” from the top menu bar. Then, find the Development section and click on “Project Browser” under this.

15. On the Project Browser settings, the first option will be “Allow installing via UI (Experimental)”. Tick the checkbox to enable. Click on “Save configuration”.

16. Select “Extend” from the top menu bar. Then click “Contrib modules” on the submenu under “Extend”.

17. Projects on Project Browser will now show a “Select” button next to each module.

18. After selecting one or more modules, an "Install selected projects" button will appear at the bottom of the page.

Method 2: Using DDEV Drupal Contrib

DDEV Drupal Contrib is an extension for DDEV for working on contrib drupal projects, and works on the assumption that your project should be in the root of your development environment.

It provides a clean environment for development, and a convenient way to run tests locally and code quality checks cleanly. However, a downside is it is not currently possible to create an install environment that allows projects to be installed with package manager through the front end. This is because Composer is looking at the Project Browser project rather than the Drupal project.

This method is only recommended if you intend to develop on the Project Browser initiative, so it's assumed you'll be cloning the Git project.

The steps to set up are as follows:

1. As with method 1, create a directory for the project:
   

   mkdir development && cd development
   mkdir project-browser && cd project-browser

2. Clone the project to this directory using the Git instructions.
3. Create the DDEV project with the following command:
   

   ddev config --project-type=drupal --docroot=web --php-version=8.3

4. Now add the DDEV Drupal Contrib project :
   

   ddev add-on get ddev/ddev-drupal-contrib

   (DDEV version older than 1.23.5: ddev get ddev/ddev-drupal-contrib)

5. Start the project:
   

   ddev start

6. Fetch dependencies (including Drupal). You can't run the composer command normally, so run as follows:
   

   ddev poser

7. Set up project sym-links. These create a link from the Drupal install to the Project Browser project:
   

   ddev symlink-project

8. To allow functional JavaScript and Nightwatch tests to run, run the following:
   

   ddev get ddev/ddev-selenium-standalone-chrome
   ddev restart

9. If you would like to watch the tests run in a browser tab:
   1. Edit the file .ddev/config.selenium-standalone-chrome.yaml
   2. Find the line starting "- MINK_DRIVER_ARGS_WEBDRIVER"
   3. Delete the "--headless" flag, including the surrounding \" characters.
   4. Save the file.
   5. Open the browser tab to watch with:
      

      ddev launch :7900

10. Run tests:
    

    ddev phpunit

Building the app with DDEV

Whichever method you use to install Project Browser in DDEV, if you change the Svelte source files you will need to rebuild the app with yarn. (If these instructions work for you please remove this note, these was with DDEV v1.23.0).

cd sveltejs
ddev yarn global add rollup
ddev yarn install
ddev yarn build

If you are working on an issue, you will then add the files sveltejs/public/build as part of your merge request.