How To Install Akeneo on Ubuntu 20.10

This is a step-by-step guide to installing Akeneo on a Linux-based host. The purpose of this tutorial is to give consolidated instructions on installing the Akeneos Community Edition PIM  on a machine running Ubuntu 20.10 for development. Note this does not cover the installation process for production deployments.

I highly recommend reviewing the Akeneo documentation  prior to and during the installation process.

For a fresh install of Ubuntu 20.10, I will take you through the steps that I followed when installing Akeneo V 5.0 on a virtual machine running Ubuntu. If you are unsure of how to set up a local Ubuntu environment check out this tutorial on setting up a virtual machine on any system.


Sudo privileges When installing and initializing your Akeneo hosting you will be using sudo in order to have instance-based root privileges to make modifications to your machine, it is not recommended that you run your terminal with root privileges to avoid accidental changes or errors.

To start, there are four utilities that need to be installed on your system: 

  • Docker 19+
  • docker-compose 1.24,
  • make
  • bash.

 

Installing and Checking Dependencies

Where does this information come from? For some of the below installation commands, the links to the documentation will be provided

To begin first take a look to see if your machine has make and Bash.

 

Confirming Bash

By default, your Ubuntu installation should be running Bash in the terminal so unless your system is not fresh and the default terminal shell has been changed you do not need to do anything. If for some reason you are not in a bash shell simply enter the following:

bash

 

Installing the Make Utility

The next step is to check and install a utility called make. To check if your system has this tool enter into your terminal the following:

make

For a fresh install, it should not be on your system yet and your terminal will tell you that the command cannot be found.

To install make enter in the command below and follow the in terminal prompts, once finished make will be installed on your machine:

sudo apt install make

 

Installing Docker

Docker 1.9 Ubuntu Install Documentation Here is a link to the documentation provided on Docker’s website, you can find more information on how to install docker using a different Linux distribution or how to uninstall out-of-date versions of Docker off of your system.

Docker will not be installed on your new Ubuntu install, so to start the process of setting up docker, you will need to set up a Docker repository by performing the following commands:

sudo apt-get update
Followed by:
sudo apt-get install \
    apt-transport-https \
    ca-certificates \
    curl \
    gnupg-agent \
    software-properties-common

Next you will need to add Docker’s official GPG Key:

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -

To verify that this is the correct fingerprint, search for the last 8 characters of the fingerprint (which should be 0EBFCD88).

sudo apt-key fingerprint 0EBFCD88

The final step for setting up the Docker repository is to set up a stable repository

sudo add-apt-repository \
   "deb [arch=amd64] https://download.docker.com/linux/ubuntu \
   $(lsb_release -cs) \
   stable"

Finally, to install Docker we will once more update the apt package index and then install the latest version of docker (For older versions of Docker view the documentation on how to download it specifically):

 sudo apt-get update

Followed by:

 sudo apt-get install docker-ce docker-ce-cli containerd.io

Once these commands are completed you can test to see if your Docker Engine installation is correct you may enter:

sudo docker run hello-world

Installing Docker Compose

Docker Compose Installation Documentation Here is the documentation for installing compose on all machines.

 

Compose should not be installed on your machine by default, so you will need to follow the following commands to install the current stable release of Docker compose:

sudo curl -L "https://github.com/docker/compose/releases/download/1.28.4/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

Now you will need to apply executable permissions to docker-compose by entering the following:

sudo chmod +x /usr/local/bin/docker-compose

To test that you’ve correctly set up docker-compose, enter the following command:

docker-compose --version

Installing Akeneo PIM V5.0

Akeneo 5.0 Installation Documentation Here you can find all information on this installation step and better understand the commands we will be using.

 

Now that you have verified that your system meets the system requirements, we will confirm the host user on your machine. (By default it is mandatory that the user ID (UID) and Group ID (GID) of the host user must be 1000:1000)

To check your UID and GID you may enter: (-u for UID; -g for GID)

id [-u|-g]

To set your host user’s UID and GID you will need to type the following commands entering your username in the {your username} placeholder:

sudo usermod -u 1000 {your username}
sudo groupmod -g 1000 {your username}

It is possible your UID and or GID are already set to 1000 but running the above commands will cause no issues.

Once you have done this you are ready to create a PIM project.

In this tutorial, we will be using Community Edition of Akeneo, but if you are building an Enterprise Edition PIM project, you may see the specific commands needed by using the installation documentation.

It is required that your PIM project must be created in a empty directory so to begin we will create a directory and navigate to it:

mkdir pim
cd pim

Now that you are navigated into this directory you can enter the following command:

sudo docker run -ti -u www-data --rm \
    -v $(pwd):/srv/pim -v ~/.composer:/var/www/.composer -w /srv/pim \
    akeneo/pim-php-dev:5.0 php /usr/local/bin/composer create-project \
    akeneo/pim-community-standard /srv/pim "5.0.*@stable"

Once this has created your project there is one more step to address an issue with permissions and that is by simply modifying a line of code in docker-compose.yml. All you need to do is navigate and find

YARN_CACHE_FOLDER: '/home/node/.yarn'

You will need to modify this and add :z to the end of this line and it should fix any launch errors

YARN_CACHE_FOLDER: '/home/node/.yarn:z'

Now you are ready to launch your Akeneo PIM!

 

Starting your Akeneo PIM project

To start your project make sure that you are inside your project directory and then you will enter the following command:

sudo make dev

This command will run for a little while and if you’ve followed the steps listed above you should not run into any errors.

Once your make command has completed you can navigate to your browser of choice and enter in the URL localhost:8080

This is what you should see and on your first launch, the username and password to enter your PIM are set to admin, admin.

Once you are signed in you should have access to your own Akeneo installation!

 

All Done? Shutting down your project

IMPORTANT: When shutting down your project, realize all data will be erased as the data is stored in the Mysql container, to make the data persistent follow the suggestions provided in the Akeneo tutorial.

When you are done working on your project you can navigate back to your terminal window and enter in the following commands to shut down the PIM:

sudo make down

Congratulations! You now know how to install and operate your own Akeneo environment.

I hope that this tutorial helped make the process of setting up Akeneo easy and quick so that you can explore Akeneo or jump right into development!

 

Need Help Going to Production?

If you need a partner that can help you take Akeneo into production, please consider Alpine.  Our consulting team has the skills and experience to help you integrate Akeneo into your business environment and configure the system to meet your product management needs and procedures.   Learn more about Alpine’s Akeneo services or contact us today!