Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 37 ยท Installation and Admin

Set Up a Local Environment for Joomla

Prepare a local web server, PHP and database for Joomla with XAMPP, Laravel Herd, Docker or a hosting account, and check PHP extensions with a runnable checker.

You learn Joomla fastest by clicking through a real installation, and the safest place for that is your own computer. A local environment lets you experiment, break things and start over without any risk to a live website. This lesson shows the choices, what each one needs, and how to prepare the folder and database for the installer in the next lesson.

Joomla cannot run in this site's browser sandbox, so the steps below are described in words and read-only code. The runnable parts are stand-ins that check your setup information, such as the list of PHP extensions.

What you need locally

A local Joomla site needs the same three layers as a live one: a web server, PHP and a database. Pick one of these routes.

Four ways to get a local server

XAMPP or MAMP One installer: Apache, PHP, MariaDB
Laravel Herd Fast PHP and Nginx for Windows and macOS
Docker Containers, same setup for a whole team
Shared hosting A real server with a free trial or cheap plan

All four work. Pick the one you already know.

1 / 2
  • XAMPP (Windows, macOS, Linux) bundles Apache, PHP and MariaDB. You start the Apache and MySQL modules in its control panel and place your site in the htdocs folder.
  • Laravel Herd runs PHP and Nginx with almost no configuration; your site folders appear at addresses like http://mysite.test. It does not include a database, so install MySQL or MariaDB separately (for example with DBngin or a standalone MariaDB).
  • Docker suits teams: a compose file describes the web server, PHP and database so that everybody gets the same environment. Joomla is also published as an official container image.
  • Hosting gives you a real server. Many hosts offer one-click Joomla installers, which are convenient but hide the steps this course wants you to learn.

If your computer already runs another server on port 80 (for example a different XAMPP project), you can change the port or use another tool.

Prepare the folder and the database

The installer needs two things from you before it starts: a folder with the Joomla files, and an empty database with a user.

  1. Download Joomla from the official site (joomla.org) as a full package ZIP. Use only that official source: copies from other sites can contain malware.
  2. Create a folder in your web root, for example htdocs/joomla (XAMPP) or a site folder in Herd, and extract the ZIP into it, so index.php and the administrator folder sit at its top level.
  3. Create a database with phpMyAdmin (included with XAMPP) or the command line. Choose the collation utf8mb4_unicode_ci so that every language and emoji are stored correctly:
SQL
CREATE DATABASE joomla_local CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'joomla_user'@'localhost' IDENTIFIED BY 'a-long-random-password-here';
GRANT ALL PRIVILEGES ON joomla_local.* TO 'joomla_user'@'localhost';
FLUSH PRIVILEGES;

On a local-only machine you may use the default root user with an empty password, but a dedicated user is a good habit and is mandatory on real servers. The user needs rights only on this one database.

  1. Check PHP: open the PHP configuration (php.ini) and make sure the needed extensions are enabled (lines such as extension=gd without a leading semicolon). Restart the web server after changes.
flowchart LR
    A["Install server<br/>XAMPP / Herd / Docker"] --> B["Extract Joomla ZIP<br/>into the site folder"]
    B --> C["Create empty database<br/>and user"]
    C --> D["Open the site in a browser<br/>and run the web installer"]

The four preparation steps before the installer.

Check your PHP extensions

You can list loaded PHP extensions with the command php -m in a terminal. The stand-in checker below takes that text and compares it with the extensions Joomla needs. Paste your own php -m output into the string to try it.

JS Stand-in: check the output of php -m

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The checker normalizes the lines (trim, lowercase), drops the [PHP Modules] headings, and uses a Set for quick lookups. Whenever something is missing, you enable it in php.ini and restart the server. The recommended list is a guide, not a hard rule.

Check limits in php.ini

Large uploads and imports fail silently when limits are too low. The values below are common starting points for development; production values depend on your site.

JS Stand-in: compare php.ini limits

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Notice that upload_max_filesize should be no bigger than post_max_size, because a form post that contains the file must fit in the post limit.

Common problems

  • Port already in use. Another program holds port 80 or 3306. Stop it or change the port, and include the port in the URL, for example http://localhost:8080/joomla.
  • Blank page after extracting. Often a PHP extension is missing or PHP is too old; look at the PHP error log.
  • Cannot connect to the database. Check host (localhost or 127.0.0.1), user name, password and that the database exists.
  • Files are not writable. On Linux and macOS the web server user must be able to write to the site folder during installation, because the installer creates configuration.php.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which collation is recommended for the Joomla database?

    utf8mb4 stores every Unicode character, including emoji and all languages.
  2. 2. Where should you download Joomla from?

    Unofficial packages can contain malicious code. Use the official download.
  3. 3. Which command lists the loaded PHP extensions?

    php -m prints the loaded modules, which you can compare with Joomla's requirements.
  4. 4. Why should a Joomla database user have rights only on its own database?

    Least privilege limits the damage of a leaked password.

Summary

  • A local server (XAMPP, Herd, Docker or a hosting account) lets you practise Joomla safely.
  • Prepare a site folder with the official Joomla files and an empty utf8mb4_unicode_ci database with its own user.
  • Verify PHP extensions with php -m and raise limits such as upload_max_filesize and memory_limit in php.ini.
  • Most setup problems come from ports, missing extensions, wrong database details or file permissions.

Next: Run the Joomla Web Installer