Install Akeneo PIM with Docker¶

Akeneo maintains its own Docker images in https://github.com/akeneo/Dockerfiles. This document provides step by step instructions to install the PIM with Docker, using these images.

Warning

These images are built for development and testing purposes only, and are not intended for production.

Note

These instructions are valid for community edition as well as the enterprise edition.

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 akeneo and akeneo-behat containers will have write access to the PIM folder, and they will do so through their docker user.

This user 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 is shared between host and container.

You need to be sure the folder ~/.config/composer exists on your host before launching the containers. If not, Docker will create it for you, but with root permissions, preventing the container from accessing it. As a result, dependencies installation will fail.

Getting Akeneo PIM¶

You need to download Akeneo PIM. This can be done by downloading the archive from our download page https://www.akeneo.com/download, or from our Portal if you have access to the enterprise edition. It can also be downloaded by cloning it from GitHub (https://github.com/akeneo/pim-community-standard for projects or https://github.com/akeneo/pim-community-dev to contribute).

Using the Docker images¶

Every flavor (dev or standard, community or enterprise) comes with a Docker Compose file template docker-compose.yml.dist, ready to be used. 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¶

Note

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.

# /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

# /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

Note

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.

MongoDB¶

If you want to use MongoDB storage, add the following to your PIM parameters (like for MySQL, the mongodb_server parameter corresponds to the name of the MongoDB service in the compose file):

# /host/path/to/you/pim/app/config/parameters.yml and parameters.yml.dist ; the last one is important too, to avoid removal on "composer update"
parameters:
    ...
    pim_catalog_product_storage_driver: doctrine/mongodb-odm
    mongodb_server: 'mongodb://mongodb:27017'
    mongodb_database: akeneo_pim

# /host/path/to/you/pim/app/config/parameters_test.yml
parameters:
    ...
    pim_catalog_product_storage_driver: doctrine/mongodb-odm
    mongodb_server: 'mongodb://mongodb-behat:27017'
    mongodb_database: akeneo_pim

Then activate the DoctrineMongoDBBundle by uncommenting the following line in app/AppKernel.php to enable the MongoDB configuration:

$ gedit app/AppKernel.php
new Doctrine\Bundle\MongoDBBundle\DoctrineMongoDBBundle(),

Finally, install the required dependency if you are using Akeneo standard edition (it is already included in the development dependencies of the dev edition):

$ cd /path/to/installation/pim-community-standard
$ php -d memory_limit=3G ../composer.phar --prefer-dist require doctrine/mongodb-odm-bundle 3.2.0

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 akeneo composer update

pim-initialize.sh

This is what the script contains in akeneo/pim-community-dev or akeneo/pim-enterprise-dev:

$ docker-compose exec akeneo app/console --env=prod cache:clear --no-warmup    # Those 4 commands clear all the caches of Symfony 2
$ docker-compose exec akeneo app/console --env=dev cache:clear --no-warmup     # You could also just perform a "rm -rf app/cache/*"
$ docker-compose exec akeneo-behat app/console --env=behat cache:clear --no-warmup
$ docker-compose exec akeneo-behat app/console --env=test cache:clear --no-warmup

$ docker-compose exec akeneo app/console --env=prod pim:install --force --symlink --clean
$ docker-compose exec akeneo-behat app/console --env=behat pim:installer:db    # Run this command only if you want to run behat or integration tests

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 akeneo app/console --env=prod cache:clear --no-warmup

$ docker-compose exec akeneo app/console --env=prod pim:install --force --symlink --clean

You should now be able to access Akeneo development environment from your host through ``http://localhost:8080/`` and behat environment through ``http://localhost:8081/``.

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

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 default XDEBUG_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 as follows:

# /host/path/to/your/pim/behat.yml
default:
    paths:
        features: features
    context:
        class:  Context\FeatureContext
        parameters:
            base_url: 'http://akeneo-behat/'
            timeout: 10000
            window_width: 1280
            window_height: 1024
    extensions:
        Behat\MinkExtension\Extension:
            default_session: symfony2
            show_cmd: chromium-browser %s
            selenium2:
                wd_host: 'http://selenium:4444/wd/hub'
            base_url: 'http://akeneo-behat/'
            files_path: 'features/Context/fixtures/'
        Behat\Symfony2Extension\Extension:
            kernel:
                env: behat
                debug: false
        SensioLabs\Behat\PageObjectExtension\Extension: ~

You are now able to run behat tests.

$ docker-compose exec akeneo-behat 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:5900. 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).