Introduction

This article covers hosting Joomla on a personal Linux based computer for testing and development purposes. The Linux versions covered are from the Debian-Ubuntu family, and specifically Linux Mint. Other distributions are similar but have different command syntax and file locations.

You need to install a set of software packages often referred to as LAMP stack. The letters refer to Linux, Apache, MySQL and PHP. You can install software using either the Graphical User Interface (GUI) or the command line in a Terminal window. They are different ways of using the Synaptic Package Manager.

Install Apache with the GUI

From the system Menu, marked with the LM logo, select Administration / Synaptic Package Manager. You will be prompted for your password. Enter your login password to open the GUI. At the top right is a Search button. Select it and enter apache and select Search. Select the apache2 checkbox and in the pop-up label select Mark for Installation. Another pop-box will show a list of additional packages required to support apache. Select Mark:

Select the Apply button in the top Toolbar and the Apply button in the Summary dialog. Apache will be installed and configured, the process ending with a Changes Applied dialog. Select Close.

You can confirm that Apache is installed and working by opening your browser, Firefox by default in a new Linux Mint install, and entering localhost in the URL bar. You should see the Ubuntu Apache2 Default Page:

The page contains some useful information about file locations that may not be so readily available later so you might like to print this page to paper or a pdf file.

Install PHP with the CLI

It is probably best to install PHP using the command line. One reason for this is that, at the time of writing, the Synaptic Package Manager only offers PHP8.1 although PHP8.2 has been available for some time and can be installed from a third party repository. There is a good description of the procedure in this tutorial with Quickstart and Detailed sections.

First close your Synaptic Package Manager GUI and then open a Terminal window and enter the following commands one at a time:

sudo add-apt-repository ppa:ondrej/php
sudo apt update
sudo apt install php8.2 php8.2-cli php8.2-{bz2,curl,mbstring,intl}
sudo apt install php8.2-fpm
sudo a2enconf php8.2-fpm
sudo systemctl reload apache2

In your browser, check that the localhost default page is still working.

Install MySQL or MariaDb

You can search the web for information on each of these database packages. MySQL is the traditional choice but was taken over by Oracle and is now less popular. MariaDB is a drop-in Open Source replacement with additional features. Both work with Joomla! 5 but it is not easy to change from one to the other. Tables have to be exported and imported. Joomla! 5 requires specific minimum versions which Linux Mint offers via the Synaptic Package Manager.

Open the Synaptic Package Manager GUI and search for either mysql-server or mariadb-server. Select the checkbox for the item ending in -server. Select Mark for Installation and them Apply in the top Toolbar. You can open the Details panel to see what is happening during the installation. Select Close when done.

You can test to see whether your database is working by entering mysql in the command line. This is the the same for both MySQL and MariaDB. You should see an Access denied error message, which is fine as it indicates your database installation is actually working.

Install phpMyAdmin

phpMyAdmin is a GUI database management tool that you will need to create and manage your databases. In the Synaptic Package Manager GUI search for phpmyadmin. Select its checkbox and Mark for Installation. After download there is a prompt to select the Webserver to reconfigure automatically. Select the chckbox for apache2 and then the Next button. At the next configuration screen leave the Configure database... checkbox checked and select Next.

Select an application password for the user phpmyadmin. Test: in your bowser enter localhost/phpmyadmin in the URL bar. You should see the phpMyAdmin login screen. With the username phpmyadmin and the password you entered during installation you will be able to login. But you will not be able to create any databases! To solve the problem you need to edit the configuration file as root in the Terminal window:

sudo nano /etc/phpmyadmin/config.inc.php

Find the two lines containing // $cfg['Servers'][$i]['AllowNoPassword'] = TRUE; and remove the leading slashes to uncomment them. Both of them!

Then login to mysql from the command line and create a new user and grant that user all privileges:

sudo mysql
CREATE USER 'admin'@'localhost' IDENTIFIED BY '';
GRANT ALL PRIVILEGES ON *.* TO 'admin'@'localhost' WITH GRANT OPTION;
exit

Then go back to phpMyAdmin and try to login with username admin and no password. You should see all databases and be able to create new databases.

Index File Priority

