LogoLogo
  • Planet 4
  • Development
    • Contribute
    • Installation
    • Git Guidelines
    • Coding Standards
    • Continuous Delivery
  • CI/CD
    • Test Instances
    • Deployment
    • Testing
      • End-to-end Tests
      • Visual Regression Tests
  • NRO Customization
    • Development
      • Using Child Themes
      • Package Registry
      • Plugins
    • Testing
      • Visual Regression Tests
    • Deployment
      • Production
      • DB/Media Sync
  • Infrastructure
    • NRO Generation
    • ElasticSearch
    • Cloudflare
  • Recipes
    • Maintenance page
    • Production sync
    • Running commands
  • Platform
    • Practices
    • ADRs
      • [ADR-0001] Use Gitbook for Technical Documentation
      • [ADR-0002] P3 Archive elastic search integration
      • [ADR-0003] WYSIWYG Blocks Architecture
      • [ADR-0004] Switch to Monorepo
      • [ADR-0006] Define scope for deployment environments
      • [ADR-0008] PSR-4 Autoloading Standard
      • [ADR-0009] Include Media Library in master theme
      • [ADR-0011] PHP Coding Standards
      • [ADR-0012] Use custom SCSS syntax for variables
      • [ADR-0013] Choose a ticketing system
      • [ADR-0014] Choose a testing framework
      • [ADR-0015] Use block templates to build block patterns
      • [ADR-0016] Form Builder data retention policy
      • [ADR-0017] Move blocks into the theme
    • Changelog
      • 2024
      • 2023
      • 2022
      • 2021
      • 2020
      • 2019
      • 2018
  • Tech
    • Wordpress
    • Blocks
    • Plugins
    • Hooks
    • Data migrations
    • CSS variables
Powered by GitBook
On this page
  • System Requirements
  • Before anything
  • Installation
  • Clean up
  • All commands
  • Workflow
  • Resources
Edit on GitHub
  1. Development

Installation

Get a full Planet 4 development environment to your local machine

PreviousContributeNextGit Guidelines

Last updated 3 months ago

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

System Requirements

  • and

  • and

  • curl

  • optional:

Platform specific steps

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 .

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 .

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:

Docker Issues:

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

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

See for details.

wp-env
docker
docker-compose
node/npm
nvm
gcloud
here
Here is a post
Docker on WSL2
https://github.com/microsoft/WSL/issues/5336
https://nickjanetakis.com/blog/setting-up-docker-for-windows-and-wsl-to-work-flawlessly
https://stackoverflow.com/questions/63497928/ubuntu-wsl-with-docker-could-not-be-found
https://github.com/docker/compose/issues/2738
https://docs.docker.com/docker-for-windows/wsl/
https://github.com/microsoft/WSL/issues/4694#issuecomment-556095344
https://docs.docker.com/desktop/install/mac-install/
https://docs.docker.com/desktop/install/mac-install/
wp-env documentation
WordPress developers blog