Rebuilding & Running LocalGov Drupal docs with DDEV

Introduction

The LocalGov Drupal docs are currently based on VuePress, and turn markdown documents into a static html site.

It's straightforward to set this up in a DDEV environment, but there are a few details to be aware of.

This document assumes you have DDEV installed locally and already know how to enter into web containers with ddev ssh and exit them with exit.

Let's look at the process step by step.

Fetch the repository

~/projects$ git clone [email protected]:localgovdrupal/docs.git localgovdocs

~/projects$ cd localgovdocs

Troubleshooting

Github permission denied

[[email protected]](mailto:[email protected]): Permission denied (publickey).
fatal: Could not read from remote repository. 

Please make sure you have the correct access rights and the repository exists.

Ensure you have associated your public key with your Github account. 

→ https://docs.github.com/en/authentication/troubleshooting-ssh/error-permission-denied-publickey#verify-the-public-key-is-attached-to-your-account

Set up the DDEV environment

~/projects/localgovdocs$ ddev config

Use:

• project name: localgovdocs
• type: php
• docroot: docs/src/.vuepress/dist

Note:

• docs/src/.vuepress/dist does not exist yet at this point, but that's ok.

Start the DDEV environment

~/projects/localgovdocs$ ddev start

Connect to the DDEV web container

To run commands inside of the DDEV web container, you first need to connect to it, just as if you were connecting to a remote server using the SSH protocol:

~/projects/localgovdocs$ ddev ssh

Result:

jpoesen@localgovdocs-web:/var/www/html$

Fetch all the dependencies

jpoesen@localgovdocs-web:/var/www/html$ cd docs

jpoesen@localgovdocs-web:/var/www/html/docs$ yarn install

Build the static site

jpoesen@localgovdocs-web:/var/www/html/docs$ cd src 

jpoesen@localgovdocs-web:/var/www/html/docs/src$ yarn build

Troubleshooting

Error: ERR_OSSL_EVP_UNSUPPORTED

You may run into the following error related to the length of the cryptographic key used in SSL3:

ERR_OSSL_EVP_UNSUPPORTED

If so, you can fix it with the following command, run from your host (not from inside your web container):

~/projects/localgovdocs$ 

ddev config --web-environment-add="NODE_OPTIONS=--openssl-legacy-provider"

Now restart your DDEV environment:

~/projects/localgovdocs$ ddev restart

Enter the web container again and try to build the docs:

~/projects/localgovdocs$ ddev ssh 

jpoesen@localgovdocs-web:/var/www/html$ cd docs/src 

jpoesen@localgovdocs-web:/var/www/html/docs/src$ yarn build

The docs should have been generated under docs/src/.vuepress/dist.

Visit the local docs site

From your host (not from inside the web container) run:

~/projects/localgovdocs$ ddev launch

Edit. Rebuild. Edit. Rebuild.

At this point you're ready to make content changes directly in the underlying markdown files.

Remember to rebuild the static site after each change, using yarn build.

In a next article we'll discuss how to contribute your changes via github.com or from the command-line.