The default location for web pages on Ubuntu/Linux Mint is /var/www/html. If you list the contents of that directory you will see it contains index.html containing the content of the Ubuntu Apache2 Default Page. Create a file named index.php in that directory with the following content:

<?php echo phpinfo();

Reload localhost. There is no change! Enter localhost/index.php in the URL bar and you will see a page containing PHP Version information. This behaviour is controlled by the default Apache configuration which it can be changed by enabling the Apache dir module and editing its configuration:

sudo a2enmod dir
sudo nano /etc/apache2/mods-enabled/dir.conf

Move index.php to the front of the list. Then restart Apache:

sudo systemctl restart apache2

This time using localhost alone in the URL bar you should see the content of the index.php file, a PHP Information page.

Virtual Hosts

In a default Linux installation the system files are in the root folder (/) and user data files are in the home folder (/home/myusername). This is a potential because the default Apache user, www-data, may not have appropriate permissions to create files in user file space. The best solution is to create Virtual Hosts.

First, a module is needed that allows Apache to switch its user and group to suit each user:

sudo apt-get install libapache2-mpm-itk
sudo a2enmod mpm_itk

Next, make a copy of the default site configuration file and edit it:

cd /etc/apach2/sites-available
sudo cp 000-default.conf username.localhost.conf
sudo nano username.localhost.conf

The default site configuration file contains comments to explain its content. They are left out in the illustration below. Uncomment the ServerName line and change all instance of username to your own username.

<VirtualHost *:80>
        ServerName username.localhost
        ServerAdmin webmaster@localhost
        DocumentRoot /home/username/public_html
        <IfModule mpm_itk_module>
                AssignUserId username username
        </IfModule>
        <Directory /home/username/public_html/ >
                Options Indexes FollowSymLinks
                AllowOverride None
                Require all granted
        </Directory>
        ErrorLog ${APACHE_LOG_DIR}/error.log
        CustomLog ${APACHE_LOG_DIR}/access.log combined
</VirtualHost>

Enable the new site and restart Apache:

sudo a2ensite username.localhost
sudo systemctl reload apache

Make an entry in the /etc/hosts file to add an entry for the new virtual host. Otherwise your browser will be looking for it on the internet.

sudo nano /etc/hosts

When done it will look something like this:

127.0.0.1       localhost
127.0.0.1       username.localhost
127.0.1.1       hostname

# The following lines are desirable for IPv6 capable hosts
::1     ip6-localhost ip6-loopback
fe00::0 ip6-localnet
ff00::0 ip6-mcastprefix
ff02::1 ip6-allnodes
ff02::2 ip6-allrouters

Hostname: This is the name you gave to your computer when you installed Linux. You will need it shortly. You can change it if you wish - but best to read up on that and do it first.

All being well, with a URL of the form username.localhost you will see a directory listing of your public_html directory. Public display of directory listings is considered bad practice, a security risk, and usually disallowed by another Apache configuration setting. However, for a personal site on a personal computer used for development and testing it is very useful. Many different sites may be set up in different sub-directories. For example, Joomla 4 and Joomla 5 sites, Bulletin Boards, Wikis and so on. When you have a lot of test sites it is difficult to remember all of the subdirectory names!

Home Network Access

If you have another computer on your home network you would probably like to access your Linux site from there too. To make that work you need another virtual host. Copy and edit the one just made:

cd /etc/apache2/sites-available
sudo cp username.localhost.conf username.conf
sudo nano username.conf

Change the ServerName from username.localhost to username.hostname and then enable the new virtual site and restart Apache.

sudo a2ensite username
sudo apachectl restart

Go to your other computer on the home network and edit its personal hosts file. For example, on a Mac edit /private/etc/hosts and add the following line at the bottom:

192.168.178.20 username.hostname www.username.hostname

Where 192.168.178.20 is the IP address of your Linux computer.

Now on your second computer you should be able to access the web server on you Linux computer by entering username.hostname in the URL bar of your browser.

Partition Notes

Software installed using the Synaptic Package Manager is usually in the Linux root directory (/). User data is located in the home directory (/home). In a simple installation these directories are in the same physical disk partition.

