Install Akeneo PIM
#Install Akeneo PIM with Docker
Akeneo maintains its own Docker images in a dedicated repository. This document provides step by step instructions to install the PIM with Docker, using these images.
These images are built for development and testing purposes only, and are not intended for production.
These instructions are valid for community edition as well as the enterprise edition.
#Getting Akeneo PIM
As our Docker image does not contain Akeneo PIM, you need to download it first. This can be done by downloading the archive from the Website, or from the Portal if you have access to the enterprise edition. It can also be downloaded by cloning it from GitHub (using the standard edition for projects or the development edition to contribute).
Every flavor (dev or standard, community or enterprise) comes with a Docker Compose file template docker-compose.yml.dist
, ready to be used.
#System requirements
#Docker and Docker Compose
If you don’t already have Docker and Docker Compose installed on your system, please refer to the documentation of the GitHub repository.
#Setting up your host user
The PIM is shared with the containers as a volume.
The fpm and node containers will have write access to the PIM folder, and they will do so through their respective users: docker
for fpm and node
for node.
These users UID and GID are both 1000:1000, so on Linux hosts it is mandatory that the user of your host machine has 1000:1000 as UID and GID too, otherwise you’ll end up with a non working PIM.
You won’t face this problem on Mac OS and Windows hosts, as those systems use a VM between the host and Docker, which already operates with appropriate UID/GID.
#Mandatory folders
To accelerate the installation of the PIM dependencies, Composer cache and Yarn cache are shared between the host and the containers. This is achieved by bind mounting the cache folders of your host machine with the containers as follows:
The following compose file example is intentionally incomplete, focusing on cache directories only. Check the complete file directly in the PIM.
version: '2'
services:
fpm:
environment:
COMPOSER_HOME: '/home/docker/.composer' # Declare where the Composer home folder will be IN THE CONTAINER
volumes:
- ~/.composer:/home/docker/.composer # Bind mount the Composer home folder of your host machine with the one of the FPM container
node:
environment:
YARN_CACHE_FOLDER: '/home/node/.yarn-cache' # Declare where the Yarn cache folder will be IN THE CONTAINER
volumes:
- ~/.cache/yarn:/home/node/.yarn-cache # Bind mount the Yarn cache folder of your host machine with the one of the Node container
You need to be sure these folders exist on your host before launching the containers. If not, Docker will create them for you, but with root permissions, preventing the containers from accessing it. As a result, dependencies installation will fail.
The cache of composer is usually in its home folder, in a cache
subdirectory (in other words, in ~/.composer/cache
). However, on some Linux systems, the Composer cache and configuration are separated in different folders:
- composer home will be in ~/.config/composer
(it contains your GitHub token, mandatory to install the dependencies of akeneo/pim-community-standard
or of the Enterprise Edition),
- composer cache will be in ~/.cache/composer
.
If you are in this case, you need to update your compose file as follows:
version: '2'
services:
fpm:
environment:
COMPOSER_CACHE_DIR: '/home/docker/.cache/composer'
COMPOSER_HOME: '/home/docker/.config/composer'
volumes:
- ~/.cache/composer:/home/docker/.cache/composer
- ~/.config/composer:/home/docker/.config/composer
#Using the Docker images
#Prepare the compose file
Copy it as docker-compose.yml
and keep it at the root of your project. You may modify it at your convenience, to change the mapping of the ports
if you want Apache to be accessible from a port other that 8080, for instance.
If you intend to run behat tests, create on your host a folder /tmp/behat/screenshots
(or anywhere else according to your compose file) with full read/write access to your user.
Otherwise docker-compose
will create it, but only with root accesses. Then failing behats will be unable to create reports and screenshots.
#Run and stop the containers
All “docker-compose” commands are to be run from the folder containing the compose file.
Make sure you have the last versions of the images by running:
$ docker-compose pull
To start your containers, run:
$ docker-compose up -d
To stop the containers, run:
$ docker-compose stop
but if you want to completely remove everything (containers, networks and volumes), then run:
$ docker-compose down -v
This, of course, will not delete the Akeneo application you cloned on your machine, only the Docker containers. However, it will destroy the database and everything it contains.
#Install and run Akeneo
#Configure Akeneo
First, make sure that Akeneo database settings are as the containers expect.
As you can see below, the database_host
parameter is the name of your MySQL service in the compose file.
For Elasticsearch, index_hosts
is the association of the login and password (elastic
and changeme
, respectively) of the container,
the service name in the compose file (elasticsearch
) and the output port of Elasticsearch (9200
).
# /host/path/to/you/pim/app/config/parameters.yml
parameters:
database_driver: pdo_mysql
database_host: mysql
database_port: null
database_name: akeneo_pim
database_user: akeneo_pim
database_password: akeneo_pim
locale: en
secret: ThisTokenIsNotSoSecretChangeIt
product_index_name: akeneo_pim_product
product_model_index_name: akeneo_pim_product_model
product_and_product_model_index_name: akeneo_pim_product_and_product_model
index_hosts: 'elastic:changeme@elasticsearch:9200'
# /host/path/to/you/pim/app/config/parameters_test.yml
parameters:
database_driver: pdo_mysql
database_host: mysql-behat
database_port: null
database_name: akeneo_pim
database_user: akeneo_pim
database_password: akeneo_pim
locale: en
secret: ThisTokenIsNotSoSecretChangeIt
installer_data: PimInstallerBundle:minimal
product_index_name: behat_akeneo_pim_product
product_model_index_name: behat_pim_product_model
product_and_product_model_index_name: behat_pim_product_and_product_model
index_hosts: 'elastic:changeme@elasticsearch:9200'
You only need to set parameters_test.yml
if you are using akeneo/pim-community-dev
or akeneo/pim-enterprise-dev
. It is not mandatory for using the standard
edition.
#Install Akeneo
Now, you can initialize Akeneo by running:
$ bin/docker/pim-dependencies.sh
$ bin/docker/pim-initialize.sh
Those two bash scripts are just helpers placed in the PIM, in the folder bin/docker
. They execute the following commands (you could do so too if you prefer):
pim-dependencies.sh
$ docker-compose exec fpm composer update
$ docker-compose run --rm node yarn install
pim-initialize.sh
This is what the script contains in akeneo/pim-community-dev
or akeneo/pim-enterprise-dev
:
$ docker-compose exec fpm bin/console --env=prod cache:clear --no-warmup # Those 4 commands clear all the caches of Symfony 3
$ docker-compose exec fpm bin/console --env=dev cache:clear --no-warmup # You could also just perform a "rm -rf var/cache/*"
$ docker-compose exec fpm bin/console --env=behat cache:clear --no-warmup
$ docker-compose exec fpm bin/console --env=test cache:clear --no-warmup
$ docker-compose exec fpm bin/console --env=prod pim:install --force --symlink --clean
$ docker-compose exec fpm bin/console --env=behat pim:installer:db # Run this command only if you want to run behat or integration tests
$ docker-compose run --rm node yarn run webpack
The version in akeneo/pim-community-standard
or akeneo/pim-enterprise-standard
is simpler as it is not intended to run tests:
$ docker-compose exec fpm bin/console --env=prod cache:clear --no-warmup
$ docker-compose exec fpm bin/console --env=prod pim:install --force --symlink --clean
$ docker-compose run --rm node yarn run webpack
If you are using Docker for Windows, there may be issues with symlinks that lead to errors during yarn run webpack
. If you encounter these issues, try leaving out the –symlink parameter from the pim:install
commands.
You should now be able to access Akeneo development environment from your host through ``http://localhost:8080/`` and behat environment through ``http://localhost:8081/``. The default username and password are both ``admin``.
Of course, you can change the host port in the compose file. If you do so, don’t forget to run again:
$ docker-compose up -d
#Run imports and exports
Akeneo 2.x implements a queue for the jobs, as a PHP daemon. This daemon is a Symfony command, that can only execute one job at a time. It does not consume any other job until the job is finished.
You can launch several daemons to allow the execution of several jobs in parallel. A daemon checks every 5 seconds the queue, so it’s not real time.
To launch a daemon, run the following command:
docker-compose exec fpm bin/console --env=prod akeneo:batch:job-queue-consumer-daemon
If you want to launch the daemon in background:
docker-compose exec fpm bin/console --env=prod akeneo:batch:job-queue-consumer-daemon &
If you want to execute only one job:
docker-compose exec fpm bin/console --env=prod akeneo:batch:job-queue-consumer-daemon --run-once
There is no need to launch a daemon for behat and integration tests. It is performed automatically, the daemon being killed once the test is finished.
Before stopping or destroying your containers, remember to first stop this daemon if you launched it in background, or you’ll end up with a stuck FPM container, and will need to completely restart Docker.
$ docker-compose exec fpm pkill -f job-queue-consumer-daemon
#Xdebug
Xdebug is deactivated by default. If you want to activate it, you can change the environment variable PHP_XDEBUG_ENABLED
to 1. Then you just have to run docker-compose up -d
again.
Also, you can configure two things on Xdebug through environment variables on akeneo
images. These environment variables are all optional:
PHP_XDEBUG_IDE_KEY
: the IDE KEY you want to use (by defaultXDEBUG_IDE_KEY
)PHP_XDEBUG_REMOTE_HOST
: your host IP address (by default it allows all IPs)
#Run behat tests
The tests are to be run inside the containers. Start by configuring Behat, by copying the file behat.yml.dist
to behat.yml
. Then make the following changes:
- Replace any occurrence of
http://akeneo/
byhttp://httpd-behat/
(which is the name of the Apache service of the Compose file that will be used to run the behats). - Configure selenium as follows:
# /host/path/to/your/pim/behat.yml
default:
...
extensions:
Behat\ChainedStepsExtension: ~
Behat\MinkExtension:
default_session: symfony2
javascript_session: selenium2
show_cmd: chromium-browser %s
sessions:
symfony2:
symfony2: ~
selenium2:
selenium2:
wd_host: 'http://selenium:4444/wd/hub'
base_url: 'http://httpd-behat/'
files_path: 'features/Context/fixtures/'
...
You are now able to run behat tests.
$ docker-compose exec fpm vendor/bin/behat features/path/to/scenario
#What if?
#I want to see my tests running
The docker image selenium/standalone-firefox-debug
comes with a VNC server in it. You need a VNC client, and to connect to localhost:5910
. The VNC password is : secret.
You will then be able to see you browser and your tests running in it!
#I never want to see my tests running
In this case, you don’t need to have a VNC server in your selenium container.
You can achieve that simply by replacing the image selenium/standalone-firefox-debug
by selenium/standalone-firefox
. The first is based on the second, simply adding the VNC server.
Don’t forget to also remove the binding on port 5900, now useless as selenium/standalone-firefox
does not expose it.
#I want to run my tests in Chrome instead of Firefox
Then all you need to do is to replace the image selenium/standalone-firefox-debug
by selenium/standalone-chrome-debug
(or selenium/standalone-chrome
if you don’t want to see the browser in action).
Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!