This guide will walk you through taking an brand new server to having a working Magento instance in 10 minutes or less. This guide follows all the recommended guidelines suggested by the Magento developers.
Prerequisites:
- An Ubuntu 18.04 LTS or Debian Buster server with at least 1GB of RAM for an archive based install or 2GB for the composer install.
- Basic knowledge of using the Linux command line.
- The hostname of your store must resolve (point) to the IP address of your server before you start this guide if you want to install an SSL certificate.
- An account with Magento. Login or sign up here.
You will need to get your access keys from your Magento Marketplace account by going to My Profile -> Access Keys and making a note of them.
Please note, Whenever I mention Magento in the following guide I am referring to Magento 2.
To begin these steps, you must SSH into your server as a sudo enabled non-root user.
Step 1 – Install all packages
Magento requires a web server, a database server, PHP and some PHP extensions.
We will use Apache2 and MariaDB as our web and database servers along with the default PHP in Ubuntu 16.04 and Debian Buster, PHP 7.3. The following commands will install everything required:
sudo apt update
sudo apt install apache2 php unzip mariadb-server php-bcmath php-curl php-gd php-intl php-mbstring php-mysql php-soap php-zip php-common php-xml php-opcache
This will install PHP 7.2 on Ubuntu and PHP 7.3 on Debian. Both versions are supported by Magento 2.3
Step 2 – Create a system user and Magento’s root directory
The Magento developers recommend, for security reasons, that a non-root system user is created and added to the webserver group. This user should be used when running the magento
binary that is used to manage the Magento installation.
We will create a user called magento
and add them to the web server’s group ’ www-data
. with the following commands:
$ sudo adduser magento
$ sudo usermod -a -G www-data magento
Now, create the Magento installation root directory:
$ sudo mkdir /var/www/magento
Then set the correct ownerships on this directory:
$ sudo chown magento:www-data /var/www/magento
Next, we need to create and configure the database that Magento will use.
Optional step - Create some system swap
If you’re trying to install Magento on a VPS there may not be any system swap space that can cause the installer to fail. If your system has 1GB of RAM it’s a good idea to create some system swap and even if you have a 2GB system Composer can fail without some swap space available.
You can check if there if your system has swap by running the free
command:
$ sudo free -m
total used free shared buff/cache available
Mem: 1829 266 76 18 1486 1399
Swap: 0 0 0
On this system, the three 0’s on the swap line shows there is no system swap. The following commands will create a swapfile and configure the system to use this file for swap.
First, create the swap directory:
$ sudo mkdir /swap/
Next, create a 2GB file that will hold the swap data:
$ sudo dd if=/dev/zero of=/swap/swapfile bs=1MB count=2048
You can change the size of the swap file by modifying the count=2048
number to the amount of MB’s you want. Next, give it the recommended 600
permissions:
$ sudo chmod 600 /swap/swapfile
Format it:
$ sudo mkswap /swap/swapfile
And finally, enable as the system swapfile:
$ sudo swapon /swap/swapfile
This configuration will only work until the next reboot which will probably be enough to complete the installation. If you want to make this permanent add the following line to /etc/fstab
:
/swap/swapfile none swap sw 0 0
Your system will now use the swap file after a reboot.
Step 3 – Create a database
In order to create a database, we need to first enter the MariaDB shell.
This is simply done by entering the command:
sudo mysql
on the command line.
When you do that you will be immediately taken to the MariaDB shell that will supply a new prompt that looks like this:
MariaDB [(none)]>
The following command will create a new database called magentodb
:
CREATE DATABASE magentodb;
Next, we will create a new user called magento and assigned them full permissions to the new database with the following command:
GRANT ALL ON magentodb.* TO magento@localhost IDENTIFIED BY '<STRONG PASSWORD>';
You must change <STRONG PASSWORD>
to a secure password when you enter this command. Make a note of the database name, username and password as they will be required later. After you have done this log out of the MariaDB shell by entering exit;
.
It is a good idea to validate the database we just created along with the username and password. This is done by logging into the MariaDB shell as the new user with the following command:
mysql -u magento -p magentodb
If you can log in using the details you set then the new database and user are working correctly.
The next job is to download, unpack and prepare Magento archive.
Step 4A – Installing Magento with Composer (2GB RAM Required)
If your system has less than 2GB of RAM skip this section and use the archive-based install in Step 4B.
Composer is a dependency manager for PHP that Magento uses to download all the components for Magento. Please note, Magento only supports Composer version 1x. This is the version shown in the instructions below.
First, change to Magento’s home directory:
cd /var/www/magento/
Next, download the latest Composer 1x version:
wget https://getcomposer.org/composer-1.phar
Next, make it execuitble:
chmod 755 composer-1.phar
Make this a system command by moving it to a directory on the system path:
$ sudo mv composer-1.phar /usr/local/bin/composer
Now that composer is installed we can use it to download Magento with the following command:
composer create-project --repository=https://repo.magento.com/ magento/project-community-edition /var/www/magento/
You will be prompted for a username and password. You will need to enter:
Username = <PUBLIC KEY>
Password = <PRIVATE KEY>
The keys are the ones that you copied from your Magento marketplace account.
When the update finishes run the following commands to set the correct ownerships and permissions on the downloaded files and directories:
cd /var/www/magento/
find var generated vendor pub/static pub/media app/etc -type f -exec chmod g+w {} +
find var generated vendor pub/static pub/media app/etc -type d -exec chmod g+ws {} +
chown -R magento:www-data /var/www/magento/
chmod u+x bin/magento
Magento is now downloaded and ready to get served after Apache is configured.
Step 4B – Installing Magento from an archive
Here we will install Magento from an archive downloaded from the Magento website. This install method will work happily on systems with much less than 2GB of RAM.
The archive containing Magento is downloaded from this page:
https://magento.com/tech-resources/download
You should select version 2.3.x without sample data. We will use the .tar.gz
version as this is the most widely supported compression format. The tar.gz
archive is shown here (although an older version number):
You must create an account to download the file. Once you have downloaded the file you will need to upload it to your server.
After you have uploaded the archive to your server you need to log back into your server and unpack the Magento archive to /var/www/magento
:
$ tar -vxf /path/to/Magento-archive.tar.gz --directory /var/www/magento
You can now delete the Magneto archive if you want to.
Next, we will set recommended ownerships and permissions. The following commands must be run from the installation directory, i.e. /var/www/magento
, so the first command will move you to that directory:
cd /var/www/magento
find var generated vendor pub/static pub/media app/etc -type f -exec chmod g+w {} +
find var generated vendor pub/static pub/media app/etc -type d -exec chmod g+ws {} +
chown -R magento:apache /var/www/magento
chmod u+x bin/magento
We will finish installing Magento from an installation page accessed by a browser after Apache is configured.
Step – 5 Configuring Apache
We need to configure Apache for HTTP so that we can use it to install the SSL certificate in the next step.The application that we will use in the next step will create the HTTPS configuration automatically.
First, change into the sites-available
directory under Apache’s configuration directory:
cd /etc/apache2/sites-available/
Then use your preferred text editor to create and open a new VirtualHost
file. Here we will use nano
and the file will be called example.com.conf
:
$ sudo nano example.com.conf
We will use the following VirtualHost
template:
<VirtualHost *:80>
ServerName <STORE HOSTNAME>
DocumentRoot /var/www/magento
ErrorLog ${APACHE_LOG_DIR}/magento_error.log
CustomLog ${APACHE_LOG_DIR}/magento_access.log combined
<Directory /var/www/magento >
Options FollowSymLinks
AllowOverride All
</Directory>
</VirtualHost>
Copy and paste this into the VirtualHost file. The only change that you will need to make is to change <STORE HOSTNAME>
to the name of your web store.
Then, enable the new site with the following command:
$ sudo a2ensite example.com
You must change this example to match the name of the VirtualHost file you created. Simply use the file name without the “.conf” to enable it e.g. my-domain.com.conf becomes:
$ sudo a2ensite my-domain.com
Next, run the following to enable mod_rewrite
Apache module which is required by Magento:
$ sudo a2enmod rewrite
Reload Apache to enable the new configuration:
$ sudo systemctl reload apache2
Step 6 - Install an SSL certificate
In this step we will install the SSL (TLS) certificate for your store so that you will be able to use HTTPS links. We will use a free Let’s Encrypt certificate that will work in all browsers and the CertBot application to install the certificate and keep it updated.
First download all the required packages:
$ sudo apt-get install certbot python-certbot-apache
Next, run the certbot
command that will download the certificate and create the Apache configuration to use the certificate:
$ sudo certbot --apache
You will then be prompted to enter an email address for the certificate. After you have entered that you must agree to the T&C’s and decide if you want to share your email address with the Electronic Frontier Foundation. This last step is optional.
The final prompt will ask you if you want to allow HTTP and HTTP access to your store or if you want HTTPS only. If you opt for the latter HTTP requests will get redirected to the HTTPS site. HTTPS only is the more secure and is the recommended, modern option.
Reload Apache again to load all the new configuration:
$ sudo systemctl reload apache2
When you installed Certbot a systemd timer was created that will automatically attempt to renew any certificates on your server twice per day. When a certificate gets close to expiry it will get renewed automatically.
Your web store is now protected with an SSL certificate which will get automatically renewed before it expires.
Step – 7 Installing Magento
We will install Magento by accessing the installation page in a web browser. You need to browse to the https://
address of your store. Follow the on-screen instructions to complete the installation. You will need to enter the database details that you used when you created the Magento database, magentodb
.
Make sure that you note down the admin URL, passcodes and any other information as you set them during the installer as the installer does not always display the Success page.
When the installation has finished you will see a Success page listing all the details of your Magento installation. You should copy and paste all this information into a file for future reference.
Note: I have had the installer page halt here at around 74% even though the installation has completed. Check the install log file at /var/www/magento/var/log/install.log
for “Magento installation complete”. If you see that then Magento is installed and you just need to visit the admin pages you chose earlier.
The final task for this installation is to create the Magento cron jobs.
Step 8 – Creating the Magento cron jobs
Magento requires several periodic, backend tasks to keep the installation working correctly. Linux has a specific program called cron
which is designed to run tasks or jobs at intervals. Magento provides a tool to create the correct cron entries to keep everything up-to-date.
Log back into your server’s command line and reset the ownerships again after the installation:
chown -R magento:www-data /var/www/magento
Then mote to the magento
directory that you created in Step 2:
su - magento
Then move to /var/www/magento
:
cd /var/www/magento
When you are there run the following command:
bin/magento cron:install
You can check what was written to the crontab with the following command:
crontab -l
You should see something like the following:
#~ MAGENTO START a6b8f559a4432711bb5c07bca3c5734473e32ef2453c2c0db27c7f50fc023a63
* * * * * /usr/bin/php7.3 /var/www/magento2/bin/magento cron:run 2>&1 | grep -v "Ran jobs by schedule" >> /var/www/magento2/var/log/magento.cron.log
* * * * * /usr/bin/php7.3 /var/www/magento2/update/cron.php >> /var/www/magento2/var/log/update.cron.log
* * * * * /usr/bin/php7.3 /var/www/magento2/bin/magento setup:cron:run >> /var/www/magento2/var/log/setup.cron.log
#~ MAGENTO END a6b8f559a4432711bb5c07bca3c5734473e32ef2453c2c0db27c7f50fc023a63
Magento is now fully installed and working.
Conclusion
We have now completed a Magento 2.3 installation following the recommendations of the Magento developers. A good idea at this point is to take a backup of your server or VM before you customize your Magento installation. This will give you an excellent starting point to return to if you mess up your installation or if you simply want to experiment with Magento and want a handy starting point before settling on a production version.