In a more complex installation, perhaps with the option to boot different operating systems (Windows or Linux) or different versions of the same operating system, the root and user data are often in separate partitions. This allows access to the same user data from each operating system.

There is a snag: a Joomla site located in a /home/username directory needs database data that is usually in the root directory, specifically in /var/lib/mysql. You can move the MySQL/MariaDB data directory to a location available to both operating systems, either in the /home partition or in a separate partition. This tutorial describes how to Change the MySQL Data Directory in Ubuntu and Debian Linux. That needs to be done for each operating system but is not covered here.

WAMP vs XAMPP

In these acronyms W stands for Windows and X stands for Cross-Platform (Linux, Mac and Windows). The remaining letters stand for Apache (the Web Server), MySQL or MariaDB (the Database Server) and PHP (the scripting language used for Web development). The final P in XAMPP stands for Perl (another scripting language).

You can install each of these software packages independantly on your platform of choice. However, it is often more convenient to install a package that bundles all of the separate items together. So XAMPP works on the three major platforms but WAMP only works on Windows. Aprt from that, they do the same job. They allow you to install and manage your local development environment.

XAMPP is covered in a separate article:

• Local Hosting with XAMPP for Linux, Mac and Windows.

There is a comparison available:

• Umbrella: WAMP vs XAMPP

Local Hosting with WampServer

If you are using a Windows computer set up a development environment using WampServer downloaded from the first of the following articles:

• Wampserver
• Wampserver Forum
• Wampserver from Aviatechno

ToDo: Installation

Getting Joomla running on your computer needs four things -> downloading and configuring a web server Apache or nginx, a database service like MySQL or MariaDB, and surely we need PHP and Joomla. To get all these different pieces to actually communicate with each other, most of us rely on bundled software like XAMPP, Laragon, or FlyEnv.

However, traditional setups can easily lead to port conflicts or database servers that mysteriously refuse to start. When a local server crashes, you might find yourself manually downloading and reinstalling entire Joomla sites over and over again just to test a single PR, potentially losing your work while fixing a bug. It consumes valuable time, and the fixes are usually just temporary band-aids.

The switch to Docker (Learn about Docker) With Docker, you can skip the manual configuration entirely. Instead of installing web servers directly onto your computer, you just write a single "recipe" file. Docker automatically downloads, isolates, and connects everything in the background. If something breaks, you don't reinstall your whole setup; you simply restart the container.

In this guide, you will learn the simplest way to get a local Joomla environment running using Docker, allowing you to spend less time fixing servers and more time contributing.

Prerequisites

You only need one thing installed before we start: Docker Desktop.

• Download it from docker.com and run the installer
• On Windows, leave the "Use WSL 2 instead of Hyper-V" option checked - it makes things faster
• Open Docker Desktop and wait until the bottom-left corner shows a green Engine running status.

That's it.

The docker-compose.yml File

When you need multiple services to communicate - like a web server (Apache/Nginx), PHP, and a database (MySQL/MariaDB) - you use a special orchestration file called docker-compose.yml. This file acts as the blueprint for your project, defining all the services required and how they collaborate. (The official Docker Joomla image is actually built on top of a PHP and Apache image. This means that by using just this one Joomla image, you get PHP, Apache, and Joomla all bundled together)

First, create a new folder on your computer for your project (for example, on your Desktop, make a folder called joomla-docker).

Inside that folder, create a new text file and name it exactly this:

docker-compose.yml

Open that file in any text editor (like VS Code or Notepad), paste the following code exactly as it is, and save it:

services:
  joomla:
    image: joomla:latest
    ports:
      - "8080:80"
    environment:
      - JOOMLA_DB_HOST=db
      - JOOMLA_DB_USER=joomla
      - JOOMLA_DB_PASSWORD=joomlapass
      - JOOMLA_DB_NAME=joomladb
    depends_on:
      - db
  db:
    image: mariadb:10.11
    environment:
      - MYSQL_ROOT_PASSWORD=rootpass
      - MYSQL_DATABASE=joomladb
      - MYSQL_USER=joomla
      - MYSQL_PASSWORD=joomlapass
    volumes:
      - db_data:/var/lib/mysql
volumes:
  db_data:

Starting the Environment

