DEV Community: Christophe Avonture

Linux Makefile - Adding a help screen

Christophe Avonture — Mon, 25 Dec 2023 16:56:55 +0000

By using a makefile, you know it already, you can gather in one place a lot of actions like make bash, make build, make deploy, ... just like I do when working on this blog (see my makefile on https://github.com/cavo789/blog/blob/main/makefile).

What's really nice is being able to type make at the command line without any other options and then get a screen with lists of existing commands and a short one-line explanation.

That's what we'll be looking at in this article.

Prerequisites - Install GNU Make if needed

We will use GNU make so you need to have it.

Please run which make in your Linux console to check if make is already installed. If so, you will get f.i. /usr/bin/make as result.

If you got make not found, please run sudo apt-get update && sudo apt-get -y install make to install it.

Prerequisites - Create a sample file

For the demo, please start a Linux shell and run mkdir -p /tmp/makefile && cd $_ to create a folder called makefile in your Linux temporary folder and jump in it.

Please create a new file called makefile with this content:

SHELL:=bash

COLOR_YELLOW:=33

.PHONY: bash
bash:
 @printf "\e[1;${COLOR_YELLOW}m%s\e[0m\n\n" "Start an interactive shell in the Docker container; type exit to quit"

.PHONY: code
code:
 @printf "\e[1;${COLOR_YELLOW}m%s\e[0m\n\n" "Open the blog in Visual Studio Code"

.PHONY: build
build:
 @printf "\e[1;${COLOR_YELLOW}m%s\e[0m\n\n" "Generate a newer version of the build directory"

.PHONY: deploy
deploy: build
 @printf "\e[1;${COLOR_YELLOW}m%s\e[0m\n\n" "Deploy static pages to the webserver"

.PHONY: install
install:
 @printf "\e[1;${COLOR_YELLOW}m%s\e[0m\n\n" "Generate a newer version of the build directory"

.PHONY: start
start:
 @printf "\e[1;${COLOR_YELLOW}m%s\e[0m\n\n" "Open the blog (http://localhost:3000)"

.PHONY: watch
watch:
 @printf "\e[1;${COLOR_YELLOW}m%s\e[0m\n\n" "Run Docusaurus watcher and open the blog on the localhost. When done, just start a browser and surf to http://localhost:3000"

The indentation in a makefile SHOULD BE made using tabs and not spaces, this is crucial. So please make sure, if your file didn't work, you know what to do.

That file contains a few targets (=actions) and a simple printf statement to display a text. Except echoing something into the console that makefile does nothing.

❯ ls -alh

total 920K
drwxr-xr-x  2 christophe christophe 4.0K Dec  10 12:19 .
drwxrwxrwt 17 root       root       908K Dec  10 12:19 ..
-rw-r--r--  1 christophe christophe 1.4K Dec  10 12:19 makefile

Adding the default action

We're ready to start our implementation.

We have to do three things for this:

Add a default: help action
Add a help: target (a target is, in the Make terminology an action)
Edit each target and add a small description.

Step 1 - Adding the default action

In the absence of a default: action defined in the file, like in your example, the first action will be executed.

So, right now, if you run make (without any other arguments), you'll get the Start an interactive shell... message, that's the result of the bash: target; the first in the file

❯ make

Start an interactive shell in the Docker container; type exit to quit

Please edit the file and add the highlighted line below:

SHELL:=bash

// highlight-next-line
default: help

COLOR_YELLOW:=33

.PHONY: bash
bash:
 @printf "\e[1;${COLOR_YELLOW}m%s\e[0m\n\n" "Start an interactive shell in the Docker container; type exit to quit"

Step 2 - Adding the help target

Still in your editor, please add the highlighted block below; the position where you'll copy/paste it is not important but, logically, let's put this new action as the first since it's the one that will be executed by default.

SHELL:=bash

default: help

COLOR_YELLOW:=33

// highlight-next-line
.PHONY: help
// highlight-next-line
help: ## Show the help with the list of commands
    // highlight-next-line
 @clear
    // highlight-next-line 
 @awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n  make \033[36m<target>\033[0m\n\n"} /^[a-zA-Z_-]+:.*?##/ { printf "  \033[36m%-20s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[0;33m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)
    // highlight-next-line
 @echo ""

Right now, if you type make on your console, you'll get this:

Usage:
  make <target>

  help                  Show the help with the list of commands

Step 3 - Add a description for each target

Take a look on your new help target: the description Show the help with the list of commands is prefixed by a double #. This is how to add a description.

// highlight-next-line
help: ## Show the help with the list of commands

So, you've to edit your makefile for the last time, and, for each target, add a ## a small, one line, description text; like below, our final file:

SHELL:=bash

COLOR_YELLOW:=33

.PHONY: help
help: ## Show the help with the list of commands
 @clear
 @awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n  make \033[36m<target>\033[0m\n\n"} /^[a-zA-Z_-]+:.*?##/ { printf "  \033[36m%-20s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[0;33m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)
 @echo ""

.PHONY: bash
bash: ## Open an interactive shell in the Docker container
 @printf "\e[1;${COLOR_YELLOW}m%s\e[0m\n\n" "Start an interactive shell in the Docker container; type exit to quit"

.PHONY: code
code: ## Open Visual Studio Code
 @printf "\e[1;${COLOR_YELLOW}m%s\e[0m\n\n" "Open the blog in Visual Studio Code"

.PHONY: build
build: ## Generate a newer version of the build directory
 @printf "\e[1;${COLOR_YELLOW}m%s\e[0m\n\n" "Generate a newer version of the build directory"

.PHONY: deploy
deploy: build ## Deploy static pages to the webserver
 @printf "\e[1;${COLOR_YELLOW}m%s\e[0m\n\n" "Deploy static pages to the webserver"

.PHONY: install
install: ## The very first time, after having cloned this blog, you need to install Docusaurus before using it.
 @printf "\e[1;${COLOR_YELLOW}m%s\e[0m\n\n" "Generate a newer version of the build directory"

.PHONY: start
start: ## Start the local webserver and open the webpage
 @printf "\e[1;${COLOR_YELLOW}m%s\e[0m\n\n" "Open the blog (http://localhost:3000)"

.PHONY: watch
watch: ## Start the Docusaurus watcher. Listen any changes to a .md file and reflect the change onto the website
 @printf "\e[1;${COLOR_YELLOW}m%s\e[0m\n\n" "Run Docusaurus watcher and open the blog on the localhost. When done, just start a browser and surf to http://localhost:3000"

And now, by running make you'll get a nice help screen:

Usage:
  make <target>

  help                  Show the help with the list of commands
  bash                  Open an interactive shell in the Docker container
  code                  Open Visual Studio Code
  build                 Generate a newer version of the build directory
  deploy                Deploy static pages to the webserver
  install               The very first time, after having cloned this blog, you need to install Docusaurus before using it.
  start                 Start the local webserver and open the webpage
  watch                 Start the Docusaurus watcher. Listen any changes to a .md file and reflect the change onto the website

As you can see, the order of targets respect the order in your file. help is displayed first because it's the first target in the file so, think to reorder targets in your file based on your logic (f.i. alphabetically).

Step 4 - Add a subtitle between each "main section"

Imagine you have dozens of shares... It would be nice to group them into sections: everything concerning your application, everything relating to your database, actions of the Code Analysis type, and so on.

To do this, simply add a line with this syntax: ##@ My project as illustrated below:

SHELL:=bash

COLOR_YELLOW:=33

.PHONY: help
help: ## Show the help with the list of commands
 @clear
 @awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n  make \033[36m<target>\033[0m\n\n"} /^[a-zA-Z_-]+:.*?##/ { printf "  \033[36m%-20s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[0;33m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)
 @echo ""

// highlight-next-line
##@ My project              Helpers to work with the application

.PHONY: bash
bash: ## Open an interactive shell in the Docker container
    # [...]

// highlight-next-line
##@ Data quality            Code analysis tools

.PHONY: phan
phan: ## Run phan analysis
    # [...]

.PHONY: php-cs-fixer
php-cs-fixer: ## Run php-cs-fixer
    # [...]

// highlight-next-line
##@ Database management     Working with the database

.PHONY: phpmyadmin
phpmyadmin: ## Run phpmyadmin web interface
    # [...]

And here is the final result:

Usage:
  make <target>

  help                  Show the help with the list of commands

My project              Helpers to work with the application
  bash                  Open an interactive shell in the Docker container

Data quality            Code analysis tools
  phan                  Run phan analysis
  php-cs-fixer          Run php-cs-fixer

Database management     Working with the database
  phpmyadmin            Run phpmyadmin web interface

Now we have a clear grouping of actions. Much better.

Take a look on mine, for this blog

This blog is maintained using such makefile, you can get a copy here: https://github.com/cavo789/blog/blob/main/makefile

Running Quarto Markdown in Docker

Christophe Avonture — Fri, 22 Dec 2023 19:39:45 +0000

Quarto is a tool for producing PDF, Word document, HTML web pages, ePub files, slideshows and many, many more output based on a Markdown file.

Using Quarto, you can render any markdown content to a new PDF f.i.

Quarto supports a very large number of features, to which are added extensions from its community, making it a really practical tool for anyone wishing to produce documentation.

Personally, I haven't used a Word-type word processor for several years; nor have I used PowerPoint since, I don't even know when the last time was.

And yet, I produce a great deal of documentation and slideshows. I write everything in markdown and generate pdfs or slideshows from the same content.

Until recently, I'd been using pandoc but, having taken the time to look around Quarto, it's a hell of a lot more powerful.

Like always on this blog, you will not install Quarto the old-fashioned way. Instead, you'll create our own Docker image.

Let's play

As usual, you will now create a temporary folder for your experiments. Please start a Linux shell and run mkdir -p /tmp/docker-quarto && cd $_.

Create your own Docker image

Create a new file called Dockerfile (there is no extension) with this content:

# Based on https://github.com/analythium/quarto-docker-examples/blob/main/Dockerfile.base

# Version number of Quarto to download and use
ARG QUARTO_VERSION="1.4.529"

ARG OS_USERNAME=quarto
ARG UID=1000
ARG GID=1000

FROM eddelbuettel/r2u:20.04

# librsvg2-bin is to allow SVG conversion when rendering a PDF file
# (will install the rsvg-view binary)
RUN set -e -x && \
    apt-get update && apt-get install -y --no-install-recommends \
    pandoc \
    pandoc-citeproc \
    curl \
    gdebi-core \
    librsvg2-bin \
    python3.8 python3-pip \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/*

RUN set -e -x && \
    install.r shiny jsonlite ggplot2 htmltools remotes renv knitr rmarkdown quarto

# Download and install Quarto
ARG QUARTO_VERSION
RUN set -e -x && \
    curl -o quarto-linux-amd64.deb -L https://github.com/quarto-dev/quarto-cli/releases/download/v${QUARTO_VERSION}/quarto-${QUARTO_VERSION}-linux-amd64.deb \
    && gdebi --non-interactive quarto-linux-amd64.deb \
    && rm -f quarto-linux-amd64.deb

# Should be done for the user; won't work if done for root
# (quarto will say that "tinytex is not installed")
ARG OS_USERNAME
ARG UID
ARG GID

RUN set -e -x && \
    groupadd -g $GID -o "${OS_USERNAME}" && \
    useradd -m -u $UID -g $GID -o -s /bin/bash "${OS_USERNAME}"

USER "${OS_USERNAME}"

# Install tools like tinytex to allow conversion to PDF
RUN set -e -x && \
    quarto install tool tinytex --update-path

RUN set -e -x && \
    printf "\e[0;105m%s\e[0;0m\n" "Run tlmgr update" \
    && ~/.TinyTeX/bin/x86_64-linux/tlmgr update --self --all && \
    ~/.TinyTeX/bin/x86_64-linux/fmtutil-sys --all

# See https://github.com/rstudio/tinytex/issues/426 for explanation
RUN set -e -x && \
    printf "\e[0;105m%s\e[0;0m\n" "Run tlmgr install for a few tinyText packages (needed for PDF conversion)" \
    && ~/.TinyTeX/bin/x86_64-linux/tlmgr install fvextra footnotebackref pagecolor sourcesanspro sourcecodepro titling

USER root

RUN set -e -x && \
    mkdir -p /input

USER "${OS_USERNAME}"

WORKDIR /

This done, please run docker build -t cavo789/quarto . and after something like three minutes the first time, you'll get your own Docker image:

❯ docker build -t cavo789/quarto .

[+] Building 208.2s (13/13) FINISHED                  docker:default
 => [internal] load .dockerignore                     0.0s
 => => transferring context: 2B                       0.0s
 => [internal] load build definition from Dockerfile  0.0s
 => => transferring dockerfile: 2.08kB                0.0s
 => [internal] load metadata for docker.io/eddelbuettel/r2u:20.04  3.4s
 => CACHED [ 1/10] FROM docker.io/eddelbuettel/r2u:20.04@sha256:133b40653e0ad564d348f94ad72c753b97fb28941c072e69bb6e03c3b8d6c06e 0.0s
 => [ 2/10] RUN set -e -x && apt-get update && apt-get install -y --no-install-recommends     pandoc     pandoc-citeproc     curl     gdebi-core     librsvg2-bin     python3.8   47.6s
 => [ 3/10] RUN set -e -x && install.r shiny jsonlite ggplot2 htmltools remotes renv knitr rmarkdown quarto                                                                       27.2s
 => [ 4/10] RUN set -e -x && curl -o quarto-linux-amd64.deb -L https://github.com/quarto-dev/quarto-cli/releases/download/v1.4.529/quarto-1.4.529-linux-amd64.deb     && gdebi -  12.1s
 => [ 5/10] RUN set -e -x && groupadd -g 1000 -o "quarto" && useradd -m -u 1000 -g 1000 -o -s /bin/bash "quarto"                                                               0.5s
 => [ 6/10] RUN set -e -x && quarto install tool tinytex --update-path                                   23.0s
 => [ 7/10] RUN set -e -x && printf "\e[0;105m%s\e[0;0m\n" "Run tlmgr update"     && ~/.TinyTeX/bin/x86_64-linux/tlmgr update --self --all && ~/.TinyTeX/bin/x86_64-linux/fm  77.9s
 => [ 8/10] RUN set -e -x && printf "\e[0;105m%s\e[0;0m\n" "Run tlmgr install for a few tinyText packages (needed for PDF conversion)"     && ~/.TinyTeX/bin/x86_64-linux/tlmgr   11.7s
 => [ 9/10] RUN set -e -x && mkdir -p /input                   0.5s
 => exporting to image               4.0s
 => => exporting layers              4.0s
 => => writing image sha256:fe1d20bd71a66eb574ba1f5b35c988ace57c2c30f93159caa4d5de2f8c490eb0                  0.0s
 => => naming to docker.io/cavo789/quarto                                                                     0.0s

What's Next?
  View summary of image vulnerabilities and recommendations → docker scout quickview

The previous instruction docker build -t cavo789/quarto . has created an image called cavo789/quarto. You can for sure choose a different name without any impact on the image.

You can quickly check the size of your image; quite huge but except you're very low in memory / disk space; this is really not a big deal.

❯ docker image list | grep quarto

cavo789/quarto  latest  fe1d20bd71a6  10 minutes ago  2.14GB

Using Quarto and generate a PDF file

Create a new test.md file in your /tmp/docker-quarto folder with this content:

# What's is Quarto? Explain like I'm five

Imagine you want to write a story or a report, but instead of using a fancy computer program, you use plain text. That's kind of like Markdown, a simple language that lets you format your text without getting too complicated.

Now, Quarto is like a super-powered writing tool that understands Markdown and can also help you write code in different languages, like R or Python. It's like having a helper in your writing process, making things easier and more fun.

So, if you want to create documents, presentations, or even books, Quarto and Markdown can be your friends. They'll help you organize your thoughts, add cool features, and even share your work with the world.

Now, back to your Linux console and you'll convert that file to a pdf. Please refers to the official documentation of Quarto to get in-depth information about it.

To convert to a PDF, the instruction to fire is quarto render test.md --to pdf. But since you're using Quarto from a Docker image, the instruction becomes docker run -it --rm -v ${PWD}:/input -w /input -u $(id -u):$(id -g) cavo789/quarto quarto render test.md --to pdf.

As a reminder, the used Docker run command are (almost always the same):

-it to start Docker interactively, this will allow the script running in the container to ask you for some prompts f.i.,
--rm to ask Docker to kill and remove the container as soon as the script has been executed (otherwise you'll have a lot of exited but not removed Docker containers; you can check this by not using the --rm flag then running docker container list on the console),
-v ${PWD}:/input to share your current folder with a folder called /input in the Docker container,
-w /input to tell Docker that the current directory, in the container, will be the /app folder,
-u $(id -u):$(id -g) ask Docker to reuse our local credentials so when a file is updated/created in the container, the file will be owned by you,
then cavo789/quarto which is the name of your Quarto Docker image, and, finally,
quarto render test.md --to pdf i.e. the command line to start within the container.

So, let's convert to PDF and run docker run -it --rm -v ${PWD}:/input -w /input -u $(id -u):$(id -g) cavo789/quarto quarto render test.md --to pdf in your console.

❯ docker run -it --rm -v ${PWD}:/input -w /input -u $(id -u):$(id -g) cavo789/quarto quarto render test.md --to pdf`

pandoc
  to: latex
  output-file: test.tex
  standalone: true
  pdf-engine: xelatex
  variables:
    graphics: true
    tables: true
  default-image-extension: pdf

metadata
  documentclass: scrartcl
  classoption:
    - DIV=11
    - numbers=noendperiod
  papersize: letter
  header-includes:
    - '\KOMAoption{captions}{tableheading}'
  block-headings: true

Rendering PDF
running xelatex - 1
  This is XeTeX, Version 3.141592653-2.6-0.999995 (TeX Live 2023) (preloaded format=xelatex)
   restricted \write18 enabled.
  entering extended mode

running xelatex - 2
  This is XeTeX, Version 3.141592653-2.6-0.999995 (TeX Live 2023) (preloaded format=xelatex)
   restricted \write18 enabled.
  entering extended mode

Output created: test.pdf

Add the --log-level warning CLI argument to Quarto to ask him to show only warning (and error) messages. Non-essential output will be hidden and you'll keep a clean console. The new command to use is thus docker run -it --rm -v ${PWD}:/input -w /input -u $(id -u):$(id -g) cavo789/quarto quarto render test.md --to pdf --log-level warning

Using Quarto and generate a HTML file

Simply modify the --to argument and replace pdf by html and run the command: docker run -it --rm -v ${PWD}:/input -w /input -u $(id -u):$(id -g) cavo789/quarto quarto render test.md --to html --log-level warning

Now, you've a test.html file in your directory.

Using Quarto and generate a revealjs slideshow

This time, the --to argument should be set to revealjs: docker run -it --rm -v ${PWD}:/input -w /input -u $(id -u):$(id -g) cavo789/quarto quarto render test.md --to revealjs --log-level warning

Open the test.html file and you'll get this:

Ok, you've just one slide now. Reopen the test.md file and you'll insert slide breaks. This can be done using the ---- syntax:

# What's is Quarto? Explain like I'm five

Imagine you want to write a story or a report, but instead of using a fancy computer program, you use plain text. That's kind of like Markdown, a simple language that lets you format your text without getting too complicated.

----

Now, Quarto is like a super-powered writing tool that understands Markdown and can also help you write code in different languages, like R or Python. It's like having a helper in your writing process, making things easier and more fun.

----

So, if you want to create documents, presentations, or even books, Quarto and Markdown can be your friends. They'll help you organize your thoughts, add cool features, and even share your work with the world.

Rerun docker run -it --rm -v ${PWD}:/input -w /input -u $(id -u):$(id -g) cavo789/quarto quarto render test.md --to revealjs --log-level warning and now your slideshow will have three slides (press space or arrow keys for navigation):

The nice thing now is that your slideshow is ready to be deployed on your remote server. Copy the html file and the associated folder (in our use case here, file test.html and folder test_files) to your FTP server f.i. and your website can be publicly accessed. Nice, isn't it?

Encrypt sensitive data using SSL and Docker

Christophe Avonture — Mon, 11 Dec 2023 15:58:20 +0000

For 1,000 reasons or more, you want to encrypt a file containing text. Which software should you install? Well ... none other than Docker!

By using a Docker Alpine/OpenSSL image, it's so easy to encrypt/decrypt files using OpenSSL.

Linux scripts

Create a new file on your disk with this content. This is the encrypt.sh script.

#!/usr/bin/env bash

(
  MY_PASSWORD="ThisIsMyLongPasswordNobodyWillBeAbleToCrackIt" &&
  docker run --rm -it -v $(pwd):/data -w /data -u $(id -u):$(id -g) alpine/openssl enc -aes-256-cbc -salt -pbkdf2 -a -in /data/secrets.md -out /data/secrets_encrypted.md -k ${MY_PASSWORD}
)

And this is the decrypt.sh script:

#!/usr/bin/env bash

(
  MY_PASSWORD="ThisIsMyLongPasswordNobodyWillBeAbleToCrackIt" &&
  docker run --rm -it -v $(pwd):/data -w /data -u $(id -u):$(id -g) alpine/openssl enc -aes-256-cbc -salt -pbkdf2 -a -d -in /data/secrets_encrypted.md -out //data/secrets_decrypted.md -k ${MY_PASSWORD}
)

Update the MY_PASSWORD variable in both scripts to use yours.

DOS scripts

For the illustration purpose, the DOS encryption script, encrypt.cmd, will ask you for a password (since the -k parameter is not part of the instruction). If the encrypted file has been created, the original one will be removed from your disk.

Here is the content of the encrypt.cmd DOS script:

@echo off

cls

docker run --rm -it -v %CD%:/data -w /data alpine/openssl enc -aes-256-cbc -salt -pbkdf2 -a -in /data/secrets.md -out /data/secrets.encrypted

# Put this part in comment if you want to keep the original, unencrypted, file.
IF EXIST secrets.encrypted (
  del secrets.md
)

The decryption script, decrypt.cmd will ask you for the password and will display the decrypted content on the console (since the -out parameter is not part of the instruction).

Here is the content of the decrypt.cmd DOS script:

@echo off

cls

docker run --rm -it -v C:\temp:/data -w /data alpine/openssl enc -aes-256-cbc -salt -pbkdf2 -a -d -in /data/secrets.encrypted

Use case

In addition to simple encryption need, one use case is to store confidential files in online systems, e.g. a versioning system such as Github, or on cloud disks (e.g. Google drive).

Command line arguments

The openssl enc command accepts those arguments:

Option	Description
`enc`	Encoding with Ciphers
`-aes-256-cbc`	The encryption cipher to be used
`-salt`	Adds strength to the encryption
`-pbkdf2`	Generate a PBKDF2 key derivation of a supplied password
`-a`	Encrypted data should be in Base64 and not binary
`-d`	Decrypt action (if `-d` is missing, action is encryt)
`-in`	Specifies the input file
`-out`	Specifies the output file
`-k`	Provide the password to use

Decrypt on the console, don't write a file

Edit the decrypt.sh (or decrypt.cmd) script and search for -out /data/secrets_decrypted.md. Remove that part.

Now, when you'll run decrypt.sh the decrypted content will be displayed on the console only, nothing will be written on the disk. Your secrets are safe.

Example

Imagine a text file like secrets.md with this content:

# My password

## My secret site

### FTP server

* Name: `127.0.0.1`
* Login: `admin`
* Password: `admin`

### Admin interface

* URL: `https://..../admin`
* Login: `admin`
* Password: `admin`

By running the encrypt.sh script, the file secrets_encrypted.md will be created on your disk and will have this content:

U2FsdGVkX18jyyHAiaDcwolgvrCmB9SutNFhOFosDZvYA+t/8F5PWsxU+YIb0xLj
/0swl1Mvh9XBcg3FwpQn5CGm5ltb3zKiExPO8WoTuYOmlJj2PN5eLJv3GWVVJ8/t
q31xBBAlbI0k+a3pWiETl1qEmh4hwc4jeC5NOByYSAojiIdCNF0W5+VVkUlBeKGb
sv8tpDWEb/dgHrfFPtZD5MqeNQw71/ndORZC1ZDIT/Ju6O7a6rd9ph0aQuPz49PU
SzDUePUgn9wbR0tZvNM1JA1LkN1kDaguJ940TdKns+Q=

From now, you can remove secrets.md since you've the encrypted version.

To retrieve the original content, just run the decrypt.sh script.

By running that command (or by running decrypt.sh), you'll decrypt the file secrets_encrypted.md and get a newer one called secrets_decrypted.md.

Self-hosted monitoring tool using Docker Uptime Kuma

Christophe Avonture — Wed, 06 Dec 2023 09:08:21 +0000

Imagine you're a web developer or you work in a web agency and you'd like to keep an eye on the sites you've developed for your clients, free of charge. Are these sites online now, or are they down?

This work is carried out by site monitoring platforms. Could you install one on your computer? Of course!

There are tons of self-hosted monitoring tools; one of them is Uptime Kuma. You can play with the demo website here: https://demo.uptime.kuma.pet:27000/. Just create an admin account (for free) and you're ready to add your first websites.

As read in the official documentation, you can easily start it using the command below.

docker run -d --restart=always -p 3001:3001 -v ${PWD}:/app/data --name uptime-kuma louislam/uptime-kuma:1

The -v ${PWD}:/app/data flag is important if you want to keep track of the sites you'll add to the dashboard (i.e. if you restart the tool). If you wish, only, play once with the interface first, you can omit it so nothing will be written on the disk.

In the setting page, site by site, you can define a lot of actions like what the monitoring tool should do when the site is down. For instance, send you a notification on Mattermost or an email or ...

On top of configuration items site by site, you'll also find in the Profile -> Settings page, a large number of global settings like the choice of the language's interface (French is available).

Create your Joomla website using Docker

Christophe Avonture — Tue, 28 Nov 2023 14:06:09 +0000

In this article, we will learn how to use Docker to install Joomla on your localhost and start a new website in seconds (don't want to wait? Jump to the Final docker-compose.yml chapter).

I will use a Linux console (I'm running WSL on my Windows computer and I have chosen Ubuntu for my distribution) but since Docker can also be used on Windows, you can perfectly run, exactly, the same commands in an MS-DOS / Powershell console.

If you don't have Docker yet, please consult my "Install Docker and play with PHP" article to get more information about Docker and an easy introduction guide.

We will assume in this article that you have Docker, and you're working under Linux or using WSL.

Before starting

As you know, to be able to run a CMS like Joomla we need three things + 1:

We need a webserver like Apache or nginx,
We need a database service like MySQL, MariaDB or PostgreSQL or any other supported databases and
We need PHP.

And, of course, we need Joomla.

In terms of Docker: we need three services.

Docker compose

When you need many services (Apache should be able to communicate with PHP and PHP should be able to request data from MySQL), you need to configure a special file called docker-compose.yml. That file should be placed in the root of the project and will define the list of services required and how they will collaborate together.

You will find an example of the docker-compose.yml file on the Joomla image description page: https://hub.docker.com/_/joomla search for docker-compose on this page.

The Docker Joomla image is built on PHP and Apache
It's for sure too technical now but if you click on the
https://github.com/joomla-docker/docker-joomla/blob/8cac4ff7ae88b9274870a95f5e22ea3c32f01fd7/5.0/php8.1/apache/Dockerfile#L8 link, you can see that the Docker image for Joomla 5.0.0 is built on a php:8.1-apache image. This means that using this image, you will get PHP, Apache and Joomla, altogether in a single image.

Download images

Please create on your disk, let us say in the /tmp/joomla folder a file called docker-compose.yml with this content (you can retrieve that file on https://hub.docker.com/_/joomla):

version: '3.9'

services:
  joomla:
    image: joomla
    restart: always
    ports:
      - 8080:80
    environment:
      - JOOMLA_DB_HOST=joomladb
      - JOOMLA_DB_PASSWORD=example

  joomladb:
    image: mysql:8.0.13
    restart: always
    environment:
      - MYSQL_ROOT_PASSWORD=example

You want MariaDB, not MySQL?
Nothing could be simpler! In the docker-compose.yml file, replace the line image: mysql:8.0.13 with image: mariadb:11.1.2 and save your change. That's it. It's piece of cake no?

To make things as clear as possible, here is my temporary folder content:

❯ pwd
/tmp/joomla

❯ ls -alh
Permissions Size User       Group      Date Modified    Name
drwxr-xr-x     - christophe christophe 2023-11-04 09:32  .
drwxrwxrwt     - christophe christophe 2023-11-04 09:32 ..
.rw-r--r--   325 christophe christophe 2023-11-04 09:32 docker-compose.yml

So, I just have one file, and this is the newly, created, docker-compose.yml file.

Now, if needed, please start a Linux console, and go to your joomla folder (i.e. cd /tmp/joomla). From there, run the command below:

docker compose up --detach

docker compose up --detach
That command is one of the most important to know. It asks Docker to proceed the docker-compose.yml file and run services. In short: run your website.

Docker will start downloading joomla and joomladb, the two services mentioned in the docker-compose.yml file.

services:
  joomla:
    [...]
  joomladb:
    [...]

You will obtain something like this, please wait until everything is downloaded.

❯ docker compose up --detach
[+] Running 16/35
 ⠹ joomladb 12 layers [⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀]    0B/0B  Pulling  19.3s
   ⠧ 177e7ef0df69 Waiting   15.8s
   ⠧ cac25352c4c8 Waiting   15.8s
   ⠧ 8585afabb40a Waiting   15.8s
   [...]
 ⠹ joomla 21 layers [⣿⣿⣦⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣦⣿⣿⣿⣿⣀⠀⠀] 94.59MB/155.9MB Pulling  19.3s
   ✔ 578acb154839 Pull complete  11.3s
   ✔ c053f6f43c12 Pull complete  11.9s
   ⠋ 65cebbf4d847 Downloading [==============>         ]  68.41MB/104.4MB  16.1s
   ✔ 34045bc93960 Download complete  1.0s
   [...]

At the end, once images have been downloaded, the console will show something like this:

❯ docker compose up --detach
[+] Running 35/35
 ✔ joomladb 12 layers [⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿]  0B/0B   Pulled  84.9s
   ✔ 177e7ef0df69 Pull complete  26.9s
   ✔ cac25352c4c8 Pull complete  27.5s
   ✔ 8585afabb40a Pull complete  28.2s
   [...]
 ✔ joomla 21 layers [⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿] 0B/0B  Pulled  146.4s
   ✔ 578acb154839 Pull complete   11.3s
   ✔ c053f6f43c12 Pull complete   11.9s
   ✔ 65cebbf4d847 Pull complete   31.2s
   [...]
[+] Running 3/3
 ✔ Network joomla_default       Created  0.3s
 ✔ Container joomla-joomladb-1  Started  52.9s
 ✔ Container joomla-joomla-1    Started  38.8s

So, the two images have been downloaded then,

a joomla_default network is created,
the joomla-joomladb-1 container is created (this is your database server) and
the joomla-joomla-1 container is created too (this is your Joomla service).

At this stage, your site is already being installed. Go to the URL http://127.0.0.1:8080 to view it (make sure to use the http protocol and not https).

Not yet ready
You may get an error page ERR_EMPTY_RESPONSE; this is because, for example, MySQL is not yet fully loaded and Joomla has to wait for it before it can display the installation page. In this case, please wait a little longer ... or read the rest of this article.

Why joomla-joomlaxxx names?

We didn't give your project a name, we just created a docker-compose.yml file in your /tmp/joomla folder. So, Docker has named your project using the folder name (joomla) concatenated to service name (refers to the docker-compose.yml file, we have two services, one called joomladb and one called joomla). That is why...

Let us introduce a minor, optional, change, we will give a name to your Docker project and containers: edit the docker-compose.yml file and add a line with name: xxxx where xxxx is the name of your choice. Do the same but using container_name this time for the two services; for instance:

version: '3.9'
name: kingsbridge
services:
  joomla:
    container_name: kingsbridge-app
    [...]

  joomladb:
    container_name: kingsbridge-db
    [...]

We won't be restarting your Docker containers yet. For now, the kingsbridge name won't be considered. For this to be the case, we would need to launch docker compose down followed by docker compose up --detach, but let us wait a little longer before doing so.

Docker images

If you're curious, you can run the docker image list command to get the list of Docker images already downloaded on your machine.

❯ docker image list
REPOSITORY   TAG       IMAGE ID       CREATED       SIZE
joomla       latest    882b2151d890   2 days ago    663MB
mysql        8.0.13    102816b1ee7d   4 years ago   486MB

Ok, so, Docker has downloaded Joomla (in its latest version) and MySQL (version 8.0.13).

What about Joomla 5.0 i.e. force a version?
By default, when we don't specify any version number (which isn't recommended), Docker will download the version known as the latest one. latest, here, is what Docker calls a tag.

version: '3.9'

services:
  joomla:
    image: joomla
    [...]

To retrieve the list of all tags, please navigate to https://hub.docker.com/_/joomla/tags.

During writing this article, Joomla latest correspond to Joomla version 4.4.0. So, what about to force to use Joomla 5.0. By surfing on the tags page, you can retrieve in the list of tags this one: 5.0.0-php8.2-apache. So just replace image: joomla with image: joomla:5.0.0-php8.2-apache in docker-compose.yml and it's done. You're forcing a version.

version: '3.9'

services:
  joomla:
    image: joomla:5.0.0-php8.2-apache
    [...]

Docker containers

We're almost done. Please run docker container list to get the list of containers created by Docker:

❯ docker container list
CONTAINER ID   IMAGE          COMMAND                  CREATED          STATUS          PORTS                    NAMES
0798f8f25d2b   joomla         "/entrypoint.sh apac…"   8 minutes ago    Up 5 minutes    0.0.0.0:8080->80/tcp     joomla-joomla-1
7b7fcd3809b0   mysql:8.0.13   "docker-entrypoint.s…"   8 minutes ago    Up 7 minutes    3306/tcp, 33060/tcp      joomla-joomladb-1

We have two running containers (your two services). Pay attention to the PORTS column: your joomla container is listening on the port 8080 and your mysql container is listening on port 3306.

Hey, port 8080, does that mean anything to you? That is a port for a web page, isn't it?

Let us try by starting your favorite browser and navigating to http://localhost:8080 (or http://127.0.0.1:8080, it's strictly the same) and... Wow!

Just incredible; no?
Wow, doesn't that sound crazy? With a single command (docker compose up --detach), you have downloaded everything you need to get Joomla running on your machine.

Let us rewind for a few seconds: to run Joomla, we knew we needed three things + 1; a webserver, a database server, PHP and, of course, we need Joomla. And here, just by running one command, hop, all the magic happens. And nothing to configure too!

Install Joomla

Back to http://localhost:8080 and we will continue the installation.

On the first screen, just select your preferred language then enter a name for your Joomla site:

When Joomla will ask for your admin credentials, just fill in the value of your choice:

But, for the database configuration, here you need to be strict:

The database type should be MySQLi (since we're using MySQL),
The name of the host should be joomladb (the name we have chosen for the database service),
The username should be root (default value) and
The password for that user should be example

Why these values?
These values can be retrieved inside the docker-compose.yml file. If you have named your database service something other than joomladb, then please use the name you have chosen.

version: '3.9'

services:
  [...]
  joomladb:
    [...]
    environment:
      - MYSQL_ROOT_PASSWORD=example

And, after a few seconds, tadaaa...

The administrator page:

And the administrator dashboard:

Congratulations, you have successfully installed a fresh Joomla website using Docker!

Everything is done in RAM

Let us leave a few minutes the browser and go back to your Linux console.

In the previous chapter, we have installed Joomla so we should have Joomla on your computer, right?

Let us verify by returning to our Linux console:

❯ pwd
/tmp/joomla

❯ ls -alh
Permissions Size User       Group      Date Modified    Name
drwxr-xr-x     - christophe christophe 2023-11-04 09:32  .
drwxrwxrwt     - christophe christophe 2023-11-04 09:32 ..
.rw-r--r--   325 christophe christophe 2023-11-04 09:32 docker-compose.yml

Oh? Nothing... Nothing has been downloaded in your folder. You don't have Joomla on your computer. How is this possible?

We will discuss this later but yes, by default with Docker, everything happens in memory, nothing on the disk. If you can't wait, please read my "Share data between your running Docker container and your computer" article to better understand why and how.

Play with containers

Still on your console, type again docker container list:

❯ docker container list
CONTAINER ID   IMAGE          COMMAND                  CREATED          STATUS          PORTS                    NAMES
0798f8f25d2b   joomla         "/entrypoint.sh apac…"   8 minutes ago    Up 5 minutes    0.0.0.0:8080->80/tcp     joomla-joomla-1
7b7fcd3809b0   mysql:8.0.13   "docker-entrypoint.s…"   8 minutes ago    Up 7 minutes    3306/tcp, 33060/tcp      joomla-joomladb-1

Pay attention this time to the last column, called NAMES.

We have thus two containers, one named joomla-joomla-1 and one name joomla-joomladb-1.

We will stop them by running docker compose down:

❯ docker compose down
[+] Running 3/3
 ✔ Container joomla-joomla-1    Removed 2.6s
 ✔ Container joomla-joomladb-1  Removed 4.2s
 ✔ Network joomla       Removed

If you go back to http://localhost:8080 with your browser and refresh the page; the site didn't exist anymore.

Run docker compose up --detach again, surf to the site again, refresh the page and the site is, oh? not yet responding. Wait a few... a few more... and after a certain period, the site will be there. Why?

Docker must (re)start two services, the Joomla one and the database server. Initialization of both services may take a few seconds, and the database service must be up so that Joomla can continue its initialization.

You can see this by running docker compose logs --follow (press CTRL+C to quit).

Once Joomla will be ready, you will get the installation wizard of Joomla... just like the first time. So, by running docker compose down you have lost your work.

As mentioned earlier, everything is done in RAM. By stopping a Docker container, you will lose everything not saved on your computer. It's great for playing/learning but not what you expect when you're developing a real site.

Remember the change we made earlier. We had added the name kingsbridge as the project name in your docker-compose.yml file and we've named the two containers. You can see that after relaunching docker compose up, this time it's no longer joomla-joomlaxxxx but kingsbridge-app and kingsbridge-db. This because changes made to the yaml file are processed only after a down / up command. If you modify the yaml file, you should restart Docker containers.

Synchronize with your computer

We will now require that Docker store files/folders on your computer.

We wish two things:

We want the entire website to be saved on your hard disk and
we want the database to be saved on the hard disk as well.

To do this, please edit the docker-compose.yml file and add the lines below:

version: '3.9'

name: kingsbridge

services:
  joomla:
    [...]
    user: 1000:1000
    volumes:
      - ./site_joomla:/var/www/html

  joomladb:
    [...]
    user: 1000:1000
    volumes:
      - ./db:/var/lib/mysql

The /var/www/html folder of the Joomla service should be synchronized with the site_joomla subfolder on your computer. This is for the Joomla website.

And the /var/lib/mysql folder of the MySQL service should be synchronized with your local db subfolder.

Please create folders first
Make sure to, first, create these two directories on your computer so folder's permissions will be correct!

❯ mkdir site_joomla db

The two lines user: 1000:1000 are really important and inform Docker to reuse your local credentials (the one used on your computer).

Important
If you don't do this, files and folders created by Docker will be owned by the root user on your computer and not by us (in my case, by the user called christophe).

Just check your folder's content:

❯ pwd
/tmp/joomla

❯ ls -alh
Permissions Size User       Group      Date Modified    Name
drwxr-xr-x     - christophe christophe 2023-11-04 20:13  .
drwxrwxrwt     - christophe christophe 2023-11-04 20:13 ..
drwxr-xr-x     - christophe christophe 2023-11-04 20:13 db
drwxr-xr-x     - christophe christophe 2023-11-04 20:13 site_joomla
.rw-r--r--   478 christophe christophe 2023-11-04 20:13 docker-compose.yml

Run Docker again but first, make sure the previous containers are removed (not only stopped): docker compose kill.

❯ docker compose kill
[+] Killing 2/2
 ✔ Container kingsbridge-db   Killed   2.1s
 ✔ Container kingsbridge-app  Killed   1.5s

Run docker compose up --detach again.

❯ docker compose up --detach
[+] Running 3/3
 ✔ Network kingsbridge_default       Created    0.3s
 ✔ Container kingsbridge-db   Started    3.3s
 ✔ Container kingsbridge-app  Started

And you can, already, run ls again to see that, yes, your local site_joomla and db folders are populated now. This is the result of the volumes entry we have added in your docker-compose.yml file.

❯ pwd
/tmp/joomla

❯ ls -alh site_joomla
Permissions Size User       Group      Date Modified    Name
drwxr-xr-x     - christophe christophe 2023-11-04 20:20 .
drwxr-xr-x     - christophe christophe 2023-11-04 20:16 ..
drwxr-xr-x     - christophe christophe 2023-10-14 14:42 administrator
drwxr-xr-x     - christophe christophe 2023-10-14 14:42 api
drwxr-xr-x     - christophe christophe 2023-10-14 14:42 cache
drwxr-xr-x     - christophe christophe 2023-10-14 14:42 cli
drwxr-xr-x     - christophe christophe 2023-10-14 14:42 components
drwxr-xr-x     - christophe christophe 2023-10-14 14:42 images
drwxr-xr-x     - christophe christophe 2023-10-14 14:42 includes
drwxr-xr-x     - christophe christophe 2023-10-14 14:42 installation
drwxr-xr-x     - christophe christophe 2023-10-14 14:42 language
drwxr-xr-x     - christophe christophe 2023-10-14 14:42 layouts
drwxr-xr-x     - christophe christophe 2023-10-14 14:43 libraries
drwxr-xr-x     - christophe christophe 2023-10-14 14:43 media
drwxr-xr-x     - christophe christophe 2023-10-14 14:42 modules
drwxr-xr-x     - christophe christophe 2023-10-14 14:42 plugins
drwxr-xr-x     - christophe christophe 2023-10-14 14:42 templates
drwxr-xr-x     - christophe christophe 2023-10-14 14:42 tmp
.rw-r--r--  6.9k christophe christophe 2023-11-04 20:20 .htaccess
.rw-r--r--  6.9k christophe christophe 2023-10-14 14:42 htaccess.txt
.rw-r--r--  1.1k christophe christophe 2023-10-14 14:42 index.php
.rw-r--r--   18k christophe christophe 2023-10-14 14:42 LICENSE.txt
.rw-r--r--  4.9k christophe christophe 2023-10-14 14:42 README.txt
.rw-r--r--   764 christophe christophe 2023-10-14 14:42 robots.txt.dist
.rw-r--r--  3.0k christophe christophe 2023-10-14 14:42 web.config.txt

❯ ls -alh db
Permissions Size User       Group      Date Modified    Name
drwxr-x---     - christophe christophe 2023-11-04 20:20 #innodb_temp
drwxr-xr-x     - christophe christophe 2023-11-04 20:21 .
drwxr-xr-x     - christophe christophe 2023-11-04 20:16 ..
drwxr-x---     - christophe christophe 2023-11-04 20:21 mysql
drwxr-x---     - christophe christophe 2023-11-04 20:21 performance_schema
drwxr-x---     - christophe christophe 2023-11-04 20:21 sys
.rw-r-----    56 christophe christophe 2023-11-04 20:21 auto.cnf
.rw-------  1.7k christophe christophe 2023-11-04 20:21 ca-key.pem
.rw-r--r--  1.1k christophe christophe 2023-11-04 20:21 ca.pem
.rw-r--r--  1.1k christophe christophe 2023-11-04 20:21 client-cert.pem
.rw-------  1.7k christophe christophe 2023-11-04 20:21 client-key.pem
.rw-r-----   50M christophe christophe 2023-11-04 20:21 ib_logfile0
.rw-r-----   50M christophe christophe 2023-11-04 20:20 ib_logfile1
.rw-r-----   13M christophe christophe 2023-11-04 20:21 ibdata1
.rw-r-----   13M christophe christophe 2023-11-04 20:20 ibtmp1
.rw-r-----   24M christophe christophe 2023-11-04 20:21 mysql.ibd
.rw-------  1.7k christophe christophe 2023-11-04 20:21 private_key.pem
.rw-r--r--   452 christophe christophe 2023-11-04 20:21 public_key.pem
.rw-r--r--  1.1k christophe christophe 2023-11-04 20:21 server-cert.pem
.rw-------  1.7k christophe christophe 2023-11-04 20:21 server-key.pem
.rw-r-----   10M christophe christophe 2023-11-04 20:21 undo_001
.rw-r-----   10M christophe christophe 2023-11-04 20:21 undo_002

Back to your browser and continue the installation of Joomla like we did in the previous chapter.

When the installation wizard has finished successfully, return to your Linux console and check if you can see the configuration.php file now.

❯ pwd
/tmp/joomla

❯ ls site_joomla/configuration.php

Permissions Size User       Group      Date Modified    Name
.rw-r--r--  2.0k christophe christophe 2023-11-04 20:29 configuration.php

❯ head -n 10 site_joomla/configuration.php
<?php
class JConfig {
        public $offline = false;
        public $offline_message = 'This site is down for maintenance.<br>Please check back again soon.';
        public $display_offline_message = 1;
        public $offline_image = '';
        public $sitename = 'Kingsbridge';
        public $editor = 'tinymce';
        public $captcha = '0';
        public $list_limit = 20;

Yes! This time we have stored your Joomla website on your computer.

For the exercise, we can kill your containers by running docker compose kill and run docker compose up --detach again to start your containers again and, this time, we will retrieve your Joomla site as we just leave it. Nothing is lost now.

And since files/folders are now on your computer, you can do everything you want with your website like committing it on a GitHub repository f.i.

Synchronization has a cost
When using one or more volumes, Docker must constantly check whether the files/folders on your computer are synchronized with the containers. This has a cost in terms of performance. Similarly, if Docker needs to write to a file (or to your Joomla database); if this is only in memory, it will be faster than if you also had to write the database to your disk. However, the difference in speed is not obvious under normal circumstances. If you're a developer writing hundreds or even thousands of records, you'll observe a noticeable difference.

Start a CLI command

When working with a Joomla website, sometimes you need to run some PHP command like php joomla.php.

To be able to do this, you will need to start a interactive shell session in the Joomla container.

Did you remember the name of your Joomla service? If no, just open the docker-compose.yml file again.

services:
  joomla:
    [...]

The name of your Joomla service is joomla (and joomladb is the name of your database service).

Now we know everything we need: to run an interactive shell session in the Joomla container, just run docker compose exec joomla /bin/sh to jump into the Joomla container (and docker compose exec joomladb /bin/sh for the database container).

Let us rewind for a few seconds because it's complicated to understand.

On your computer, in your Linux console, if you type pwd to get the current folder, you will see /tmp/joomla since it's the directory we have used in the tutorial.

Then, we jump in the Joomla Docker container by running docker compose exec joomla /bin/sh and, you can see it, we don't have any longer a prompt starting with > but with $ but that isn't the only difference. If now, we run pwd again, we're no more in your /tmp/joomla folder but in /var/www/html.

It can drive you mad but ... when entering in the Docker container, you're no more on your computer, you're virtually in another computer, the container. In that computer, the current folder is thus /var/www/html. By typing exit, you will leave the container, go back to your computer and back in the /tmp/joomla folder.

❯ pwd
/tmp/joomla
❯ docker compose exec joomla /bin/sh
$ pwd
/var/www/html
$ exit
❯ pwd
/tmp/joomla

Something else to try:

❯ php --version
command not found: php
❯ docker compose exec joomla /bin/sh
$ php --version
PHP 8.1.25 (cli) (built: Nov  1 2023 06:20:35) (NTS)
$ exit

So, on my computer (and probably on yours), by typing php --version, I got an error. That is correct. I don't have PHP on my computer. I work daily with PHP for years and I don't have it on my machine. 😄

Then I jump in the Joomla container and type the same command again and, yes, inside the Docker container of Joomla, yes, PHP is installed and here, It's the version 8.1.25.

Using alias

Docker will always start your project on your localhost and on a port like http://127.0.0.1:8080.

Instead of using the IP address, it would be much nicer to use an alias like http://kingsbridge:8080.

For this, on Windows, edit the file C:\Windows\System32\Drivers\etc\hosts and add the kingsbridge line as below illustrated:

127.0.0.1 localhost
127.0.0.1 kingsbridge

Save the file. Now you can surf to http://kingsbridge:8080

When creating an alias in the host file, some people prefer to use the .local suffix like in 127.0.0.1 kingsbridge.local to make clear it's a localhost site. If you prefer this, so the URL will be http://kingsbridge.local:8080

Using another port

Imagine you have another project, no more the Kingsbrige one. Can you have many Docker projects running at the same time? Yes! of course.

You just need to make sure to use another, unused, port.

Consider the Shiring project docker-compose.yml file

version: '3.9'

name: shiring

services:
  joomla:
    image: joomla
    ports:
      - 8081:80

  [...]

We will use the port 8081 for that project and, in your host file, we will add 127.0.0.1 shiring.

So, now and at the same time, we can access to http://kingsbridge:8080 and to http://shiring:8081 without conflicts since we have used a separate port number.

Kingsbridge can be a Joomla 4.4 / PHP 7.4 website while Shiring is on Joomla 5.0 / PHP 8.2 without any conflict. And that's just astonishingly simple, if you think back to the way you worked before Docker.

Using another port isn't mandatory. You can have several websites on the same port as 8080. But, in that case, we won't be able to use these websites at the same time. You can start the first one and when trying to start the second one, Docker will say port already in use. This isn't a problem; you can just run docker compose stop for the first one so free the port then start the second one.

In this article, I'm using port 8080 because Joomla has used it in his default docker-compose.yml file. You're not forced to use that one, you can perfectly use 80 and not 8080. In my daily work, I'm using ports 80, 81, 82, 83, ... varying the second figures for my projects.

Using phpmyadmin

Alongside Joomla and MySQL, it would be useful to have access to the database of your Joomla website. Can we use f.i. phpmyadmin, Adminer or pgadmin (for PostgreSQL) or ... ?

The answer is, yes, of course.

For the three mentioned above, there are official Docker images. For phpmyadmin, here it's: https://hub.docker.com/_/phpmyadmin

To use it, just run this command: docker run --name phpmyadmin -d --link joomladb:db --network kingsbridge_default -p 8089:80 phpmyadmin.

We will run the phpmyadmin (aka PMA) Docker image and

--name phpmyadmin allow us to give it a friendly name (optional)
-d is like --detach: the container should stay in up
--link joomladb:db: phpmyadmin should access to your Joomla database service. Remember the name in your docker-compose.yml file,
--network kingsbridge_default: your database server is accessible on the kingsbridge_default network and
-p 8089:80 tells Docker that we wish to access the web interface of PMA on port 8089

If you have forgotten the name of the network used by your containers, run docker compose up --detach again and you will see it. Otherwise run docker network list to get the list of networks.

❯ docker network list
NETWORK ID     NAME                  DRIVER    SCOPE
ddb1c1606b76   bridge                bridge    local
336cd6fec416   host                  host      local
16d351a0e393   kingsbridge_default   bridge    local
d8cdc43a7272   none                  null      local

To open phpmyadmin, start your browser and navigate to http://127.0.0.1:8089.

Did you remember your MySQL credentials? It was root / example.

Using Adminer

If you prefer Adminer, here is the command to run:

docker run -d --rm --name adminer --link joomladb:db --network kingsbridge_default -p 8088:8080 adminer

And here is the configured URL to use for Adminer: http://127.0.0.1:8088?server=joomladb&username=root&db=joomla_db. (joomla_db is the name of the database we've created earlier in chapter Install Joomla)

Did you prefer PostgreSQL or MariaDB ?

So far, we've chosen to use MySQL as our database manager. Our docker-compose.yml file is the one, slightly modified, that can be found on https://hub.docker.com/_/joomla.

Could you opt for something other than MySQL? Of course, as long as Joomla supports this system (see https://manual.joomla.org/docs/next/get-started/technical-requirements/).

We just need to replace the joomladb service, don't use anymore mysql but the one we wish.

Using PostgreSQL

Let's try PostgreSQL... We'll replace mysql. The official PostgreSQL Docker image can be retrieved on https://hub.docker.com/_/postgres. The documentation tell us which image we should use and how to define variables like the default password (POSTGRES_PASSWORD).

We also need to change a few variables:

The default database user should be specified and it will be f.i. postgres,
We should define too the name of the database in both services; we'll name our db joomla_db and
We need to inform Joomla that we'll use PostgreSQL so we need to set JOOMLA_DB_TYPE to pgsql (can be either mysql or pgsql).

This information has been retrieved from this Pull requests: https://github.com/joomla-docker/docker-joomla/pull/156.

Our docker-compose.yml will become:

version: '3.9'

name: kingsbridge

services:
  joomla:
    [...]
    environment:
      - JOOMLA_DB_HOST=joomladb
      - JOOMLA_DB_USER=postgres
      - JOOMLA_DB_PASSWORD=example
      - JOOMLA_DB_NAME=joomla_db
      - JOOMLA_DB_TYPE=pgsql

  joomladb:
    image: postgres:16.0-alpine
    [...]
    environment:
      - POSTGRES_DB=joomla_db
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=example

Now, during the configuration of Joomla, make sure to choose PostgreSQL (PDO) for the database type and fill in the database wizard with the correct values.

Use alpine images wherever possible
For the first time during this tutorial, we're using an alpine image (postgres:16.0-alpine here). These images are lighter than the not alpine image. They contain the bare essentials for running the service, whereas a traditional image contains additional tools, binaries, ... that you may need but are not certain to use.

Using MariaDB

If you plan to use MariaDB, here is the Docker Official Image: https://hub.docker.com/_/mariadb.

version: '3.9'

name: kingsbridge

services:
  joomla:
    [...]

  joomladb:
    image: mariadb:11.1.2
    [...]

For MariaDB, please select MySQLi during the installation wizard.

Extra information

The container will be restarted by Windows

If you shut down your computer, if one or more containers are still running, Docker will run them again on the next startup.

This means that the next time you start your computer, your website will still be accessible, and you won't have to run a single command. It's so easy!

Working with Windows

Imagine you're in your console (f.i. run cd /tmp/joomla in the Linux console) and you wish to open the site with Visual Studio Code, already installed on your Windows machine.

It's easy: just run code . to open the current folder so your project within vscode.

Another use case, you wish to start the Windows Explorer program and navigate in your project's structure. Here too, it's possible, just run explorer.exe . to open it and load the current directory. See my "Open your Linux folder in Windows Explorer" article to read more about this feature.

Make it easy

Only for Linux / WSL (not for DOS/PowerShell)
This chapter only concern Linux since DOS/PowerShell didn't support the GNU make command.

In this blog article, we have seen a lot of docker commands.

By alphabetical order:

docker compose down,
docker compose exec joomla /bin/sh,
docker compose kill,
docker compose logs --follow,
docker compose up --detach,
docker container list,
docker image list,
docker network list,
docker run -d --rm --name adminer --link joomladb:db --network kingsbridge_default -p 8088:8080 adminer and
docker run -d --rm --name phpmyadmin --link joomladb:db --network kingsbridge_default -p 8089:80 phpmyadmin

It's not easy to remember them all, so why not simplify things?

We will use GNU make for this.

First run which make in your Linux console to check if make is installed. If so, you will get f.i. /usr/bin/make as result. If you got make not found, please run sudo apt-get update && sudo apt-get -y install make to install it.

This done, we will create a new file called makefile in your directory. We will use code makefile to start Visual Studio code and create the makefile in your directory.

This file is specific to each project, not global.
The makefile, being created in your project folder, can contain instructions for that specific project. You could have one makefile for each project.

❯ pwd
/tmp/joomla

❯ code makefile

Now copy/paste this content in your makefile:

adminer:
  @printf "\e[1;033m%s\e[0m\n\n" "User is root and password is example. Please open http://127.0.0.1:8088?server=joomladb&username=root&db=joomla_db to open Adminer."
  @printf "\e[1;033m%s\e[0m\n\n" "Starting adminer. If the browser didn't open automatically, please surf to http://127.0.0.1:8088?server=joomladb&username=root&db=joomla_db to open adminer."
  docker run -d --rm --name adminer --link joomladb:db --network kingsbridge_default -p 8088:8080 adminer
  -sensible-browser http://localhost:8088 &

bash:
  @printf "\e[1;033m%s\e[0m\n\n" "Start an interactive shell in the Joomla Docker container; type exit to quit"
  docker compose exec joomla /bin/sh

code:
  code .

down:
  docker compose down

explorer:
  explorer.exe .

kill:
  docker compose kill

logs:
  docker compose logs --follow

start:
  @printf "\e[1;033m%s\e[0m\n\n" "Starting your website. If the browser didn't open automatically, please surf to http://127.0.0.1:8080 to open your site."
  -sensible-browser http://localhost:8080 &

up:
  docker compose up --detach

phpmyadmin:
  @printf "\e[1;033m%s\e[0m\n\n" "User is root and password is example. Please open http://127.0.0.1:8089 to open phpmyadmin."
  @printf "\e[1;033m%s\e[0m\n\n" "Starting phpmyadmin. If the browser didn't open automatically, please surf to http://127.0.0.1:8089 to open phpmyadmin."
  docker run --name phpmyadmin -d --link joomladb:db --network kingsbridge_default -p 8089:80 phpmyadmin
  -sensible-browser http://localhost:8089 &

Make sure indentation is using tabs, not space.

Save and close vscode.

Make sure values are correct
The makefile here above contains hardcoded values like joomla_db for the database name. Make sure these values are still correct when you'll reuse this file for other projects.

The indentation in makefile SHOULD BE made using tabs and not spaces, this is crucial. So please make sure, if your file didn't work, you know what to do.

Now, instead of running f.i. docker compose up --detach for running your Joomla site, just run make up. Instead of running docker run --name phpmyadmin -d --link joomladb:db --network kingsbridge_default -p 8089:80 phpmyadmin to start phpmyadmin, just run make phpmyadmin. To launch the browser and surf on your site, it will be make start.

Use printf to echo valuable information
By typing make phpmyadmin, it would be nice to see, on the console, the credentials to use and a small tip like this:

❯ make phpmyadmin
User is root and password is example. Please open http://127.0.0.1:8089 to open phpmyadmin.

docker run --name phpmyadmin -d --link joomladb:db --network kingsbridge_default -p 8089:80 phpmyadmin
a0c37edd9f8c139556f1f0a6b028ec5102362f16233efbc05f56d184edfb83c9

To do this, just use the printf function like illustrated above.

Please read my Makefile - Tutorial and Tips & Tricks GitHub repository if you wish to learn more about Make.

Feel free to add your own make instructions; can be multiline.

Final docker-compose.yml

In the introduction of this article, I have said we will learn how to use Docker to install Joomla and start a new website **in seconds**.

This is how:

On your computer, create a folder for your new project (f.i. mkdir ~/projects/my_new_project && cd $_)
In that folder, create a docker-compose.yml file with this content:

  version: '3.9'

  name: yourprojectname

  services:
    joomla:
      image: joomla:5.0.0-php8.2-apache
      container_name: kingsbridge-app
      restart: always
      ports:
        - 8080:80
      environment:
        - JOOMLA_DB_HOST=joomladb
        - JOOMLA_DB_PASSWORD=example
      user: 1000:1000
      volumes:
        - ./site_joomla:/var/www/html
      depends_on:
        - joomladb

    joomladb:
      image: mysql:8.0.13
      container_name: kingsbridge-db
      restart: always
      environment:
        - MYSQL_ROOT_PASSWORD=example
      user: 1000:1000
      volumes:
        - ./db:/var/lib/mysql

Create your two sub-folders: mkdir db site_joomla
Run docker compose up --detach to start Docker and create your containers
Wait a few seconds and your new site is up.

Make sure, for each project, to update the name: line and if you plan to be able to run your Joomla sites concurrently, make sure to update the port number for Joomla and chose a new one every time (can be 80, 81, 82 and so one).

FrankenPHP instead of Apache

A new player is entering the game: FrankenPHP. This is a new application server which can be used instead of Apache or nginx.

Based on their documentation, it is 3.5 faster than PHP FPM. If you want to learn how to run Joomla on FrankenPHP, please read this post article: FrankenPHP, a modern application server for PHP. We'll discover the work of Alexandre Elisé on this.

Using volumes with Docker, use cases

Christophe Avonture — Fri, 24 Nov 2023 08:03:10 +0000

When working with a Docker container, data can be persistent or not. Imagine you're creating a localhost website with Joomla, Wordpress or any other tool (Laravel, Symfony, etc.).

You've perfectly created the various Docker files needed to run the local site, you've run the command docker compose up --detach to start the containers and now you're busy installing the site. After a few moments, your local site is up and you can start developing its functionalities.

By default, if you haven't taken any precautions, the moment you stop the container (docker compose down), you'll kill your site, i.e. by default, having not taken care to save your data (your site, your database), everything will be lost and reset the next time you run docker compose up --detach. Well... Maybe that was your wish (something totally ephemeral); maybe not;

To illustrate the notion of persistence, we're going to work with a Docker image that we'll create with our own little hands, and which will never be anything more than an execution counter. Each time the container is executed, you'll see "You have executed this script 1 time", and this number will increase with each execution.

Creation of our Docker image

For the illustration, please start a Linux shell and run mkdir -p /tmp/counter && cd $_.

Now that you're in a temporary folder on your disk, please create a new file called Dockerfile with this content:

FROM alpine:3.14

COPY counter.sh counter.sh

RUN chmod +x counter.sh

ENTRYPOINT ["tail", "-f", "/dev/null"]

Please, too, create a file called counter.sh with this content:

#!/usr/bin/env sh

if [[ ! -f /data/counter.txt ]]; then
    mkdir -p /data
    echo "Creating /data/counter.txt ..."
    echo "0" > /data/counter.txt
fi

counter=$((`cat /data/counter.txt`+1))

echo "You have executed this script ${counter} times."

echo "${counter}" > /data/counter.txt

Now, just create the Docker image by running docker build -t demo/counter ..

❯ docker image list
REPOSITORY     TAG       IMAGE ID       CREATED          SIZE
demo/counter   latest    89505911ec33   21 minutes ago   5.61MB

Can't be smaller
As you can see, our image is really small. This is the advantage using the alpine Docker image.

Using our image

Now, it's time to create our docker-compose.yml file with this content:

version: '3.9'

name: demo

services:

  counter:
    build: .
    container_name: counter
    image: demo/counter

We'll run our container by running docker compose up --detach:

❯ docker compose up --detach
[+] Building 0.0s (0/0)                    docker:default
[+] Running 3/3
 ✔ Network demo_default  Created           0.2s
 ✔ Volume "demo_data"    Created           0.1s
 ✔ Container counter     Started

We can verify our container is running using docker container list (simplified output):

❯ docker container list
CONTAINER ID   IMAGE          STATUS          NAMES
6296459f7827   demo/counter   Up 30 seconds   counter

Calling our container for the first time

docker compose exec counter /counter.sh is the command to use to execute our script and we'll call it multiple times:

❯ docker compose exec counter /counter.sh
You have executed this script 1 times.

❯ docker compose exec counter /counter.sh
You have executed this script 2 times.

❯ docker compose exec counter /counter.sh
You have executed this script 3 times.

❯ docker compose exec counter /counter.sh
You have executed this script 4 times.

❯ docker compose exec counter /counter.sh
You have executed this script 5 times.

Ok so we have validated that our counter is working fine.

What about if we stop the container and start it again by running docker compose down ; docker compose up --detach.

Running our counter again:

❯ docker compose exec counter /counter.sh
You have executed this script 1 times.

We've lost our data
As you can see, we've lost our counter. By stopping and starting the container, our data has been lost. And that's perfectly normal, because that's the intrinsic concept of a Docker container: it's ephemeral. A container should be disposable; by restarting it, the container is reset.

Introducing the notion of volume

There are two types of volumes, the ones managed by Docker and, on the other side, mounted volumes.

Volumes managed by Docker

Update the docker-compose.yml file like this:

version: '3.9'

name: demo

services:

  counter:
    build: .
    container_name: counter
    image: demo/counter
    volumes:
      - counter_data:/data

volumes:
  counter_data:

As you can see, we're using a volumes (always plural form) and we're saying that the /data folder inside the container should be mapped to a volume called counter_data. At the bottom of the docker-compose.yml file, we are just declaring our volume.

We'll start our container again: docker compose down ; docker compose up --detach.

But now, we should have a Docker volume called counter_data; let's check:

❯ docker volume list
DRIVER    VOLUME NAME
local     demo_counter_data

Yes, we've it.

Let's try again some calls then stop/restart and a few calls then:

❯ docker compose exec counter /counter.sh
Creating /data/counter.txt ...
You have executed this script 1 times.
❯ docker compose exec counter /counter.sh
You have executed this script 2 times.
❯ docker compose exec counter /counter.sh
You have executed this script 3 times.
❯ docker compose exec counter /counter.sh
You have executed this script 4 times.
❯ docker compose exec counter /counter.sh
You have executed this script 5 times.
❯ docker compose exec counter /counter.sh
You have executed this script 6 times.

❯ docker compose down ; docker compose up --detach
[+] Running 2/2
 ✔ Container counter     Removed    11.1s
 ✔ Network demo_default  Removed     0.5s
[+] Building 0.0s (0/0)    docker:default
[+] Running 2/2
 ✔ Network demo_default  Created     0.2s
 ✔ Container counter     Started     0.7s

❯ docker compose exec counter /counter.sh
You have executed this script 7 times.
❯ docker compose exec counter /counter.sh
You have executed this script 8 times.
❯ docker compose exec counter /counter.sh
You have executed this script 9 times.
❯ docker compose exec counter /counter.sh
You have executed this script 10 times.

So, our counter was well persistent this time
As you can see, by running down followed by up, we have kept the value of our counter. This value is saved in a file which is now stored in a Docker volume. As long as we don't delete the volume, our value will be preserved.

You can remove the volume by running docker volume rm demo_counter_data but:

❯ docker volume rm demo_counter_data
Error response from daemon: remove demo_counter_data: volume is in use - [b976c92eed6ed4e54f6ec75d652b8977bbbd86392e604216dd61d0c446e1fc0c]

Indeed, you can't remove a volume if there is still, at least, one container who use it so, you should run docker compose down && docker volume rm demo_counter_data or, simpler, docker compose down --volumes. The --volumes flag says to remove any volume declared in the docker-compose.yml file.

Location of the volumes

Volumes are stored somewhere on the disk by Docker, you don't need to take care about this.

Just keep in mind that files are not saved in your folder; let's check this:

> cd /tmp/counter

> ls -alh
total 28K
drwxr-xr-x  2 christophe christophe 4.0K Nov 22 09:40 .
drwxrwxrwt 28 root       root        12K Nov 22 09:35 ..
-rw-r--r--  1 christophe christophe  109 Nov 22 09:36 Dockerfile
-rw-r--r--  1 christophe christophe  287 Nov 22 10:00 counter.sh
-rw-r--r--  1 christophe christophe  190 Nov 22 10:09 docker-compose.yml

Files are not stored in our project
As you can see, we've only our files, not the counter. Files stored in a volume managed by Docker aren't stored in our project's directory.

Location
In fact, volumes are stored in \\wsl$\docker-desktop-data\data\docker\volumes if you're running WSL but it's really a bad idea to access files directly from there. Let Docker do the job for you.

Accessing files in the volume

Using Docker Desktop

One of the easiest ways to access the files contained in a volume is to use the Docker Desktop graphical interface.

By clicking of the volume name (demo_counter_data here)

By double-clicking on the filename, you'll start a basic text editor where you can, if you want, update the counter and save the change.

A new call to our counter shows that we have hacked the number:

❯ docker compose exec counter /counter.sh
You have executed this script 51 times.

Using vscode

But you can, too, use Visual Studio code to access files.

First, if needed, install the Docker extension:

Press CTRL+SHIFT+X to display the Extensions window of vscode,
Search for the Docker extension of Microsoft (make sure to search for ms-azuretools.vscode-docker),
and Install the extension

Now, in the left pane, you'll see a new button for Docker. Click on it.

In the new window, you'll get the list of containers, the list of images and other things.

Deploy the list of containers, click on demo/counter (our container) and display the list of files.

Open the data root folder and right-click on counter.txt, our counter file and select Open.

Now, you can edit that file from vscode, make changes and save them.

❯ docker compose exec counter /counter.sh
You have executed this script 101 times.

Yes, accessing files using vscode works too.

Mounted volumes

A mounted volume is synchronized with your hard disk. Instead of letting Docker manage everything for you, you'll decide where files should be stored.

Let's make a few cleaning right now, please run docker compose down --volumes to kill the volume used in the previous chapter and kill the docker container.

Update the docker-compose.yml file like this:

version: '3.9'

name: demo

services:

  counter:
    build: .
    container_name: counter
    image: demo/counter
    volumes:
      - ./data:/data

The syntax now is, just a few, different: we don't have a volumes entry at the bottom of the file but we've used a relative notation like ./data:/data. So, the ./data local folder (on your hard disk) has to be synchronized with the /data folder of the container.

By running docker compose up --detach && docker compose exec counter /counter.sh we'll run our counter and expect to see You have executed this script 1 times. but you'll probably get an error:

❯ docker compose exec counter /counter.sh
Creating /data/counter.txt ...
/counter.sh: line 6: can't create /data/counter.txt: nonexistent directory
cat: can't open '/data/counter.txt': No such file or directory
You have executed this script 1 times.
/counter.sh: line 13: can't create /data/counter.txt: nonexistent directory

We need to create our local data folder:

❯ mkdir data

❯ ls -alh
total 32K
drwxr-xr-x  3 christophe christophe 4.0K Nov 22 10:54 .
drwxrwxrwt 28 root       root        12K Nov 22 09:35 ..
-rw-r--r--  1 christophe christophe  109 Nov 22 09:36 Dockerfile
-rw-r--r--  1 christophe christophe  287 Nov 22 10:00 counter.sh
drwxr-xr-x  2 christophe christophe 4.0K Nov 22 10:54 data
-rw-r--r--  1 christophe christophe  149 Nov 22 10:48 docker-compose.yml

Now that we've our data folder, try again:

❯ docker compose up --detach && docker compose exec counter /counter.sh
[+] Building 0.0s (0/0)        docker:default
[+] Running 2/2
 ✔ Network demo_default  Created         0.2s
 ✔ Container counter     Started         0.8s
Creating /data/counter.txt ...
You have executed this script 1 times.

This time, the counter.txt file is present in our directory:

❯ ls -alh data
total 12K
drwxr-xr-x 2 christophe christophe 4.0K Nov 22 10:56 .
drwxr-xr-x 3 christophe christophe 4.0K Nov 22 10:54 ..
-rw-r--r-- 1 root       root          2 Nov 22 10:56 counter.txt

Oups, the file is owned by root not me
Uh oh! The file is owned by the root user and not me (i.e. user christophe in my case). That's annoying since I can't edit it or remove it without using sudo.

The file is owned by root because the current user; used inside the container, is the root user. We need to inform Docker that he has to use ours.

To do this, we'll update once more our docker-compose.yml file:

version: '3.9'

name: demo

services:

  counter:
    build: .
    container_name: counter
    image: demo/counter
    user: 1000:1000
    volumes:
      - ./data:/data

Why 1000:1000?
We need to pass to Docker our current user id and group id so Docker will be able to create files/folders using our user. To get your current user id and group id, just run echo "$(id -u):$(id -g)" in the console and, you'll see, the first created user (after the installation of Linux) is, always, user id 1000, group id 1000. Most probably you.

Let's try again but, first remove the incorrect file: sudo rm -f data/counter.txt

Then run docker compose down && docker compose up --detach && docker compose exec counter /counter.sh

Now, the file will be yours:

❯ ls -alh data
total 12K
drwxr-xr-x 2 christophe christophe 4.0K Nov 22 10:56 .
drwxr-xr-x 3 christophe christophe 4.0K Nov 22 10:54 ..
-rw-r--r-- 1 christophe christophe    2 Nov 22 10:56 counter.txt

Conclusion

We've seen three ways of playing with data:

We don't care about data,
We rely on Docker to manage the volume for us and
We really value our data and want it to be part of our project.

Depending on your needs, you can opt for one of three solutions.

You want to play with a Docker container, test it, learn from it... You don't want to keep any traces on your hard disk. The first solution is perfect here i.e. don't matter about volumes.

You want to test but also keep the data somewhere without polluting your hard disk. You're working on something temporary, so you may want to keep the data, but you can't be sure. The second solution will suit you best i.e. self managed volumes.

On the contrary, your work is important and you don't want to lose anything. Your data must be saved on your hard disk. The third solution will be the one you use i.e. mounted volumes.

Working with Laravel events

Christophe Avonture — Sun, 19 Feb 2023 06:51:30 +0000

How to dispatch an event and process returned values

You need to run an event having one or more listeners and, in your main code, you wish to retrieve some values once listeners have done their job.

In our example below, we'll fire a SampleEvent class and his SampleListener. The idea is to initialize an employee.

File app/Providers/EventServiceProvider.php

protected $listen = [
    SampleEvent::class => [
        SampleListener::class,
    ],
];

For our sample, your routes/web.php can looks like this:

use App\Employee;
use App\Events\SampleEvent;

Route::get('/', function () {
    $employee = new Employee();

    SampleEvent::dispatch($employee);

    echo 'FIRSTNAME is ' . $employee->getFirstName() . PHP_EOL;
    echo 'NAME      is ' . $employee->getLastName()  . PHP_EOL;
    echo 'PSEUDO    is ' . $employee->getPseudo()  . PHP_EOL;
});

What we do is:

Create a new employee based on the Employee class,
Call our SampleEvent event and give our new employee,
Let the magic happens,
Display the employee's first and last name.

Here, by default, our employee.

File app/Employee.php

This class will initialize our employee and provide setters and getters.

By default, our employee will be called John Doe (cavo789).

<?php

namespace App;

class Employee
{
    public function __construct(
        private string $firstname = 'John',
        private string $lastname  = 'Doe',
        private string $pseudo    = 'cavo789'
    ) {
    }

    public function getFirstName(): string
    {
        return $this->firstname;
    }

    public function setFirstName(string $firstname)
    {
        $this->firstname = $firstname;
        return $this;
    }

    public function getLastName(): string
    {
        return $this->lastname;
    }

    public function setLastName(string $lastname)
    {
        $this->lastname = $lastname;
        return $this;
    }

    public function getPseudo(): string
    {
        return $this->pseudo;
    }

    public function setPseudo(string $pseudo)
    {
        $this->pseudo = $pseudo;
        return $this;
    }
};

File app/Events/SampleEvent.php

Our event will receive an employee and make it private.

Make three setters public to allow listeners to update the first and the last name. Also allow to initialize the pseudo.

<?php

namespace App\Events;

use App\Employee;
use Illuminate\Foundation\Events\Dispatchable;

class SampleEvent
{
    use Dispatchable;

    public function __construct(private Employee $employee)
    {
    }

    public function setFirstName(string $firstname): self
    {
        $this->employee->setFirstName($firstname);
        return $this;
    }

    public function setLastName(string $lastname): self
    {
        $this->employee->setLastName($lastname);
        return $this;
    }

    public function setPseudo(string $pseudo): self
    {
        $this->employee->setPseudo($pseudo);
        return $this;
    }
}

File app/Listeners/SampleListener.php

Our listener logic. SampleListener will receive the SampleEvent as parameter and, thus, has access to all his public methods. We'll here update the first and the lastname, we'll not update the pseudo.

<?php

namespace App\Listeners;

use App\Events\SampleEvent;

class SampleListener
{
    public function handle(SampleEvent $event): void
    {
        $event->setFirstName('Georges')->setLastName('Washington');
    }
}

The result

If we run curl localhost in the console, we'll get the output below showing us it has worked perfectly as expected.

FIRSTNAME is Georges
NAME      is Washington
PSEUDO    is cavo789

If we edit back the app/Providers/EventServiceProvider.php file and comment the listener like below illustrated, our code will still works

protected $listen = [
    SampleEvent::class => [
        // SampleListener::class,
    ],
];

FIRSTNAME is John
NAME      is Doe
PSEUDO    is cavo789

Photo credit: Jason Rosewell on Unsplash

Docker - Run/Refactor PHP code from a web interface

Christophe Avonture — Sat, 01 Jan 2022 11:11:31 +0000

As a loyal reader of several forums for years, I frequently find unreadable PHP code posted by beginners asking for help. Before we can try to help them, it is sometimes useful to reformat the code and rewrite it partially. This can take times...

To execute the code to see where the problem is before fixing it, I have been using the Run-PHP-Code tool for a few years but it does not meet the need for reformatting (php-cs-fixer / php code-beautifier) or refactoring (rector). Second disadvantage here (since I don't trust the PHP code), Run-PHP-Code is running on my localhost i.e. on my machine and that can represent a risk (creation/deletion of files, ...). The ideal is to execute the code in a sandbox.

It had been a while since I wanted to do it: I took some hours to take the code of Run-PHP-Code to make his own Docker image, based on PHP 7.4.26 (version 1.0) or 8.1 (version 1.1) and thus to allow to run it in a secure environment.

I also took the time to add a "refactor" button which then calls php-cs-fixer, phpcbf and Rector.

The result is this ready-to-use Docker image: https://hub.docker.com/r/cavo789/runcode.

In only two CLI commands, you will have a web interface with an editor where, on the left side, you can copy/paste or type a PHP code and on the right side visualize the result of its execution (button Run) or its refactoring (button Refactor); the whole running in a Docker container and thus isolated from your machine.

Pretty easy and helpful when trying to give support on forums.