Installing Pimcore using Docker

Docker is the leading solution for developing containerized applications, allowing developers to configure a virtual environment in their PC that can easily be transferred to a server and be used by the user. In fact, using Docker is the modern way to develop web applications. It accelerates the setup, reduces the friction between environments, and ensures an easy-to-use, replicable system.

Pimcore embraces Docker development and has released Docker images that are ready to be used. Moreover, it has released a docker-compose file that orchestrates all the containers needed to run Pimcore.

Using Docker, you will be able to set up and start Pimcore in minutes. Using the script provided in the GitHub repository for this book, most of the process is easy.

The first step is to clone the Pimcore repository and navigate to the 2. Setting up Pimcore Development Environment folder. You can copy the files from there and paste them into your target folder. The files are as follows:

• docker-compose.yml: This contains the definition of the container; it is quite similar to the default Pimcore file.
• install.sh: This contains the installation script, which is an automated version of the installation steps from the official guide.

Let's see these two files and how we can use them.

The docker-compose file

The docker-compose file contains many container definitions for enabling all the required components. The first one is the database component:

db:
    image: mariadb:10.4
working_dir: /application
    command: [MySQLd, --character-set-server=utf8mb4, --collation-server=utf8mb4_unicode_ci, --innodb-file-format=Barracuda, --innodb-large-prefix=1, --innodb-file-per-table=1]
    environment:
      - MYSQL_ROOT_PASSWORD=ROOT
      - MYSQL_DATABASE=pimcore
      - MYSQL_USER=pimcore
      - MYSQL_PASSWORD=pimcore

In the previous snippet, we have an instance of MariaDB tuned for Pimcore usage. Using the environment variables, we set the most important parameters of the database:

• The credentials of the root user: MYSQL_ROOT_PASSWORD
• The database name: MYSQL_DATABASE
• The credentials of the service user: MYSQL_USER and MYSQL_PASSWORD

With this configuration, we need to connect to the host database using Pimcore/Pimcore credentials.

The second container to take into account is the Pimcore container. Refer to the following code snippet from the docker-compose file:

  php:
    image: Pimcore/Pimcore:PHP7.4-apache
    volumes:
     - .:/var/www/html:cached
    ports:
     - 80:80
     - 443:443
depends_on:
     - db

The name of this container is php because Pimcore relies on a PHP image. Using volume mapping, we mount the folder where the docker-compose file is located on the Pimcore directory inside the container.

The installation file

The installation file is just a set of commands that you should run individually, but condensed into a single script. This prevents any manual errors and reduces the effort needed to set up a new environment.

The script covers the following steps:

1. The first step is the Pimcore download. To do this, we need to add the following command to the script:

   COMPOSER_MEMORY_LIMIT=-1 composer create-project Pimcore/skeleton tmp

   The problem here is with the container image settings. It is created for listening to the /var/www/html/public folder, so the Pimcore installation must be done at the /var/www/html/ level. The problem is that the Composer command will need a folder to download the files from. This will create a subfolder and necessitate a change to the default container settings. So, the most common approach is to download Pimcore in a temporary folder and then move the contents of the temporary folder to the standard Apache folder. This trick is done using the following commands:

   mv tmp/.[!.]* .
   mv tmp/* .
   rmdir tmp

2. Next, we need to fix the memory usage of PHP. Pimcore requires 512 MB for the installation process, and in most cases, the default value from PHP is not sufficient. What we will do in our script is increase the memory limit by changing the configuration files with the following commands:

   echo 'memory_limit = 512M' >>/usr/local/etc/php/conf.d/docker-php-memlimit.ini;
   service apache2 reload

3. Now we are ready to start the Pimcore installation. We will install Pimcore using the settings hardcoded into the docker-compose file. To do this, we need to add the following command to our script:

   ./vendor/bin/Pimcore-install --MySQL-host-socket=db --MySQL-username=Pimcore --MySQL-password=Pimcore --MySQL-database=Pimcore

4. Finally, we have to remember that all the commands we have launched so far have been done on behalf of the root user. So, all the files and folders created belong to the root user and group. The user running the web server will be different and will belong to the www-data group. This means that the web server cannot write or read the files, based on the chmod settings. That's why we need to reset permissions at the end of this process. The following line of code does that:

   chown -R www-data .

   This chown command adds the www-data group to the files and folders permission; this is enough to enable Pimcore to read and write files.

The final version of the script is as follows:

#!/bin/bash
#Pimcore download
COMPOSER_MEMORY_LIMIT=-1 composer create-project Pimcore/skeleton tmp
#trick for moving the files
mv tmp/.[!.]* .
mv tmp/* .
rmdirtmp
#increase the memory_limit to >= 512MB as required by Pimcore-install
echo 'memory_limit = 512M' >>/usr/local/etc/php/conf.d/Docker-php-memlimit.ini;
service apache2 reload
#run installer
./vendor/bin/Pimcore-install --MySQL-host-socket=db --MySQL-username=Pimcore --MySQL-password=Pimcore --MySQL-database=Pimcore
# fix permission
chown -R www-data .

The preceding script is contained in the source code and is called install.sh. You can just copy and paste it to your source code directory and follow the instructions in the next section.

Starting Pimcore with Docker

Now that we have understood how Pimcore using Docker works, we can use our script to start Pimcore:

1. The first step is to navigate to the folder with the Pimcore setup files; in our case, the folder is called /my/project.
2. Open the terminal here and run the following command:

   docker-compose up

   This command activates the Docker environment. Because this command isn't launched with the -d parameter (run as daemon), if you close the console, the Docker environment will shut down. This console is helpful because it shows all the logs from the containers, including the Pimcore container.

3. Then, open another terminal and run the following command:

   docker-compose exec php bash install.sh

   This command will launch the install.sh script inside the container named PHP. The script will run all the instructions needed to install Pimcore. This command is only required the first time you run the container. Its purpose is just for installation.

4. Finally, open a web browser and enter the URL http://localhost/. You will see the standard Pimcore page, as indicated in the following screenshot:
   

   Figure 2.2 – The Pimcore welcome page

5. Now we can test the credential used during the setup by visiting http://localhost/admin in the address bar. You will be redirected to the login page and you will be able to enter credentials and log in to the administrative section of Pimcore. The following screenshot shows the login page:

Figure 2.3 – The Pimcore login page

From now on, performing Step 2 will be enough to run Pimcore!

What we learned in this section was how to install Pimcore using Docker in minutes. As you saw in the Starting Pimcore with Docker section, we just ran two commands and all the processes were set. This reduces the time and effort needed from hours (installing and configuring Apache, Redis, MySQL, and so on) to minutes. Now it's clear why we decided to use Docker in this book.

In the next section, we will enter the Pimcore folder structure and we will learn about what is inside each folder.