Search
K

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

Platform specific steps

Linux
Windows
MacOS
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
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
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.
Makefile: 212: recipe for target 'start' failed
Segmentation fault
@therealkenc, @squeaky-pl Could you try this?
%userprofile%\.wslconfig
[wsl2]
kernelCommandLine = vsyscall=emulate
Mac with Apple silicon (M1, M2, etc.)
Install Rosetta 2:
softwareupdate --install-rosetta
then download and install Docker Desktop from the official documentation:
Mac with Intel chip
Download and install Docker Desktop from the official documentation:

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
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
- 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)
- elastic:activate Activate ElasticSearch container and plugin
- elastic:deactivate Deactivate ElasticSearch container and plugin

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