Setting up a LAMP server on Ubuntu 16.04 for Joomla! Development.
This document will guide you through setting up a LAMP (Linux / Apache / MySQL / PHP) Server for Joomla! 3.x Development. The Ubuntu 16.04 platform was chosen because Ubuntu Linux is both freely available and very well supported. Note that version 16.04 is the newest long term support version of Ubuntu at the time of this writing. An astute reader will realize that this environment can be used for the development of any web-based application or website, not just the Joomla! Content Management System. This document will walk through step by step detailing what software needs to be installed and what configuration has to be made for all the components to work together. During the process, specific folders and file names and their locations will be used so that everyone stays on the same page, but in reality you have latitude with what you name your server, your location of the virtual host directory, and more. These will be mentioned in sections marked with the words [Additional Information] in a blue box. This document assumes the reader already has either installed Ubuntu 16.04 Desktop or Server. These instructions will also work with the other flavors of Ubuntu that exist. Kubuntu, Edubuntu et. al.
[Additional Information]
Text marked in red mono-space font represents a command you would type in the terminal, browser or in a text editor. For example: sudo apt install lamp-server^
Step 1 – Installing LAMP
Installing LAMP on your computer can be incredibly easy or kinda hard. It just depends if you are a glutton for punishment or not. Fortunately, most of us like to do things that are both quick and efficient and I am no different. So the method I will use to install LAMP is going to be the painless one.
Start by opening a terminal. I like to use the [CTRL][ALT][T] key stroke to do this. Once the terminal opens type in the command sudo apt install lamp-server^. Please note the caret (^) at the end of the command. It is required.
At this point you will be prompted to download the packages required by your request. Enter y, and press enter.
When the packages are downloaded and the installation starts you will be asked for a MySQL root user password, and then asked to type it again. This is the password for the root account of the MySQL server program. This password is very important and must be remembered. If you have to write it down to keep from forgetting it, remember to keep it in a safe place.
When the software installation has completed we can test that everything is good to go by opening up the web browser and typing http://localhost into the address bar.
[Additional Information]
For those of you who have installed programs on Ubuntu using the terminal may be asking what is the deal with the caret (^) at the end of the command. Well, what you are seeing here is a clever little shortcut to install all the packages we need in one fell swoop. The lamp-server^ allows the apt-get program to perform a task that the program Tasksel would do. Tasksel is the program that the installer of Ubuntu Server runs to allow you to select bundles of server software. This allows us to do the same thing without having to separately install the Tasksel program.
Step 2 – Installing phpMyAdmin
The program phpMyAdmin is a web application that will allow you to work with the MySQL server from a web based interface. It is convenient to have installed if your a developer and allows you to create databases, do queries, create users and a myriad of other handy things. Although this is not specifically required to develop Joomla! 3.x extensions, its inclusion does make life just a little bit better.
In order to install phpmyadmin, a couple of dependencies have to be met. The newer versions of phpmyadmin support multi-byte character sets used for those languages that utilize more than the standard single byte character sets. So to meet these requirements, we will have to install two php libraries that are not installed by default when you install the LAMP server. These are mbstring and gettext. To install these libraries enter the command sudo apt install php-mbstring php-gettext and press the enter key. When you are asked if you want to install the additional packages, enter y and press the enter key.
With the dependencies met we can now install phpmyadmin. To install phpmyadmin, enter the command sudo apt install phpmyadmin in your terminal. Apt-get will notify you of the packages that need installed and ask you if you want to continue, enter y and press enter.
Once the packages are downloaded and the install starts, it will ask you to choose the web server that should be automatically configured to run phpMyAdmin. Press the space bar to select apache2, then press the tab key until <Ok> is highlighted and press the enter key.
Next, phpMyadmin informs you that a database needs to be installed and configured before it can be used. It asks if you want to allow it to create this database using the script dbconfig-common. Select yes and press the enter key.
Next, phpMyAdmin asks for a password that will be used to register with the database server. Again, you can enter anything you like here but you will want to remember it. I use the same password that I entered for the root user in step one. Press tab to highlight <Ok> and press the enter key. PhpMyAdmin asks you to re-enter the password you just created. Enter the password again, then press tab to highlight <Ok> and press the enter key.
Finally, phpMyAdmin has been installed. To test our work, open your browser up and enter http://localhost/phpmyadmin in the address bar and press enter. If all worked well, you will be presented with the phpMyAdmin login screen. Enter the user name of root and the password you created in step 1 above. You should now be logged into phpMyAdmin. All is good.
Step 3 – Setting up the folder for the virtual host.
At this point I am making a purposeful decision to set up Apache to use virtual hosts. I have a couple of reasons for doing this. First, it provides a very convenient place for us to place our files when we develop, namely in our home folder. Second, if we are developing for more than one client or project, each project can have its own autonomous space.
Now that you know the reason, let's set up a virtual host for Joomla! development. So we all stay on the same page, let's create a folder on our desktop to hold our virtually hosted files. You can either right click your desktop and select create a new folder and name it joomdev, or you can do it from the command line with the following command: mkdir ~/Desktop/joomdev. The tilde character is a shortcut meaning your home folder.
Step 4 – Changing Apache to run as your user.
Running Apache on the local machine can cause a lot of permission headaches. There are a number of differing solutions to help remedy this. The solution I take is to have Apache run as the same user and group as the developer ie, ME. This will prevent the problems associated with Apache running as one user and group and the developer running as another. But please remember, this is NOT a safe practice. This assumes that Apache is only running in your development environment and will NEVER be placed on the Internet. You have been warned!!!
For those of you who have been running around in Linux for a while, the idea of users and groups are second nature for you. However, if you are new to the Linux world, these concepts may not be so clear. So, I am going to take a minute to cover them and for you experts out there, please be patient we will get moving again shortly.
Every user and program in Linux runs as a specific user and in a specific group. Permissions in Linux are assigned to users, groups and others (called world). The Apache web server is no different. In Ubuntu Linux, Apache runs as the user www-data and the group www-data. As a user, you run as your user name and in Ubuntu are assigned a group that has the same name as your user name. Armed with this little bit of knowledge, we discover why there are so many issues with permissions trying to develop when we run as one user and the web server, Apache, runs as a different user. To remedy this problem, we are going to tell the web server, Apache, to run as our user name and group.
If you are a very new user to Ubuntu and your machine automatically logs you in when you start it, you may be asking yourself, what is my user name and group. Fortunately, it is very easy to find this information out.
If you need to figure out your user name, there are a couple ways of determining it. First, if it is not already open, start a terminal session. Recall, pressing [CTRL][ALT][T] will start it for you. The first method is to just look at the prompt. You should see <your user name>@<your machine name>. Yes, that is how simple it really is. The portion to the left of the @ symbol is your user name. Now, if you really want to confirm this, you can type the command whoami and press enter and the computer will inform you the user name you are running as.
The next step is to determine your user group. While still at the command prompt type the command groups <user name> where <user name> will be your user name that was determined from the instructions above. The output of this command will be a listing of all the groups you belong to, and chances are you could have quite a few. Examine the list of groups and you will most likely discover that one of your groups matches your user name. This is group is the best candidate for the job at hand and is the one you will want to use in the instructions below.
Hopefully, the experts toughed out that little excursion in rabbit hunting and are still with me. Now that we have our user name and group, we need to instruct Apache to run as them instead of its own user name and group. To do this, enter the command sudo nano /etc/apache2/envvars and this will open up an Apache configuration file using a text editor called nano. This file controls all the environment variables Apache uses yo run. There are two lines in this file we need to change. Look for the lines that read export APACHE_RUN_USER and export APACHE_RUN_GROUP. At the end of these lines, replace the user www-data with your user name, and replace the group www-data with your group. Now press [CTRL][X] to exit the editor. It will ask you to save the modified buffer, press y and then press enter to save. That is all there is to make Apache run as our user and group.
With all that out of the way, let's check our work by restarting the Apache service. Enter the command sudo service apache2 restart and press enter.
Step 5 – Setting up the Virtual Host for Apache.
The next order of business is setting up the virtual host for Apache. To do this we need to create a file that gives Apache enough information about our virtual host so that when we make a request for it, it knows where to find it and where to write the logs and what to call them. The name you give this file is irrelevant, but should help remind you what it is. I am going to call mine joom.dev.conf. One thing to take note of here is that Apache version 2.4 requires that the virtual host configuration files end with a .conf extension. This is a new requirement since Apache version 2.4. To create this file issue the command sudo nano /etc/apache2/sites-available/joom.dev.conf. Add the following information to the file we just created.
<VirtualHost *:80>
ServerName joom.dev
ServerAlias www.joom.dev
DocumentRoot /home/<user name>/Desktop/joomdev/
<Directory /home/<user name>/Desktop/joomdev/ >
Options Indexes FollowSymLinks
AllowOverride All
Require all granted
</Directory>
LogLevel info
ErrorLog ${APACHE_LOG_DIR}/joom.dev-error.log
CustomLog ${APACHE_LOG_DIR}/joom.dev-access.log combined
</VirtualHost>
One line of the file that I want to talk about is the DocumentRoot directive. The document root is where Apache will go to serve web pages for the virtual host. The path that is entered there will be the full path where the folder is located. In the above example, you see that I am pointing to the folder I created on my desktop in step 3. If you have followed the example verbatim to this point you will want to make sure your replace the <user name> with your user name. If you are unsure of what your Linux user name is, you can find it by typing the command whoami at the terminal prompt. Lastly, I need to mention the <Directory> lines are required by Apache 2.4 to allow access to documents outside of the already configured document store of /var/www. If you don't add these lines then when you try to access your website, you will get a 403 Forbidden Error. Save this file by pressing [CTRL][X], then press y, and finally press the enter key.
In order for Apache to find our virtual host we have to enable the re-write module. To do so, enter the command sudo a2enmod rewrite.
Next, we have to tell Apache that we want to use our virtual host. To enable Apache to use it, enter this command. sudo a2ensite joom.dev.conf.
Finally, we have to restart Apache for the new settings to take effect. Do so with the command sudo service apache2 restart.
Step 6 – Setting up name services for our virtual host.
So far, we have told apache that we want to use a virtual host and that our host will be called myjoom.dev. The name myjoom.dev was entered on the ServerName line of the configuration file we created in the last step. For the redirection to work correctly, we need to make the request in our browser to http://joom.dev and it needs to point to the local host. If we were on the Internet, we would use Domain Name Services (DNS) to do this for us, but since we are not we will need to use the /etc/hosts file to do it for us. So let's edit the file with sudo nano /etc/hosts. Add the line 127.0.0.1 www.joom.dev joom.dev to the file. Press [CTRL][X] to exit, press y to save and the press the enter key.
That's all there is to it. When we want to go to joom.dev, the computer will look in this file and send us to 127.0.0.1.
[Additional Information]
You may be wondering why don't we just point our browser to 127.0.0.1 or to localhost since it goes to the same place. The reason is that Apache needs to see the myjoom.dev to know to go to our folder we set up for it. If we used localhost or 127.0.0.1 then Apache would load the default web location located at /var/www.
Step 7 – Create a simple page to test our virtual host.
We are nearly finished. All that is left to do is create a simple web page to test our setup. Let's fire up the nano editor and do just that with the command nano ~/Desktop/joomdev/index.html and enter in the following text.
<html>
<head>
<title>My Joomla Development Server Test Page</title>
</head>
<body>
<h3>Virtual Host Test Page</h3>
<p>Welcome to your virtual host!</p>
</body>
</html>
Press [CRTL][X] to exit and y to save and then the enter key. That's it. Let's test it by opening the browser and going to http://joom.dev in the address bar. If all went well, you should see a welcome message from your virtual host in your browser window.
Now you have your own LAMP server set up to run virtual hosts. However, before you start developing PHP applications and extensions for Joomla! we need to enable some features that make developing a little easier. Let’s do that next.
[Additional Information]
I mentioned earlier some of the benefits of running virtual hosts on your server and I think they are worth the few extra minutes it takes to set it up. But I do want to mention that the name you choose for your folder does not matter as long as it is being pointed to in the virtual host file. And the same thing for the name of the virtual host file. Just use a name that describes the host you are creating so later, if you want to make a change, you can recognize it by it's name. And lastly, the name you use for the virtual host you are creating, like myjoom.dev does not matter either as long as you put it in the virtual host file for Apache and make the entry into your hosts file so your computer can translate the name properly.
Step 8 - Making Changes to your LAMP server to aid in developing.
When you code in PHP and make an error, the default for PHP is to display nothing at all. This is what you want in a production environment, but in a development environment you want to know what went wrong. Fortunately for us, we can get PHP to tell us when we have encountered an error and give some information about it. To do this we need to edit the file that controls the PHP engine. This file is called php.ini and is found in the /etc/php/7.0/apache2/ folder.
Edit this file by entering the command sudo nano /etc/php/7.0/apache2/php.ini in your terminal. When the file is opened find the line that reads error_reporting = … and change it to read error_reporting = E_ALL. You can find the line quickly in the file is you press [CTRL] + [W] to search the document and enter the text error_reporting = in the search box and press the enter key.
The E_ALL tells PHP to display all errors, warnings and notices including coding standards.
Now that we have told PHP what errors that we want to be displayed, we now need to tell PHP to actually display them. To do this find the line that reads display_errors = Off and change it to read display_errors = On. You can get to the line quickly by using the above mention search feature of nano. Press the [CTRL] + [W] keys and enter the search text of display_errors = and press the enter key.
Now that we have made changes to the php.ini file we need to to take affect. In your terminal window restart apache with the command sudo service apache2 restart. Now if we make a mistake in our code php will be able to display it.
But wait … there’s more.
A PHP extension called xdebug can provide a stack trace showing us where out code experience the problem and where the call to our code was made. It does this in a way that makes this information much easier to read. To install xdebug, open your terminal and issue the following command:
sudo apt install php-xdebug
When is it complete, restart the apache web server by issuing the command sudo service apache2 restart.
Xdebug is a powerful tool. I encourage you to learn more about it. Go to their website, xdebug.org and take a look.
There are more things we can do to make debugging easier with PHP, but we will save these changes for a time that they are required. If you plan on developing for Joomla, there are recommended settings for developing. You will do yourself a favor if you go to docs.joomla.org and read up.
ALL DONE!!!