diff --git a/docs/src/devs/getting-started/README.md b/docs/src/devs/getting-started/README.md index c3240a6..1ee0914 100755 --- a/docs/src/devs/getting-started/README.md +++ b/docs/src/devs/getting-started/README.md @@ -11,22 +11,21 @@ to a web-based server environment. There are two main approaches to local development: -**1. Using your machine's native technologies:** +**1. Using Docker for a containerized approach:** -Some operating systems come with some of the required tools pre-installed out of the box and (e.g. PHP, web and database -servers). Most of the time, you'll have to manually install the remaining ones. This approach generally requires more -time spent on maintaining and updating every technology separately as well as making sure that all the moving parts -continuously work well together. +Tools such as Lando or DDEV "packages" all the required technologies (web server, PHP and database) for you using +Docker, and simulates a server environment. This approach is more automated and requires less manual work as the +tool takes care of every component's version updates and compatibility is guaranteed. -**2. Using a containerized approach:** +**2. Using your machine's native technologies:** -i.e. a tool such as Lando or DDEV that "packages" all the required technologies for you and simulates a server environment. -This approach is more automated and requires less manual work as the tool takes care of every component's version updates -and compatibility is guaranteed. +Historically, we installed a LAMP-style stack manually, e.g. PHP, Apache/Nginx and a database. This approach generally +requires more time spent on maintaining and updating every technology separately as well as making sure that all the +moving parts continuously work well together. No matter the local installation approach you adopt, Composer is required. -### Composer installation +### Composer Drupal's Core, modules and themes, are all "packages" and Composer manages these dependencies in a structured and organised manner. To put a Drupal website together, all assets have to be sourced from a dedicated URL and compiled to @@ -34,26 +33,22 @@ create a fully functional build. To do that, Composer i.e. Drupal's dependency m your local system. There are two ways to install Composer, locally and globally. The latter is usually preferred as, with a single -executable installed once, it allows Composer to manage the dependencies of multiple projects present on your machine. -To install Composer, follow the detailed instructions on the -[official Composer documentation page](https://getcomposer.org/doc/00-intro.md#globally). +executable installed once, it allows Composer to manage the dependencies of multiple projects present on your machine. + +Composer is included in DDEV and Lando. ### Working with Lando/DDEV containerized servers Many of us use a containerization technology locally for testing and development, such as Lando or DDEV. Both of these -tools simplify the process of setting up and managing development environments for web projects. To use LGD locally with -either Lando or DDEV, you'll need to have Docker Desktop installed first. - -#### Docker Desktop installation +tools simplify the process of setting up and managing development environments for web projects. To use LocalGov Drupal +locally with either Lando or DDEV, you'll need to have Docker installed first. -Docker Desktop is a one-click-install application for your Mac, Linux, or Windows environment that lets you build, share -and run containerized applications and microservices. It provides a straightforward GUI (Graphical User Interface) that -lets you manage your containers, applications, and images directly from your machine. +Different Docker solutions are recommended for macOS, Linux, and Windows, so please follow the instructions: -To install Docker Desktop, follow the steps outlined on the -[official Docker documentation page](https://docs.docker.com/desktop/install/mac-install/#system-requirements). +- [Installing DDEV and Docker](https://docs.ddev.com/en/stable/users/install/) +- [Installing Lando and Docker](https://docs.lando.dev/getting-started/requirements.html) -With Docker Desktop (and Composer) in place, you can now move on to: +With DDEV or Lando in place, you can now move on to: - [Working with Lando](/devs/getting-started/working-with-lando.html) or - [Working with DDEV](/devs/getting-started/working-with-ddev.html) @@ -66,6 +61,7 @@ on their host machine. In that case, you will need to locally install the approp - PHP - Database server - Web server +- [Composer](https://getcomposer.org/doc/00-intro.md#globally) You can have a more thorough look on our dedicated page for the [Drupal Requirements](/devs/getting-started/drupal-requirements.html). @@ -84,11 +80,10 @@ centralised issue tracking of bug reports for end users. ### Coding standards resources -* [Drupal coding standards](https://www.drupal.org/docs/develop/standards) +* [Drupal coding standards](https://project.pages.drupalcode.org/coding_standards/) ### Testing resources -* [PHPUnit documentation](https://phpunit.readthedocs.io/en/7.5/) -* [Drupal 8 PHPUnit documentation](https://www.drupal.org/docs/8/testing/phpunit-in-drupal-8) -* [Drupal 8 testing documentation](https://www.drupal.org/docs/8/testing) -* [Workshop: Automated Testing and Test Driven Development in Drupal 8](https://github.com/opdavies/workshop-drupal-automated-testing) +* [PHPUnit documentation](https://phpunit.readthedocs.io/en/) +* [Drupal 8 PHPUnit documentation](https://www.drupal.org/docs/develop/automated-testing/phpunit-in-drupal) +* [Drupal 8 testing documentation](https://www.drupal.org/docs/develop/automated-testing) diff --git a/docs/src/devs/getting-started/working-with-ddev.md b/docs/src/devs/getting-started/working-with-ddev.md index 4562de2..1330211 100644 --- a/docs/src/devs/getting-started/working-with-ddev.md +++ b/docs/src/devs/getting-started/working-with-ddev.md @@ -8,203 +8,182 @@ tags: # Working with DDEV -## DDEV-Prerequisites +## DDEV Installation -DDEV is an open-source tool for launching local web development environments in minutes. These environments can be -extended, version controlled, and shared, so you can take advantage of a Docker workflow without Docker experience or -bespoke configuration. Projects can be changed, powered down, or removed as easily as they’re started. +DDEV is an Open Source tool for launching local web development environments in minutes. +These environments can be extended, version controlled, and shared, so you can take advantage of a Docker workflow +without Docker experience or bespoke configuration. -The [official DDEV requirements page](https://ddev.readthedocs.io/en/latest/) offers detailed information on the +The Drupal community selected DDEV as the [recommended local Drupal development tool](https://www.drupal.org/docs/getting-started/installing-drupal/install-drupal-using-ddev-for-local-development) in June 2024. + +The [DDEV requirements page](https://docs.ddev.com/en/) offers detailed information on the prerequisites that should be in place but, generally speaking, here's a list of minimum requirements for DDEV: - Recent OS version - RAM: 8GB - Storage: 256GB -_Optional: You can delete the .lando.dist.yml file in the project’s root, as it is redundant when using DDEV -instead of Lando._ - -There are multiple ways of installing DDEV locally, mainly depending on your Operating System. Make sure you go through -the [official DDEV installation page](https://ddev.readthedocs.io/en/latest/users/install/ddev-installation/) if your -OS is not covered below. - -## Installing DDEV on Mac OS - -### DDEV on Mac OS using Homebrew +There are multiple ways of installing DDEV locally, mainly depending on your Operating System. -Homebrew is a popular package manager for Mac OS and Linux - it basically brings packages into your machine in an -organised manner. It controls and manages their dependencies and versions (similar to Composer). -To install Homebrew locally: +Please follow the [DDEV installation instructions](https://docs.ddev.com/en/stable/users/install/) for your Operating System, whether it is macOS, Linux, or Windows. -```bash -/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" -``` +## Installing LocalGov Drupal locally with Composer and DDEV -With Homebrew in place, run the following to install DDEV: +Composer (see [Getting Started](/devs/getting-started/)) is included in DDEV. It is not recommended to install +[PHP or Composer on the host machine](https://docs.ddev.com/en/stable/users/usage/faq/#do-i-need-to-install-php-composer-nginx-or-nodejsnpm-on-my-workstation) +to prevent conflicting versions. -```bash -brew install ddev/ddev/ddev -``` +Now that we have all the required dependencies in place (Composer, Docker and DDEV), we can create our first +LocalGov Drupal project locally. -You can confirm that DDEV is in place by checking its installed version: +Switch to an appropriate directory (for example the `~/Sites` folder on macOS) via the command line: ```bash -ddev -v +cd ~/sites ``` -### DDEV on Mac OS using Curl +### 1. Setting up DDEV -To download and run the install script, run the following in your Terminal: +First, we need to set up DDEV for LocalGov Drupal in a new directory, for example called `localgov`: ```bash -curl -fsSL https://ddev.com/install.sh | bash +mkdir localgov +cd localgov ``` -## Installing DDEV on Windows -You can install DDEV on Windows in three ways: -- Using WSL2 with Docker inside -- Using WSL2 with Docker Desktop -- Installing directly on traditional Windows with an installer - -DDEV strongly recommends using WSL2. While its Linux experience may be new for some Windows users, it’s worth the -performance benefit and common experience of working with Ubuntu and Bash. You can follow the -[official DDEV Windows installation steps](https://ddev.readthedocs.io/en/latest/users/install/ddev-installation/#wsl2-docker-desktop-install-script) -to install DDEV using WSL2 with Docker Desktop. - -## Installing DDEV on Linux - -You can use Homebrew or the curl install script in most instances, as described in the Mac OS installation instructions -above. On the [official DDEV Linux installation page](https://ddev.readthedocs.io/en/latest/users/install/ddev-installation/#linux, -there are more installation ways listed for some Linux and Ubuntu distributions. - -## Installing LocalGov Drupal locally with Composer and DDEV - -If you haven't yet installed Composer and Docker Desktop, see [Getting Started](/devs/getting-started/) for instructions -on how to install these requirements. - -Now that we have all the required dependencies in place (Composer, Docker Desktop and DDEV), we can create our first -LocalGov Drupal project locally. - -Open your Command Prompt/Terminal/Shell and switch to an appropriate directory (for example, on Mac OS X, the ~/Sites -folder is usually preferred): +Then, we need to initialise our DDEV project: ```bash -cd ~/Sites +ddev config --project-type=drupal10 --php-version=8.3 --docroot=web +ddev start ``` -### 1. Creating the Project -Similarly to our Lando installation guide, we are going to use the LocalGov Drupal project template publicly available -on [GitHub](https://github.com/localgovdrupal/localgov_project): - -![ LGD project template on GitHub ](../../images/localgov-drupal-github.png) - -To build the LGD project locally, we need to run the following Composer command and bring all the required packages -together in a new LGD_DEMO directory (feel free to change the project name to anything else you might prefer): - -```bash -composer create-project localgovdrupal/localgov-project LGD_DEMO --no-install +All required resources are pulled in, and the containers start running. + +You can verify everything is working, and see all services with the DDEV `describe` command: + +```yml +$ ddev describe +┌──────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Project: localgov ~/dev/localgov https://localgov.ddev.site │ +│ Docker platform: linux-docker │ +│ Router: traefik │ +│ DDEV version: v1.24.10 │ +├──────────────┬─────────┬────────────────────────────────────────────────────────┬────────────────────┤ +│ SERVICE │ STAT │ URL/PORT │ INFO │ +├──────────────┼─────────┼────────────────────────────────────────────────────────┼────────────────────┤ +│ web │ OK │ https://localgov.ddev.site │ drupal10 PHP 8.3 │ +│ │ │ InDocker -> Host: │ Server: nginx-fpm │ +│ │ │ - web:80 -> 127.0.0.1:32768 │ Docroot: 'web' │ +│ │ │ - web:443 -> 127.0.0.1:32769 │ Perf mode: none │ +│ │ │ - web:8025 -> 127.0.0.1:32770 │ Node.js: 20 │ +├──────────────┼─────────┼────────────────────────────────────────────────────────┼────────────────────┤ +│ db │ OK │ InDocker -> Host: │ mariadb:10.3 │ +│ │ │ - db:3306 -> 127.0.0.1:32772 │ User/Pass: 'db/db' │ +│ │ │ │ or 'root/root' │ +├──────────────┼─────────┼────────────────────────────────────────────────────────┼────────────────────┤ +│ xhgui │ stopped │ https://localgov.ddev.site:8142 │ │ +│ │ │ InDocker: │ │ +│ │ │ - xhgui:80 │ │ +│ │ │ Launch: ddev xhgui │ │ +├──────────────┼─────────┼────────────────────────────────────────────────────────┼────────────────────┤ +│ Mailpit │ │ Mailpit: https://localgov.ddev.site:8026 │ │ +│ │ │ Launch: ddev mailpit │ │ +├──────────────┼─────────┼────────────────────────────────────────────────────────┼────────────────────┤ +│ Project URLs │ │ https://localgov.ddev.site, https://127.0.0.1:32769, │ │ +│ │ │ http://localgov.ddev.site, http://127.0.0.1:32768 │ │ +└──────────────┴─────────┴────────────────────────────────────────────────────────┴────────────────────┘ ``` -The Terminal output of this command will look something like the following: +Every time DDEV starts, the project URLs are included in the output. In our case, we have selected _localgov_ as the +name of our project and, as a result, https://localgov.ddev.site will be the first URL we can access our project on. +Our machine's localhost IP (like `127.0.0.1:32768`) and an available port allocated to our DDEV +project is also available. Both URLs can be used to access our project on our browser. -![ LocalGov Drupal: Composer command output ](../../images/LGD-Composer-project-build-terminal-output.png) +**Note**: The LocalGov Drupal project will not be accessible via those URLs until you have created it, see below. -Switch to the LGD_DEMO directory by running: +At any point (when you're done for the day, for example), you can stop the project and remove its memory usage by running: ```bash -cd LGD_DEMO +ddev stop ``` -### 2. The DDEV Part - -Then, we need to initialise our DDEV project: +Once DDEV has been initialised, you might also want to run: ```bash -ddev config +ddev auth ssh ``` -As you can see in the screenshot below, DDEV is suggesting default values for the following: +... in order to enable your SSH keys for this project (this is useful for SSH authentication in case access to remote +repositories is required). The output of this command lists all the SSH keys our container has been made aware of. -- _Project name_ (suggested default: _locagov_) -- _Docroot location_ (suggested default: _web_) -- _Project type_ (suggested default: _drupal10_) -We complete the initialisation by hitting 'Enter' in all three suggestions so the default value is selected. The output -of the command should look like the following: +### 2. Creating the Project -![ LocalGov Drupal: ddev config output ](../../images/LDG-ddev-config.png) +We are going to use the LocalGov Drupal project template publicly available +on [GitHub](https://github.com/localgovdrupal/localgov_project) and [Drupal.org](https://www.drupal.org/project/localgov). -Then, fire up DDEV: +To build the LocalGov Drupal project locally, we use Composer to bring all the required packages together: ```bash -ddev start +ddev composer create-project localgovdrupal/localgov-project ``` -Initially, the required resources are pulled in: +All Composer packages for this project will be downloaded. This can take a while, as the command downloads all the +necessary packages from their corresponding repositories. -![ LocalGov Drupal: ddev start Terminal output 1 ](../../images/LDG-ddev-start-1.png) +Below are the main phases of the process (you can read more about how Composer +actually manages and installs dependencies on the +[corresponding Composer documentation page](https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies)). -Following that, the containers start running: +#### 1. Locking dependencies to their defined versions -![ LocalGov Drupal: ddev start Terminal output 2 ](../../images/LDG-ddev-start-2.png) +![ LocalGov Drupal: Composer install output - 1 ](../../images/LGD-lando-composer-install-1.png) -Every time ddev starts, the project URLs are included in the output. In our case, we have selected _localgov_ as the -name of our project and, as a result, _https://localgov.ddev.site_ will be the first URL we can access our project on. -The second URL, _https://127.0.0.1:65175_, uses our machine's localhost IP and an available port allocated to our ddev -project. Both URLs can be used to access our project on our browser. +#### 2. Downloading the locked dependencies -**Note**: The project will not be accessible via those URLs until you have run `composer install` in Step 3 below. +![ LocalGov Drupal: Composer install output - 2 ](../../images/LGD-lando-composer-install-2.png) -At any point (when you're done for the day, for example), you can stop the project and remove its memory usage by running: +#### 3. Installing the downloaded dependencies -```bash -ddev stop -``` +![ LocalGov Drupal: Composer install output - 3 ](../../images/LGD-lando-composer-install-3.png) -Once DDEV has been initialised, you might also want to run: +#### 4. Applying patches -```bash -ddev auth ssh -``` +(These have also been pre-defined in the LocalGov Drupal Composer template.) -in order to enable your SSH keys for this project (this is useful for SSH authentication in case access to remote -repositories is required). The output of this command lists all the SSH keys our container has been made aware of. +![ LocalGov Drupal: Composer install output - 4 ](../../images/LGD-lando-composer-install-4.png) -The Docker dashboard, with all our LGD demo project's DDEV containers up and running, should look something like the -following: +#### 5. Scaffolding files -![ Docker Desktop: ddev containers ](../../images/LDG-ddev-docker-desktop-containers.png) +(Scaffolding is a fancy name for putting certain key Drupal files and their contents in place). -### 3. The composer install Part +![ LocalGov Drupal: Composer install output - 5 ](../../images/LGD-lando-composer-install-5.png) -Now it's time to pull in all the Composer dependencies for this project: - -```bash -ddev composer install -``` - -If it's the first time running composer install, this process can take a while because all the project's dependencies -need to be brought in from their repositories. We have already covered the various stages of this Composer command's -output in our -[LGD Lando installation guide](/devs/getting-started/working-with-lando.html#localgov-drupal-local-installation-with-composer-and-lando). -Upon re-running the same command, the Terminal should naturally inform us that there is Nothing to _install, update or -remove_. ### 4. Building the Site with Drush -We can now finally install our site using the site install drush command (for more on drush, Drupal's popular scripting -tool, see [https://www.drush.org](https://www.drush.org): +We can now finally install our site using the site install drush command (for more on drush, Drupal's popular scripting +tool, see [Drush](https://www.drush.org)): ```bash -ddev drush si localgov -y +ddev drush site:install localgov -y ``` The output of the command will look something like the following: ![ ddev drush site install output ](../../images/LGD-ddev-drush-site-install.png) -Our new LocalGov Drupal site is now up and running locally! Remember those two project URLs returned by `ddev start` -above? You can use either one of them, and the credentials returned from the last command, to access your Drupal -administrator account on your brand new LGD site on your favourite browser: +Our new LocalGov Drupal site is now up and running locally! + +To log in to your Drupal administrator account on your brand new LocalGov Drupal site, run this commmand +to create a one time login link for the admin user: + +```bash +ddev launch $(ddev drush user:login) +``` + +Alternatively, open https://localgov.ddev.site/ and manually enter the credentials returned from the +`drush site:install` command here: ![ DDEV local LGD website loaded ](../../images/LGD-ddev-demo-site-user-login-page.png) @@ -212,5 +191,11 @@ Logging into your admin account will land you on the Drupal content page: ![ DDEV local LGD admin logged in ](../../images/LGD-ddev-demo-site-admin-logged-in.png) -Your brand new LocalGov Drupal site is now up and running locally with DDEV. From here, you can explore all the unique -features that come with LGD out of the box and start building your new Council website! +Your brand new LocalGov Drupal site is now up and running locally with DDEV. From here, you can explore all the unique +features that come with LocalGov Drupal out of the box and start building your new Council website! + +To check out all the features, you can create a demo site, by installing the LocalGov Demo module: + +```bash +ddev drush install localgov_demo +```