Open your terminal (or PowerShell on Windows), navigate to your joomla-docker folder, and run:

docker compose up -d

The first time you run this, Docker will download the Joomla and MariaDB images which might take a minute or two depending on your internet speed. After that, every subsequent start is almost instant as you can see below.

 

The Joomla Installer

Open your browser and go to http://localhost:8080. You should see the Joomla installation screen.

Fill in your site name and admin details on the first screen.

 

When you reach the Database Configuration screen, this is where most people get stuck:

Do not type localhost as the host name.

Because the database is running in its own container, Joomla needs the container's service name — not localhost. Use these exact values:

• Database Type: MySQLi
• Host Name: db
• Username: joomla
• Password: joomlapass
• Database Name: joomladb

Click through, finish the installation, and you're done.

When you're finished working for the day, run docker compose stop to pause the containers and free up memory. Your site will be exactly where you left it next time.

---

Common Issues

• The page at localhost:8080 won't load right after starting: The database container takes a few seconds to finish initialising. Wait 30 seconds and refresh.
• Port 8080 is already in use: Change "8080:80" to "8081:80" in the compose file and access it at localhost:8081 instead.
• Containers started but Joomla shows a database error: Double-check that your Host Name in the installer is db and not localhost.

Pro-Tip: Accessing the Joomla Files for Development

Right now, your Joomla site is running, but the actual PHP files are hidden inside the Docker container. If you want to contribute to Joomla, test PRs, or write your own plugins, you need those files on your computer so you can open them in VS Code or your favorite editor.

To sync the files from the container to your local hard drive, you just need to add two lines (volumes: ) and (- ./site_joomla:/var/www/html) to the joomla section of your docker-compose.yml file as shown below:

services:
  joomla:
    image: joomla:latest
    ports:
      - "8080:80"
    volumes:
      - ./site_joomla:/var/www/html
    # ... (rest of your settings)

What this does: 

The next time you run docker compose up -d, Docker will automatically create a folder called site_joomla right next to your compose file. It will copy the entire Joomla core (including the administrator dashboard, components, and templates) into that folder.

Any code changes you make in that folder on your computer will instantly update inside the running container! You are now fully set up for local development.

Bonus Tip 1: Testing Specific Joomla and PHP Versions

When testing PRs, maintainers will often ask you to test against specific PHP versions. With XAMPP, downgrading or upgrading PHP is a nightmare. With Docker, it takes two seconds.

Instead of using image: joomla:latest in your docker-compose.yml, you can specify exact versions using tags. For example, if you need to test Joomla 5.2 on PHP 8.3, just change that one line to: image: joomla:5.2-php8.3-apache

Run docker compose up -d again, and Docker will instantly swap out your server environment. You can find all the available version tags on the Official Joomla Docker Hub page.

Bonus Tip 2: Adding phpMyAdmin

If you are coming from XAMPP, you might miss having a visual interface to look at your database. You can easily add phpMyAdmin to your setup by adding a new service block to the bottom of your docker-compose.yml file:

phpmyadmin:
  image: phpmyadmin/phpmyadmin:latest
  ports:
    - "8081:80"
  environment:
    - PMA_HOST=db
  depends_on:
    - db

Restart your containers, and you can now access phpMyAdmin by going to http://localhost:8081 in your browser. Just log in with joomla as the username and joomlapass as the password.

Laragon is a lightweight Windows tool that handles Apache, MySQL, and PHP in one simple install. No config files, no manual setup - just download, run, and start building/testing Joomla. See this article in the Joomla Community Magazine: Laragon: The Effortless, High-Performance AMP Server for Windows.

This guide gets you from scratch to a working local Joomla site, and also covers a small UI quirk in the latest version that is easy to fix once you know what is happening.

Downloading and Installing Laragon

To get started, head over to the official Laragon download page. Download the Laragon Full version (currently v8.6.1), as it includes everything you need (like Apache, MySQL, and the latest PHP versions)- right out of the box. Alternatively, you can click here to download the installer directly.

Once the .exe file is downloaded, double-click it to begin the installation.

Note on Windows Defender: Because Laragon is a powerful developer tool, Windows Defender SmartScreen might block it from starting and show a blue warning screen. This is normal - Simply click More info, and then click the Run anyway button that appears at the bottom.

