We are using docker and docker-compose to provide as consistent a local development environment as possible, in accordance with 12factor development principles.

System Requirements

Firstly, check you have all the requirements on your system. For Linux users, these are either preinstalled or available through your distribution's package manager.

• ​git​

• ​make - Instructions for installing make vary, for OSX users xcode-select --install might work

• ​docker​

• ​docker-compose - This should be installed along with docker on OSX and Windows

• ​npm​

• ​envsubst - This should be pre-installed on most Linux distributions

• php-xml and php-mbstring extensions

# install basic packages
sudo apt install -y curl git make
​
# install php packages
sudo apt install -y composer php-xml php-mbstring
​
# install node and npm
curl -sL https://deb.nodesource.com/setup_13.x | sudo -E bash -
sudo apt install -y nodejs
​
# install docker
sudo apt install -y docker.io
​
# install docker-compose
sudo curl -L "https://github.com/docker/compose/releases/download/1.25.4/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
​
# allow user to run docker
sudo usermod -aG docker $USER
newgrp docker

First run

The first time you'll need to follow the steps below, in order to clone this repo and build the containers.

# Clone the repository
git clone https://github.com/greenpeace/planet4-docker-compose
​
# Navigate to new directory
cd planet4-docker-compose
​
# Build containers, start and configure the application
make dev

If you want the application repositories to be cloned using ssh protocol, instead of https, you can use a variable:

GIT_PROTO="ssh" make dev

If you want to run docker-compose commands directly:

# Set your shell environment variables correctly
eval $(make env)
​
# View status of containers
docker-compose ps
​
# View log output
docker-compose logs -f

On first launch, the container bootstraps the installation with composer then after a few minutes all services will be ready and responding to requests.

When the terminal is finished, and you see the line 'ready', navigate to www.planet4.test.

It's not necessary to re-run make dev each time you wish to start the local development environment. To start containers on subsequent runs, use:

make run

Lightweight configuration

If the current setup is too heavy for your machine, there is a lighter version that skips creating some of the containers. Keep in mind though that this leaves out PhpMyAdmin, ElasticHQ and Selenium containers, so it would be harder to debug things.

To use it, you need to set the relevant environmental variable. For instance:

DOCKER_COMPOSE_FILE="docker-compose.light.yml" make run

Troubleshooting

To view the output of running containers:

eval $(make env)
docker-compose logs

If at any point the install process fails, with Composer showing a message such as file could not be downloaded (HTTP/1.1 404 Not Found), this is a transient network error and re-running the install should fix the issue.

Stop

To stop all the containers just run:

make stop

Updating

To update all containers, run:

make run

Editing source code

By default, the Wordpress application is bind-mounted at:

./persistence/app/

All planet4 code will be under the Wordpress' content folder:

./persistence/app/public/wp-content/

Logging in

Administrator login

Backend administrator login is available at www.planet4.test/wp-admin/.

Login username is admin and the password is admin.

Database access via phpMyAdmin

​phpmyadmin login: pma.www.planet4.test​

Elasticsearch access via ElasticHQ

​elastichq Access at localhost:5000/​