Docker & Joomla
Present slides: https://slides.woluweb.be
This presentation was made at
- JoomlaDay France 2024 #jd24fr
1 Introduction
So many times I have seen people struggling on forums or elsewhere to configure a “local server”.
Actually, Docker is really the way to go because
- it is not only an easy & cool way to set up a “local server” to play / work with Joomla
- but once you can use it, you realize that it allows to set up any kind of tool / environment in less than 1 minute, without worrying for conflicts / versions / whatever
2 Demo
2.1 Prerequisite
Let’s suppose you have already installed Docker Desktop (or Docker Engine if you don’t wish/need the Graphical User Interface).
See the detailed installation procedures hereafter.
2.2 Example 1
See the corresponding video: https://youtu.be/-4WXIXQJWTU
As you can see, basically all it takes to get a Joomla website running locally is
- one little configuration file that you copy paste
- one command line
2.2.1 Have Joomla up and running
- Open Docker Desktop
- Go to the Official Image for Joomla on the Docker website: https://hub.docker.com/_/joomla
- Copy the
docker-compose.yml
example and save it in a local File calleddocker-compose.yml
(or better:compose.yaml
which is the latest standard) in a newly created Folder
- Open your Terminal in that given Folder and type the following Command
docker compose up --detach
- In Docker Desktop, you can see when your Containers are ready (it typically needs only a few seconds, except the first time where the different Images also need to be downloaded)
- Open your browser and go to
localhost:8080
(orhttp://127.0.0.1:8080
should localhost not be defined on your computer)… your Joomla website is ready (i.e. even already installed! You can log in with the username and password mentioned in theyaml
file)
(if all services are not ready yet, in your browser you could have a message like “Unable to connect” or “This site can’t be reached”. Just be a bit patient and refresh the page)
Notes:
- the
--detach
at the end of our Command means “Detached mode: Run containers in the background”.- d
is its short version - to know more about
docker compose up
, see https://docs.docker.com/reference/cli/docker/compose/up/
2.2.2 File Management
2.2.2.1 See the files within Docker Desktop
Now you probably want to access your Files, for example
- to edit a PHP file like
configuration.php
- to rename / delete images
- …
But as you might have noticed, the Joomla and the Database Files are not directly accessible via your regular File Manager. This is because Docker itself is managing all files (“self-managed”).
In Docker Desktop > Volumes, you can indeed see
- 1 Volume for
joomla_data
- 1 Volume for
db_data
Note: these are the names given arbitrarily in our yaml
file. You can, of course, give them any name you like!
There you can open each volume, navigate through the folders and even open files. But you cannot edit them.
2.2.2.2 Edit the files
To make things easy, simply install
- Visual Studio Code (which is free, but feel free to use PHPStorm if you have a licence)
- the following Extensions for Visual Studio Code
- Docker by Microsoft
“Makes it easy to create, manage, and debug containerized applications” - Dev Containers by Microsoft
“Open any folder or repository inside a Docker container and take advantage of Visual Studio Code’s full feature set”
- Docker by Microsoft
Accessing the Folders and Files is now easy
- Open Visual Studio Code
- Click on the Docker icon in the left bar (added by the Docker Extension). There you see a.o.
- the Containers
- the Images
- the Volumes
- …
- Open the Volumes, right-click on
joomla_data
and click onExplore in a Dev Container
(added by the Dev Containers Extension)
- Now you can do what you want, for example
4.1. Edit configuration.php
, change the row public $offline = false
to public $offline = true
and save. Now if you refresh your website in your browser localhost:8080
the website has indeed gone offline
4.2. If you go to Joomla’s back-end > Content > Media and upload Images, you will see them in Virtual Studio Code > Explorer
Tip 1: if you have made 1 or several changes to a File (even another day), you can simply go back to any Version simply with Virtual Studio Code: Explorer icon > Timeline
Tip 2: in Virtual Studio Code you also have a Terminal (quite simply to be found under the Terminal menu item)
Tip 3: if you are in your terminal application and want to open Virtual Studio Code already placed in the current folder, simply type the following command:
code .
2.2.3 Persistence
You can close Docker Desktop any time: when you will reopen it, your website will again be up and running (“persistency”).
But if you want to consume less memory, you can “turn off” your containers.
- either via Docker Desktop > Containers: Stop of even Delete
- either via your terminal in that given folder: type the following command:
docker compose down
After that, whenever you will run again
docker compose up --detach
Your website will be back.
Actually, as long as you don’t delete the Volumes joomla_data
and db_data
your website is still intact, ready to be run.
NB: under Docker Desktop > Images you will find all the Images that you already “downloaded”. You can safely delete those files: the only consequence is that they will be downloaded again if your ỳaml`requires them.
2.3 Example 2: customized environment
Let’s customize further our setup
- by default, we had the latest stable Joomla Version and some given PHP Version. Let’s suppose you want a specific Joomla Version and a specific PHP version
- by default, the database engine is mysql. Let’s suppose you want to use mariadb instead
- by default, the upload maximum file size is 2 Mb. Let suppose you want to increase it
Here is how we can easily achieve this
- just like in the previous example, create a new folder with the same file
compose.yaml
(new folder because otherwise we will be messing up the previously installed mysql with the newly installed mariadb for example). Then edit that file as follows - change
ìmage: joomla
intoimage: joomla:5.2-php8.3-apache
if you want Joomla 5.2 with PHP 8.3 (see https://hub.docker.com/_/joomla for all the available Tags) - change
image: mysql:8.0
intoimage: mariadb:10.5.26
to switch from MySQL 8.0 to MariaDB 10.5.26 - in order to change the upload maximum file size (or any parameter which belongs typically to php.ini actually)
- create a file called
php.ini
next tocompose.yaml
with the following content :
- create a file called
upload_max_filesize = 500M
post_max_size = 500M
- add the following line `- ./php.ini:/usr/local/etc/php/php.ini` after `- joomla_data:/var/www/html` (keeping the same indentation!)
That’s it!
By running docker compose up --detach
in this folder I will now have my customized environment.
2.4 Example 3: adding PHPMyAdmin
What if we also wanted to have PHPMyAdmin in order to be able to play directly with our database.
The official image is available here: https://hub.docker.com/_/phpmyadmin/
2.4.1 Occasionally
If we only need PHPMyAdmin occasionally then we can just launch it manually any time once your Joomla website is running.
See https://www.avonture.be/blog/docker-adminer-pgadmin-phpmyadmin
2.4.2 Systematically
If we want to have PHPMyAdmin systematically then all we have to do is to add a few lines in our compose.yaml
file.
- we add the
phpmyadmin
service. Note: we added there acondition: service_healthy
so thatphpmyadmin
only starts whendb
is ready - therefore, in the
db
service we have added ahealthcheck
block - and since we have now introduced that
healthcheck
concept, it also makes sense to add thecondition: service_healthy
for thejoomla
service
To know more about Startup Order, see https://docs.docker.com/compose/how-tos/startup-order/
services:
joomla:
image: joomla
restart: always
ports:
- 8080:80
environment:
JOOMLA_DB_HOST: db
JOOMLA_DB_USER: joomla
JOOMLA_DB_PASSWORD: examplepass
JOOMLA_DB_NAME: joomla_db
JOOMLA_SITE_NAME: Joomla
JOOMLA_ADMIN_USER: Joomla Hero
JOOMLA_ADMIN_USERNAME: joomla
JOOMLA_ADMIN_PASSWORD: joomla@secured
JOOMLA_ADMIN_EMAIL: joomla@example.com
depends_on: # new block - cfr the "healthcheck" under the db service
db:
condition: service_healthy
volumes:
- joomla_data:/var/www/html
networks:
- joomla_network
db:
image: mysql:8.0
restart: always
environment:
MYSQL_DATABASE: joomla_db
MYSQL_USER: joomla
MYSQL_PASSWORD: examplepass
MYSQL_RANDOM_ROOT_PASSWORD: '1'
healthcheck: # new block - cfr the "condition: service_healthy" of the "depends_on" block for joomla and phpmyadmin services
test: ["CMD", "mysqladmin" ,"ping", "-h", "localhost"]
timeout: 10s
retries: 10
volumes:
- db_data:/var/lib/mysql
networks:
- joomla_network
phpmyadmin: # new service
depends_on:
db:
condition: service_healthy
image: phpmyadmin/phpmyadmin:latest
restart: always
ports:
- '8081:80'
environment:
PMA_HOST: db
networks:
- joomla_network
volumes:
joomla_data:
db_data:
networks:
joomla_network:
Now when you run docker compose up --detach
you will notice that the joomla
and phpmyadmin
services will only start once the db
service shows “Healthy”.
- As previously
http://localhost:8080/
shows Joomla - And now
http://localhost:8081/
shows PHPMyAdmin- the port is
8081
because this is what we chose in ourcompose.yaml
file - the credentials to access our database are also defined in our
compose.yaml
file- MYSQL_USER: joomla
- MYSQL_PASSWORD: examplepass
- the port is
2.5 Example 4: all the Files in my own File Manager
In the previous example, we saw that even when our volumes (Files) are managed within Docker itself, we can still access them.
But sometimes you really want to have joomla_data
and db_data
as regular folders of your computer, so that you can access them directly with your regular File Manager.
2.5.1 Prerequisite
Let’s suppose Docker Engine is already installed (see the detailed installation procedures hereafter).
2.5.2 Configuration
- in a new Folder, create manually the 2 Folders
joomla_data
anddb_data
We don’t let Docker create them so that we are the Owners of those folders. Otherwise Docker will create them and be the owner, creating useless permission issues.
- in the same Folder, create the following
composer.yaml
File
services:
joomla:
image: joomla
restart: always
ports:
- 8080:80
environment:
JOOMLA_DB_HOST: db
JOOMLA_DB_USER: joomla
JOOMLA_DB_PASSWORD: examplepass
JOOMLA_DB_NAME: joomla_db
JOOMLA_SITE_NAME: Joomla
JOOMLA_ADMIN_USER: Joomla Hero
JOOMLA_ADMIN_USERNAME: joomla
JOOMLA_ADMIN_PASSWORD: joomla@secured
JOOMLA_ADMIN_EMAIL: joomla@example.com
user: "1000:1000" # added - use the command id -u and id -g to know your own userid:groupid
volumes:
- ./joomla_data:/var/www/html # added ./ at the start
networks:
- joomla_network
db:
image: mysql:8.0
restart: always
environment:
MYSQL_DATABASE: joomla_db
MYSQL_USER: joomla
MYSQL_PASSWORD: examplepass
MYSQL_RANDOM_ROOT_PASSWORD: '1'
user: "1000:1000" # added - use the command id -u and id -g to know your own userid:groupid
volumes:
- ./db_data:/var/lib/mysql # added ./ at the start
networks:
- joomla_network
# volumes:
# joomla_data:
# db_data:
networks:
joomla_network:
Note: anything after the symbol # is a comment made to highlight the difference with the original basic yaml
file, but, of course, all these comments can be deleted.
Compared to the original basic yaml
file, we have respectively
- in each section called
joomla
anddb
- added a line for
user:
. Use the commandid -u
andid -g
to know what is your User Id and your User Group.
In my case (and in many cases) it is1000
and1000
. So the full line isuser: "1000:1000"
- added
./
before each volume, meaning that Docker will point to the current Local Folder
- added a line for
- disabled the
volumes:
section because we are precisely using our own 2 Folders so Docker will not have to “manage” the volumes itself
2.5.3 Starting Docker Engine
On some operating systems, like Ubuntu and Debian, the Docker daemon service starts automatically when booting.
Otherwise, use the following command to start it manually:
sudo systemctl start docker
See https://docs.docker.com/engine/daemon/start/ for more details.
2.5.4 Execution
Since Docker Engine was executed with sudo
privileges (i.e. as root user), we also have to use sudo
on our usual command:
sudo docker compose up --detach
Open your browser and go to localhost:8080
… your Joomla website is ready.
To close your containers (but keep your website intact), simply do
sudo docker compose down
3 Installing Docker Desktop
Let’s see how to install Docker Desktop, namely Docker with Graphical User Interface
- it is indeed probably easier / more comfortable if you have no/little experience with Docker
- but strictly speaking you can, of course, also always use Docker Engine, namely Docker without Graphical User Interface
3.1 on Windows
The best way is to first install WSL2 (Windows Subsystem for Linux)
You will find enough documentation online, for example
3.2 on Linux (Ubuntu, …)
Let’s take the example of Ubuntu.
See
- https://docs.docker.com/desktop/install/linux/ for Linux in general
- https://docs.docker.com/desktop/install/linux/ubuntu/ for Ubuntu in particular
Short version :
- Set up Docker’s apt repository as explained on https://docs.docker.com/engine/install/ubuntu/
- Download the appropriate version, in my case
docker-desktop-amd64.deb
- Install
sudo apt update
sudo apt install ./docker-desktop-<arch>.deb
where <arch>
is in my case amd64
of course.
3.3 Launch Docker Desktop
You can launch Docker Desktop
- either via its icon
- either via the following command line:
systemctl --user start docker-desktop
Note: if you are running Ubuntu 24.04, before launching Docker Desktop you need to run
sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
after each reboot (as explained in the Prerequisites on https://docs.docker.com/desktop/install/linux/ubuntu/)
3.4 Docker Desktop - sign in
Creating an account is not necessary but has advantages.
But note: before being able to “Sign in” you need to do the following:
https://docs.docker.com/desktop/get-started/#credentials-management-for-linux-users
4 Installing Docker Engine
4.1 On Ubuntu
Note: when using Docker Desktop on Ubuntu, I personally always run into Permission issues. So for this scenario we will now use Docker Engine instead of Docker Desktop [if you can help me having to make it work with Docker Desktop, please get in touch!]. It is also the opportunity to give a try to Docker Engine.
In the case of Ubuntu, the procedure is described here: https://docs.docker.com/engine/install/ubuntu/
Step 1 “Set up Docker’s apt repository.” was already done above, so I can directly jump to Step 2:
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
4.2 Manage Docker as a non-root user
If you want to manage Docker as a non-root user please follow those instructions:
https://docs.docker.com/engine/install/linux-postinstall/
Note: in the context of this presentation, we skip this because we will simply manage Docker as root user (using sudo
preface our Commands)
4.3 A few useful command
docker volume list
docker container list
5 Useful Links
There is a “Docker Stuff” group on Joomla’s Mattermost: https://joomlacommunity.cloud.mattermost.com/main/channels/docker-stuff
5.1 Useful Docker Images
Databases
- https://hub.docker.com/_/mariadb https://mariadb.org/mariadb/all-releases/
- https://hub.docker.com/_/mysql
- https://hub.docker.com/_/postgres
More generally, see https://hub.docker.com/
5.2 Christophe Avonture’s presentations around Docker
In English
- https://www.avonture.be/blog/docker-joomla/ part 1
- https://www.avonture.be/blog/docker-joomla-part-2
- https://www.avonture.be/blog/docker-joomla-restore-jpa
- https://www.avonture.be/blog/install-docker/
- https://www.avonture.be/blog/docker-php-ini/
- https://www.avonture.be/blog/docker-volumes/
- https://www.avonture.be/blog/docker-wordpress/
In French #jd22fr
6 DPDocker by Allon Moritz
Very useful for Joomla testers and/or developers
https://github.com/Digital-Peak/DPDocker
6.1 Installation
In a Folder, type
git clone https://github.com/Digital-Peak/DPDocker.git
This creates a DPDocker Folder.
Go to that folder in your terminal.
6.2 Example - testing a Pull Request
One of the Tools of DPDocker is “joomla-pr”:
https://github.com/Digital-Peak/DPDocker/tree/main/joomla-pr
Let’s try this. Go to https://github.com/joomla/joomla-cms and click on the “Pull Request” Tab.
Identify a Pull Request (PR), for example https://github.com/joomla/joomla-cms/pull/44223. So the ID of this Pull Request is 44223
joomla-pr/run-joomla-pr-webserver.sh 44223 -db mysql -php 8.1
Runs the web server for pr 44223 on a mysql database with PHP 8.1.
http://localhost:8090/pr/44223/administrator now shows the website.
Press CTRL+c to Stop the Container.
7 Special thanks
On this special occasion, I would like to express my gratitude to Christophe Avonture aka cavo789 for
- having created the Joomla User Group which was my first contact with the Joomla Community
- having pushed me to attend my very first JoomlaDay (which changed my life)
- initiating me to Docker!
8 Get in touch
Any suggestion about this presentation?
Please feel free to contact me. I’ll be happy to keep improving it 🙂
Marc Dechèvre | woluweb
+32 474 37 13 12 | +32 2 772 58 69