Click through the setup wizard. The default settings are perfectly fine, but keep an eye out for these two important details:

1. Destination Location: Leave the installation folder as C:\laragon. Installing it deep inside your Program Files or Documents can sometimes cause permission issues later.

2. Setup Options: Make sure the Auto virtual hosts checkbox is ticked. This is the feature that gives your local Joomla site a clean address (like http://myjoomla.test) instead of a raw IP address.
   
   

Once the installation finishes, restart your computer. (the installer wizard will prompt you to do the same)

 

Starting Your Server and Firewall Permissions

Open Laragon from your Start menu and click the Start All button.

Because this is your first time running a local server, Windows needs to verify that it is safe. You will see Windows Defender Firewall prompts pop up asking for network access for services like Apache HTTP Server, MySQL, and Mailpit.

• Simply click Allow access on each of these prompts.

Once allowed, Laragon will start your local environment. You will know it is working when you see the Apache and MySQL port numbers appear in the Laragon window.

 

The "Already Running" Quirk (and How to Fix It)

When you are done working, you might click "Stop All" to turn off Apache and MySQL, and then click the "X" in the top right corner to close the Laragon window.

Here is the quirk: clicking the "X" does not completely shut down Laragon. It keeps running silently in the background. If you try to open the Laragon app again from your Start menu or desktop, you will see a yellow warning in the bottom right corner of your screen that says: "Laragon is already running!"

The Trap: If you click the "X" on that tiny yellow warning to close it, the main Laragon window will also disappear, leaving you completely unable to access the control panel. (Note: You might also occasionally see a license pop-up appear that causes the interface to freeze in a similar way).

The Fix: If your interface disappears or freezes, you just need to force-close the background process and start fresh. It is very simple:

1. Press Ctrl + Shift + Esc on your keyboard to open the Windows Task Manager.

2. Look(Search) for Laragon in the list of running processes.

3. Right-click on it and select End task.

That's it! You have safely killed the stuck background process. You can now open Laragon from your Start menu, and it will load up perfectly, allowing you to click "Start All" without any errors.

Handling the License Pop-Ups (The "Nag" Screens)

Laragon is free to use for non-commercial development and testing without purchasing a license. However, after using the app for a little while, you will likely encounter a "License Key" prompt encouraging you to support the project.

Because you are using the free version, you can simply dismiss these screens, but there is a specific sequence to expect:

1. The main License Key window will appear over your Laragon interface. Click the Close text or the 'X'.
   
   
   

2. Immediately after closing it, a second Warning pop-up will appear, reminding you that Laragon is running without a license. Click OK or the 'X'.
   
   
   

3. Once you close that second warning, Laragon might automatically open your web browser and redirect you to https://laragon.org/key. You can simply close that browser tab.

4. When you go back to the Laragon interface and click Start All to turn your server back up, you might have to click through those exact same two pop-ups one more time.

After dismissing them this second time, the pop-ups will disappear, and you are completely free to use Laragon!

(Note: If at any point during these pop-ups your Laragon interface freezes and becomes unclickable, just remember the Ctrl + Shift + Esc Task Manager trick from the previous step to end the background process and start fresh)

Creating a Database for Joomla

Before installing Joomla, you need a blank database to store its data. Laragon includes a built-in database manager called HeidiSQL, so everything you need is already there.

1. Make sure your Laragon services are running (click Start All).

2. Click the Database button on the main Laragon interface.

3. A Session Manager window will open. Laragon automatically fills in the default local credentials for you (User: root, Password: [leave blank]).

4. Click the Open button at the bottom.
   
   Troubleshooting: "Access denied for user 'root'@'localhost'" Error: If you click the Open button and immediately get a connection failed error, don't worry! This usually means you have another MySQL program (like XAMPP or MySQL Workbench) running in the background, which is blocking Laragon's access to the database port (Port 3306).
   
   
   

   The Fix:

   1. Press the Windows key, type Services, and hit Enter.

   2. Scroll down the list to find MySQL, MySQL80, or MariaDB.

   3. Right-click the running service and select Stop.

   4. Go back to Laragon, click Stop All, then Start All, and try clicking Open in the Session Manager again. It should connect without any error.

5. Once you are successfully connected and inside the HeidiSQL database manager, look at the left-hand column. Right-click on the server name (usually labeled Laragon.MySQL or 127.0.0.1).

6. Hover over Create new, and select Database.

7. A small prompt will appear. Type a simple name for your database in the "Name" field (for example: joomla_dev). You can leave the "Collation" dropdown on its default setting.

8. Click OK.

You will see your new database appear in the list on the left. That's it! You can now close the database manager window completely.

Getting Your Joomla Files

Now that your server and database are ready, it’s time to get the Joomla files in place. How you do this depends entirely on what you want to achieve with this local setup:

Method 1: For Building a Standard Website If you just want to build a website or test out extensions, you need the standard stable release.

• Head over to the official Joomla download page and download the latest Full Package .zip file.

Method 2: For Testing Community PRs (Patch Testing) If your goal is to help the community by testing patches and Pull Requests, you need a pre-built package that contains the absolute latest code.

• The Nightly Build: Download the latest Nightly Build .zip from Nightly Builds. These are generated every night and are perfect for use with the Joomla Patch Tester component.

• The PR Prebuilt Package: Alternatively, if you are testing a specific PR on GitHub, scroll to the bottom of the PR page, click Show all checks, and look for the Download Prebuilt packages link.
  

Method 3: For Contributing Core Code If you plan to write code and submit your own Pull Requests, you need the raw, uncompiled source code.

• Clone the Joomla CMS GitHub repository directly into your Laragon environment using Git.

• Important: A raw GitHub clone will not run out of the box - You must open Laragon's Terminal and run composer install and npm ci inside your folder to build the PHP dependencies and CSS/JS assets. (Because you installed the Full version of Laragon, Composer and NPM are already installed on your system).
  
  

Placing the Files in Laragon:

No matter which method you chose, getting the files running in Laragon is the exact same process:

1. Open your Laragon interface and click the Root button. This automatically opens the C:\laragon\www folder on your computer.

2. Inside this www folder, create a new folder for your project. Keep the folder name simple, lowercase, and without spaces (for example: joomla_dev or joomla_pr_test).

3. Place your Joomla files inside this new folder. (If you downloaded a .zip in Method 1 or 2, extract all the contents directly into this folder. If you are using Git in Method 3, clone the repo into this folder).

4. Because you enabled "Auto virtual hosts" during installation, Laragon automatically uses your folder name to create your local web address. So, a folder named joomla_dev becomes accessible in your browser at http://joomla_dev.test.
   
   Tip: Keep Your Environments Clean: It is a good idea to create different folders for different Joomla versions or specific PR tests (e.g., one folder named joomla5_stable and another named joomla6_dev). Laragon will happily run them all side-by-side with their own clean .test URLs, preventing your code and databases from getting mixed up!
   
   
   
   

Running the Joomla Installer

You have your database, and your Joomla files are sitting in their new folder (for example, C:\laragon\www\joomla_dev). Now it’s time to actually install Joomla!

Crucial Step: Reload Apache! If Laragon was already running while you created your new project folder, Laragon doesn't know the folder exists yet.

• Open your Laragon interface.

• Click the "Reload" on top-right. (This forces Laragon to scan the www folder and generate the new http://joomla_dev.test address).

Completing the Setup:

1. Open your web browser and type in your project's auto-generated URL (e.g., http://joomla_dev.test).

2. You should immediately see the Joomla Web Installer page.

3. Choose your language and enter a name for your Joomla site.

4. Set up your Super User account (remember these login details, you will need them to access the Joomla administrator dashboard!).

5. On the Database Configuration screen, enter the credentials for the Laragon database you created earlier:

   • Database Type: MySQLi (Default)

   • Host Name: localhost

   • Username: root

   • Password: [Leave this completely blank]

   • Database Name: The exact name you typed into HeidiSQL earlier (e.g., joomla_dev).
     

6. Click Install Joomla.

Once the progress bar finishes, you will see a success message - You can now click Open Site to view your live local website, or Open Administrator to log into the Joomla backend.

That's it - your local Joomla site is live and ready to use.