Installation

Get a full Planet 4 development environment to your local machine

We are using wp-env as a base and pulling all necessary themes and plugins so that you can develop for your website more easily.

System Requirements

• docker and docker-compose

• node/npm and nvm

• curl

• optional: gcloud

Platform specific steps

Linux

Install basic system dependencies:

sudo apt install -y git make unzip apt-transport-https ca-certificates curl gnupg-agent software-properties-common

Install docker and docker-compose. We prefer to install it from upstream, to have the latest version:

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
sudo add-apt-repository -y "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io

Add your user to the docker group to avoid using sudo on every command:

sudo usermod -aG docker ${USER}

Refresh your group membership by running:

su - ${USER}

To verify that everything works you can just run the hello-world docker container:

docker run hello-world

Windows

In order to run the Planet4 development environment in Windows you'll need to enable Windows Subsystem for Linux (WSL). WSL allows you to run a Linux environment within Windows. You'll need to enable WSL and install Ubuntu. The current version (WSL 2) comes with a lot of enhancements and better disk performance. You can follow the installation instructions here.

Here is a post with some more detail about setting up WSL 2 (and many other tips for Windows devs!)

Note: this guide was created using the Ubuntu 20.04 image.

Verify WSL 2 and the Ubuntu image are installed

From a Powershell window, run this command to see the installed distros:

wsl -l -v

You should see the distro you installed in the list, with the WSL version: Ubuntu 20.04 - 2

Make sure WSL is enabled

Look here for more details. and set version for a specific distribution:

wsl --set-version Ubuntu-20.04 2

Install docker

Follow official documentation on Docker on WSL2.

Troubleshooting

In case the WSL version for your distro is 1, you can update it using:

wsl --set-version Ubuntu-20.04 2

WSL 2 Networking Issues: https://github.com/microsoft/WSL/issues/5336

Docker Issues: https://nickjanetakis.com/blog/setting-up-docker-for-windows-and-wsl-to-work-flawlesslyhttps://stackoverflow.com/questions/63497928/ubuntu-wsl-with-docker-could-not-be-foundhttps://github.com/docker/compose/issues/2738

sudo pip3 install -IUq docker-compose

The command 'docker-compose' could not be found in this WSL 2 distro.
We recommend to activate the WSL integration in Docker Desktop settings.

See https://docs.docker.com/docker-for-windows/wsl/ for details.

Makefile: 212: recipe for target 'start' failed

Segmentation fault

https://github.com/microsoft/WSL/issues/4694#issuecomment-556095344

@therealkenc, @squeaky-pl Could you try this?

%userprofile%\.wslconfig

[wsl2]
kernelCommandLine = vsyscall=emulate

MacOS

Mac with Apple silicon (M1, M2, etc.)

Install Rosetta 2:

softwareupdate --install-rosetta

then download and install Docker Desktop from the official documentation:

https://docs.docker.com/desktop/install/mac-install/

Mac with Intel chip

Download and install Docker Desktop from the official documentation:

https://docs.docker.com/desktop/install/mac-install/

Before anything

• Clone the develop repo:

git clone https://github.com/greenpeace/planet4-develop/

• Set node version:

# nvm will automatically select the right version based on the `.nvmrc` file
nvm use

• Install npm packages:

npm install

• Check the requirements:

npm run env:requirements

Installation

Install default developer environment with:

npm run env:install

NRO environment

For NRO developers, use instead:

# NRO name is the name used for your deployment repo (repo -> name to use):
# planet4-international -> international
# planet4-australiapacific -> australiapacific
npm run nro:install <nro name>

Clean up

npm run env:clean

All commands

npm run
- usage                             Get information about all commands
- env:requirements                  Check requirements
- env:install                       Install default Planet 4 theme and database
- env:start                         Start the environment
- env:stop                          Stop the environment
- env:clean                         Clean wp-env and delete all Planet 4 files
- env:destroy                       Delete all wp-env and Planet 4 files and containers
- env:config                        Show generated configuration
- env:fix-permissions [all]         Fix files permissions to current user as owner
- env:clean-repos                   Remove main repos if they are not git repositories
- env:update                        Update installer, base and main repos
- env:status                        Status of docker containers
- env:e2e-install                   Install E2E tests dependencies
- env:e2e                           Run E2E tests on local instance
- nro:install <?nro>                Install NRO theme and database
- nro:enable                        Enable installed NRO theme and database
- nro:disable                       Switch back to default theme and database
- nro:theme <?nro>                  Clone NRO theme in themes dir
- build:assets                      Build main repos assets
- build:repos                       Clone and install main repos
- db:import <dump path> <db name>   Import database dump (gzip)
- db:use <db name>                  Switch to database
- shell:php                         Access PHP shell (WordPress container)
- shell:mysql                       Access MySQL console (current database)
- logs:mysql                        Shows logs from the mysql container
- logs:php                          Shows logs from the php (wordpress) container
- elastic:activate                  Activate ElasticSearch container and plugin
- elastic:deactivate                Deactivate ElasticSearch container and plugin
- xdebug:install                    Install Xdebug in WordPress container
- xdebug:configure                  Rewrite Xdebug configuration and reload server
- xdebug:flamegraph <trace>         Generate a flamegraph from a Xdebug trace file

Workflow

• Themes are installed under planet4/themes

  • the theme is usually cloned by the installer and should be modifiable right away

  • you can add or create any theme in this folder, it will be available in your local instance

• Plugins are installed under planet4/plugins

  • you can add or create any plugin in this folder, it will be available in your local instance

Resources

• wp-env documentation
• WordPress developers blog