CONTAINER.md: Include documentation for ecs container image

CONTAINER.md

@@ -1,10 +1,10 @@
 
 [![GitHub tag (latest SemVer)](https://img.shields.io/github/v/tag/processone/ejabberd?sort=semver&logo=embarcadero&label=&color=49c0c4)](https://github.com/processone/ejabberd/tags)
-[![ejabberd Container on GitHub](https://img.shields.io/github/v/tag/processone/ejabberd?label=ejabberd&sort=semver&logo=docker)](https://github.com/processone/ejabberd/pkgs/container/ejabberd)
+[![ejabberd Container on GitHub](https://img.shields.io/github/v/tag/processone/ejabberd?label=ejabberd&sort=semver&logo=opencontainersinitiative&logoColor=2094f3)](https://github.com/processone/ejabberd/pkgs/container/ejabberd)
 [![ecs Container on Docker](https://img.shields.io/docker/v/ejabberd/ecs?label=ecs&sort=semver&logo=docker)](https://hub.docker.com/r/ejabberd/ecs/)
 
-`ejabberd` Container Image
+ejabberd Container Images
-==========================
+=========================
 
 [ejabberd][home] is an open-source,
 robust, scalable and extensible realtime platform built using [Erlang/OTP][erlang],
@@ -16,26 +16,29 @@ that includes [XMPP][xmpp] Server, [MQTT][mqtt] Broker and [SIP][sip] Service.
 [mqtt]: https://mqtt.org/
 [sip]: https://en.wikipedia.org/wiki/Session_Initiation_Protocol
 
-This document explains how to use the `ejabberd` container image available in
+This page documents those container images ([images comparison](#images-comparison)):
-[ghcr.io/processone/ejabberd](https://github.com/processone/ejabberd/pkgs/container/ejabberd),
-built using the files in `.github/container/`.
-This image is based in Alpine 3.19, includes Erlang/OTP 27.2 and Elixir 1.18.1.
 
-Alternatively, there is also the `ecs` container image available in
+- [![ejabberd Container](https://img.shields.io/badge/ejabberd-grey?logo=opencontainersinitiative&logoColor=2094f3)](https://github.com/processone/ejabberd/pkgs/container/ejabberd)  
-[docker.io/ejabberd/ecs](https://hub.docker.com/r/ejabberd/ecs/),
+  published in [ghcr.io/processone/ejabberd](https://github.com/processone/ejabberd/pkgs/container/ejabberd),
-built using the
+  built using [ejabberd](https://github.com/processone/ejabberd/tree/master/.github/container) repository,
-[docker-ejabberd/ecs](https://github.com/processone/docker-ejabberd/tree/master/ecs)
+  both for stable ejabberd releases and the `master` branch, in x64 and arm64 architectures.
-repository.
-Check the [differences between `ejabberd` and `ecs` images](https://github.com/processone/docker-ejabberd/blob/master/ecs/HUB-README.md#alternative-image-in-github).
 
-If you are using a Windows operating system, check the tutorials mentioned in
+- [![ecs Container](https://img.shields.io/badge/ecs-grey?logo=docker&logoColor=2094f3)](https://hub.docker.com/r/ejabberd/ecs/)  
-[ejabberd Docs > Docker Image](https://docs.ejabberd.im/admin/install/container/#ejabberd-container-image).
+  published in [docker.io/ejabberd/ecs](https://hub.docker.com/r/ejabberd/ecs/),
+  built using [docker-ejabberd/ecs](https://github.com/processone/docker-ejabberd/tree/master/ecs) repository
+  for ejabberd stable releases in x64 architectures.
+
+For Microsoft Windows, see
+[Docker Desktop for Windows 10](https://www.process-one.net/blog/install-ejabberd-on-windows-10-using-docker-desktop/),
+and [Docker Toolbox for Windows 7](https://www.process-one.net/blog/install-ejabberd-on-windows-7-using-docker-toolbox/).
+
+For Kubernetes Helm, see [help-ejabberd](https://github.com/sando38/helm-ejabberd).
 
 
 Start ejabberd
 --------------
 
-### With default configuration
+### daemon
 
 Start ejabberd in a new container:
 
@@ -46,22 +49,28 @@ docker run --name ejabberd -d -p 5222:5222 ghcr.io/processone/ejabberd
 That runs the container as a daemon,
 using ejabberd default configuration file and XMPP domain `localhost`.
 
-Stop the running container:
-
-```bash
-docker stop ejabberd
-```
-
 Restart the stopped ejabberd container:
 
 ```bash
 docker restart ejabberd
 ```
 
+Stop the running container:
 
-### Start with Erlang console attached
+```bash
+docker stop ejabberd
+```
 
-Start ejabberd with an Erlang console attached using the `live` command:
+Remove the ejabberd container:
+
+```bash
+docker rm ejabberd
+```
+
+
+### with Erlang console
+
+Start ejabberd with an interactive Erlang console attached using the `live` command:
 
 ```bash
 docker run --name ejabberd -it -p 5222:5222 ghcr.io/processone/ejabberd live
@@ -70,40 +79,42 @@ docker run --name ejabberd -it -p 5222:5222 ghcr.io/processone/ejabberd live
 That uses the default configuration file and XMPP domain `localhost`.
 
 
-### Start with your configuration and database
+### with your data
 
 Pass a configuration file as a volume
 and share the local directory to store database:
 
 ```bash
-mkdir database
+mkdir conf && cp ejabberd.yml.example conf/ejabberd.yml
-chown ejabberd database
 
-cp ejabberd.yml.example ejabberd.yml
+mkdir database && chown ejabberd database
 
 docker run --name ejabberd -it \
-  -v $(pwd)/ejabberd.yml:/opt/ejabberd/conf/ejabberd.yml \
+  -v $(pwd)/conf/ejabberd.yml:/opt/ejabberd/conf/ejabberd.yml \
   -v $(pwd)/database:/opt/ejabberd/database \
   -p 5222:5222 ghcr.io/processone/ejabberd live
 ```
 
-Notice that ejabberd runs in the container with an account named `ejabberd`,
+Notice that ejabberd runs in the container with an account named `ejabberd`
+with UID 9000 and group `ejabberd` with GID 9000,
 and the volumes you mount must grant proper rights to that account.
 
 
 Next steps
 ----------
 
-### Register the administrator account
+### Register admin account
+
+#### [![ejabberd Container](https://img.shields.io/badge/ejabberd-grey?logo=opencontainersinitiative&logoColor=2094f3)](https://github.com/processone/ejabberd/pkgs/container/ejabberd) [:orange_circle:](#images-comparison)
 
 If you set the `REGISTER_ADMIN_PASSWORD` environment variable,
-an account is registered with that password,
+an account is automatically registered with that password,
 and admin privileges are granted to it.
-The account created may be:
+The account created depends on what variables you have set:
 
-- `EJABBERD_MACRO_ADMIN=juliet@example.org` --> `juliet@example.org`
+- `EJABBERD_MACRO_ADMIN=juliet@example.org` -> `juliet@example.org`
-- `EJABBERD_MACRO_HOST=example.org` --> `admin@example.org`
+- `EJABBERD_MACRO_HOST=example.org` -> `admin@example.org`
-- None of those variables are set --> `admin@localhost`
+- None of those variables are set -> `admin@localhost`
 
 The account registration is shown in the container log:
 
@@ -113,15 +124,22 @@ User admin@example.org successfully registered
 ```
 
 Alternatively, you can register the account manually yourself
-and edit conf/ejabberd.yml and add the ACL as explained in
+and edit `conf/ejabberd.yml` and add the ACL as explained in
-[ejabberd Docs: Administration Account](https://docs.ejabberd.im/admin/install/next-steps/#administration-account):
+[ejabberd Docs: Administration Account](https://docs.ejabberd.im/admin/install/next-steps/#administration-account).
+
+---
+
+#### [![ecs Container](https://img.shields.io/badge/ecs-grey?logo=docker&logoColor=2094f3)](https://hub.docker.com/r/ejabberd/ecs/)
+
+The default ejabberd configuration has already granted admin privilege
+to an account that would be called `admin@localhost`,
+so you just need to register it, for example:
 
 ```bash
 docker exec -it ejabberd ejabberdctl register admin localhost passw0rd
 ```
 
-
+### Check ejabberd log
-### Check ejabberd log files
 
 Check the content of the log files inside the container,
 even if you do not put it on a shared persistent drive:
@@ -131,7 +149,7 @@ docker exec -it ejabberd tail -f logs/ejabberd.log
 ```
 
 
-### Inspect the container files
+### Inspect container files
 
 The container uses Alpine Linux. Start a shell inside the container:
 
@@ -140,7 +158,7 @@ docker exec -it ejabberd sh
 ```
 
 
-### Open ejabberd debug console
+### Open debug console
 
 Open an interactive debug Erlang console attached to a running ejabberd in a running container:
 
@@ -165,7 +183,7 @@ docker exec -it ejabberd vi conf/ejabberd.yml
 
 and add this option:
 ```yaml
-captcha_cmd: /opt/ejabberd-22.04/lib/captcha.sh
+captcha_cmd: "$HOME/bin/captcha.sh"
 ```
 
 Finally, reload the configuration file or restart the container:
@@ -186,21 +204,22 @@ For more details about CAPTCHA options, please check the
 documentation section.
 
 
-Advanced Container Configuration
+Advanced
---------------------------------
+--------
 
 ### Ports
 
-This container image exposes the ports:
+The container image exposes several ports
+(check also [Docs: Firewall Settings](https://docs.ejabberd.im/admin/guide/security/#firewall-settings)):
 
 - `5222`: The default port for XMPP clients.
 - `5269`: For XMPP federation. Only needed if you want to communicate with users on other servers.
 - `5280`: For admin interface (URL is `admin/`).
-- `1880`: For admin interface (URL is `/`, useful for podman-desktop and docker-desktop)
+- `1880`: For admin interface (URL is `/`, useful for [podman-desktop](https://podman-desktop.io/) and [docker-desktop](https://www.docker.com/products/docker-desktop/)) [:orange_circle:](#images-comparison)
 - `5443`: With encryption, used for admin interface, API, CAPTCHA, OAuth, Websockets and XMPP BOSH.
 - `1883`: Used for MQTT
 - `4369-4399`: EPMD and Erlang connectivity, used for `ejabberdctl` and clustering
-- `5210`: Erlang connectivity when `ERL_DIST_PORT` is set, alternative to EPMD
+- `5210`: Erlang connectivity when `ERL_DIST_PORT` is set, alternative to EPMD [:orange_circle:](#images-comparison)
 
 
 ### Volumes
@@ -217,11 +236,26 @@ You should back up or export the content of the directory to persistent storage
 - `/opt/ejabberd/logs/`: Directory containing log files
 - `/opt/ejabberd/upload/`: Directory containing uploaded files. This should also be backed up.
 
-All these files are owned by `ejabberd` user inside the container.
+All these files are owned by an account named `ejabberd` with group `ejabberd` in the container.
+Its corresponding `UID:GID` is `9000:9000`.
+If you prefer bind mounts instead of volumes, then
+you need to map this to valid `UID:GID` on your host to get read/write access on
+mounted directories.
 
-It's possible to install additional ejabberd modules using volumes,
+If using Docker, try:
-[this comment](https://github.com/processone/docker-ejabberd/issues/81#issuecomment-1036115146)
+```bash
-explains how to install an additional module using docker-compose.
+mkdir database
+sudo chown 9000:9000 database
+```
+
+If using Podman, try:
+```bash
+mkdir database
+podman unshare chown 9000:9000 database
+```
+
+It's possible to install additional ejabberd modules using volumes, check
+[this Docs tutorial](http://docs.ejabberd.im/developer/extending-ejabberd/modules/#your-module-in-ejabberd-modules-with-ejabberd-container).
 
 
 ### Commands on start
@@ -245,10 +279,10 @@ Example usage (or check the [full example](#customized-example)):
 ```
 
 
-### Macros in environment
+### Macros in environment [:high_brightness:](#images-comparison)
 
 ejabberd reads `EJABBERD_MACRO_*` environment variables
-and uses them to define the `*`
+and uses them to define the corresponding
 [macros](https://docs.ejabberd.im/admin/configuration/file-format/#macros-in-configuration-file),
 overwriting the corresponding macro definition if it was set in the configuration file.
 This is supported since ejabberd 24.12.
@@ -258,18 +292,61 @@ For example, if you configure this in `ejabberd.yml`:
 ```yaml
 acl:
   admin:
-    user: ADMINJID
+    user: ADMIN
 ```
 
 now you can define the admin account JID using an environment variable:
 ```yaml
     environment:
-      - EJABBERD_MACRO_ADMINJID=admin@localhost
+      - EJABBERD_MACRO_ADMIN=admin@localhost
 ```
 
 Check the [full example](#customized-example) for other example.
 
 
+### ejabberdapi
+
+When the container is running (and thus ejabberd), you can exec commands inside the container
+using `ejabberdctl` or any other of the available interfaces, see
+[Understanding ejabberd "commands"](https://docs.ejabberd.im/developer/ejabberd-api/#understanding-ejabberd-commands)
+
+Additionally, the container image includes the `ejabberdapi` executable.
+Please check the [ejabberd-api homepage](https://github.com/processone/ejabberd-api)
+for configuration and usage details.
+
+For example, if you configure ejabberd like this:
+```yaml
+listen:
+  -
+    port: 5282
+    module: ejabberd_http
+    request_handlers:
+      "/api": mod_http_api
+
+acl:
+  loopback:
+    ip:
+      - 127.0.0.0/8
+      - ::1/128
+      - ::FFFF:127.0.0.1/128
+
+api_permissions:
+  "admin access":
+    who:
+      access:
+        allow:
+          acl: loopback
+    what:
+      - "register"
+```
+
+Then you could register new accounts with this query:
+
+```bash
+docker exec -it ejabberd ejabberdapi register --endpoint=http://127.0.0.1:5282/ --jid=admin@localhost --password=passw0rd
+```
+
+
 ### Clustering
 
 When setting several containers to form a
@@ -284,6 +361,8 @@ For this you can either:
 - edit `conf/ejabberdctl.cfg` and set variables `ERLANG_NODE` and `ERLANG_COOKIE`
 - set the environment variables `ERLANG_NODE_ARG` and `ERLANG_COOKIE`
 
+---
+
 Example to connect a local `ejabberdctl` to a containerized ejabberd:
 
 1. When creating the container, export port 5210, and set `ERLANG_COOKIE`:
@@ -293,7 +372,7 @@ Example to connect a local `ejabberdctl` to a containerized ejabberd:
       -p 5210:5210 -p 5222:5222 \
       ghcr.io/processone/ejabberd
     ```
-2. Set `ERL_DIST_PORT=5210` in ejabberdctl.cfg of container and local ejabberd
+2. Set `ERL_DIST_PORT=5210` in `ejabberdctl.cfg` of container and local ejabberd
 3. Restart the container
 4. Now use `ejabberdctl` in your local ejabberd deployment
 
@@ -309,19 +388,175 @@ Example using environment variables (see full example [docker-compose.yml](https
       - ERLANG_COOKIE=dummycookie123
 ```
 
+---
 
-Build `ejabberd` Container Image
+Once you have the ejabberd nodes properly set and running,
---------------------------------
+you can tell the secondary nodes to join the master node using the
+[`join_cluster`](https://docs.ejabberd.im/developer/ejabberd-api/admin-api/#join-cluster)
+API call.
 
-This container image includes ejabberd as a standalone OTP release built using Elixir.
+Example using environment variables (see the full
-That OTP release is configured with:
+[`docker-compose.yml` clustering example](#clustering-example)):
+```yaml
+environment:
+  - ERLANG_NODE_ARG=ejabberd@replica
+  - ERLANG_COOKIE=dummycookie123
+  - CTL_ON_CREATE=join_cluster ejabberd@main
+```
+
+### Change Mnesia Node Name
+
+To use the same Mnesia database in a container with a different hostname,
+it is necessary to change the old hostname stored in Mnesia.
+
+This section is equivalent to the ejabberd Documentation
+[Change Computer Hostname](https://docs.ejabberd.im/admin/guide/managing/#change-computer-hostname),
+but particularized to containers that use this
+ecs container image from ejabberd 23.01 or older.
+
+#### Setup Old Container
+
+Let's assume a container running ejabberd 23.01 (or older) from
+this ecs container image, with the database directory binded
+and one registered account.
+This can be produced with:
+```bash
+OLDCONTAINER=ejaold
+NEWCONTAINER=ejanew
+
+mkdir database
+sudo chown 9000:9000 database
+docker run -d --name $OLDCONTAINER -p 5222:5222 \
+       -v $(pwd)/database:/opt/ejabberd/database \
+       ghcr.io/processone/ejabberd:23.01
+docker exec -it $OLDCONTAINER ejabberdctl started
+docker exec -it $OLDCONTAINER ejabberdctl register user1 localhost somepass
+docker exec -it $OLDCONTAINER ejabberdctl registered_users localhost
+```
+
+Methods to know the Erlang node name:
+```bash
+ls database/ | grep ejabberd@
+docker exec -it $OLDCONTAINER ejabberdctl status
+docker exec -it $OLDCONTAINER grep "started in the node" logs/ejabberd.log
+```
+
+#### Change Mnesia Node
+
+First of all let's store the Erlang node names and paths in variables.
+In this example they would be:
+```bash
+OLDCONTAINER=ejaold
+NEWCONTAINER=ejanew
+OLDNODE=ejabberd@95145ddee27c
+NEWNODE=ejabberd@localhost
+OLDFILE=/opt/ejabberd/database/old.backup
+NEWFILE=/opt/ejabberd/database/new.backup
+```
+
+1. Start your old container that can still read the Mnesia database correctly.
+If you have the Mnesia spool files,
+but don't have access to the old container anymore, go to
+[Create Temporary Container](#create-temporary-container)
+and later come back here.
+
+2. Generate a backup file and check it was created:
+```bash
+docker exec -it $OLDCONTAINER ejabberdctl backup $OLDFILE
+ls -l database/*.backup
+```
+
+3. Stop ejabberd:
+```bash
+docker stop $OLDCONTAINER
+```
+
+4. Create the new container. For example:
+```bash
+docker run \
+       --name $NEWCONTAINER \
+       -d \
+       -p 5222:5222 \
+       -v $(pwd)/database:/opt/ejabberd/database \
+       ghcr.io/processone/ejabberd:latest
+```
+
+5. Convert the backup file to new node name:
+```bash
+docker exec -it $NEWCONTAINER ejabberdctl mnesia_change_nodename $OLDNODE $NEWNODE $OLDFILE $NEWFILE
+```
+
+6. Install the backup file as a fallback:
+```bash
+docker exec -it $NEWCONTAINER ejabberdctl install_fallback $NEWFILE
+```
+
+7. Restart the container:
+```bash
+docker restart $NEWCONTAINER
+```
+
+8. Check that the information of the old database is available.
+In this example, it should show that the account `user1` is registered:
+```bash
+docker exec -it $NEWCONTAINER ejabberdctl registered_users localhost
+```
+
+9. When the new container is working perfectly with the converted Mnesia database,
+you may want to remove the unneeded files:
+the old container, the old Mnesia spool files, and the backup files.
+
+#### Create Temporary Container
+
+In case the old container that used the Mnesia database is not available anymore,
+a temporary container can be created just to read the Mnesia database
+and make a backup of it, as explained in the previous section.
+
+This method uses `--hostname` command line argument for docker,
+and `ERLANG_NODE_ARG` environment variable for ejabberd.
+Their values must be the hostname of your old container
+and the Erlang node name of your old ejabberd node.
+To know the Erlang node name please check
+[Setup Old Container](#setup-old-container).
+
+Command line example:
+```bash
+OLDHOST=${OLDNODE#*@}
+docker run \
+       -d \
+       --name $OLDCONTAINER \
+       --hostname $OLDHOST \
+       -p 5222:5222 \
+       -v $(pwd)/database:/opt/ejabberd/database \
+       -e ERLANG_NODE_ARG=$OLDNODE \
+       ghcr.io/processone/ejabberd:latest
+```
+
+Check the old database content is available:
+```bash
+docker exec -it $OLDCONTAINER ejabberdctl registered_users localhost
+```
+
+Now that you have ejabberd running with access to the Mnesia database,
+you can continue with step 2 of previous section
+[Change Mnesia Node](#change-mnesia-node).
+
+
+Build Container Image
+----------------
+
+The container image includes ejabberd as a standalone OTP release built using Elixir.
+
+### Build `ejabberd` [![ejabberd Container](https://img.shields.io/badge/ejabberd-grey?logo=opencontainersinitiative&logoColor=2094f3)](https://github.com/processone/ejabberd/pkgs/container/ejabberd)
+
+The ejabberd Erlang/OTP release is configured with:
 
 - `mix.exs`: Customize ejabberd release
 - `vars.config`: ejabberd compilation configuration options
 - `config/runtime.exs`: Customize ejabberd paths
 - `ejabberd.yml.template`: ejabberd default config file
 
-### Direct build
+#### Direct build
 
 Build ejabberd Community Server container image from ejabberd master git repository:
 
@@ -332,7 +567,7 @@ docker buildx build \
     .
 ```
 
-### Podman build
+#### Podman build
 
 To build the image using Podman, please notice:
 
@@ -357,38 +592,9 @@ podman stop eja1
 podman run --name eja1 -it -e EJABBERD_BYPASS_WARNINGS=true -p 5222:5222 localhost/ejabberd live
 ```
 
-### Package build for `arm64`
+### Build `ecs` [![ecs Container](https://img.shields.io/badge/ecs-grey?logo=docker&logoColor=2094f3)](https://hub.docker.com/r/ejabberd/ecs/)
 
-By default, `.github/container/Dockerfile` builds this container by directly compiling ejabberd,
+The ejabberd Erlang/OTP release is configured with:
-it is a fast and direct method.
-However, a problem with QEMU prevents building the container in QEMU using Erlang/OTP 25
-for the `arm64` architecture.
-
-Providing `--build-arg METHOD=package` is an alternate method to build the container
-used by the Github Actions workflow that provides `amd64` and `arm64` container images.
-It first builds an ejabberd binary package, and later installs it in the image.
-That method avoids using QEMU, so it can build `arm64` container images, but is extremely
-slow the first time it's used, and consequently not recommended for general use.
-
-In this case, to build the ejabberd container image for arm64 architecture:
-
-```bash
-docker buildx build \
-    --build-arg METHOD=package \
-    --platform linux/arm64 \
-    -t personal/ejabberd:$VERSION \
-    -f .github/container/Dockerfile \
-    .
-```
-
-Build `ecs` Container Image
----------------------------
-
-### Configuration
-
-Image is built by embedding an ejabberd Erlang/OTP standalone release in the image.
-
-The configuration of ejabberd Erlang/OTP release is customized with:
 
 - `rel/config.exs`: Customize ejabberd release
 - `rel/dev.exs`: ejabberd environment configuration for development release
@@ -399,7 +605,7 @@ The configuration of ejabberd Erlang/OTP release is customized with:
 Build ejabberd Community Server base image from ejabberd master on Github:
 
 ```bash
-docker build -t docker.io/ejabberd/ecs .
+docker build -t personal/ejabberd .
 ```
 
 Build ejabberd Community Server base image for a given ejabberd version:
@@ -408,7 +614,6 @@ Build ejabberd Community Server base image for a given ejabberd version:
 ./build.sh 18.03
 ```
 
-
 Composer Examples
 -----------------
 
@@ -468,26 +673,21 @@ stores the mnesia database in a local path,
 registers an account when it's created,
 and checks the number of registered accounts every time it's started.
 
-Download or copy the ejabberd configuration file:
+Prepare an ejabberd configuration file:
 ```bash
-wget https://raw.githubusercontent.com/processone/ejabberd/master/ejabberd.yml.example
+mkdir conf && cp ejabberd.yml.example conf/ejabberd.yml
-mv ejabberd.yml.example ejabberd.yml
-```
-
-Use a macro in `ejabberd.yml` to set the served vhost, with `localhost` as default value:
-```yaml
-define_macro:
-  XMPPHOST: localhost
-
-hosts:
-  - XMPPHOST
 ```
 
 Create the database directory and allow the container access to it:
-```bash
+
-mkdir database
+- Docker:
-sudo chown 9000:9000 database
+    ```bash
-```
+    mkdir database && sudo chown 9000:9000 database
+    ```
+- Podman:
+    ```bash
+    mkdir database && podman unshare chown 9000:9000 database
+    ```
 
 If using Docker, write this `docker-compose.yml` file
 and start it with `docker-compose up`:
@@ -501,8 +701,9 @@ services:
     image: ghcr.io/processone/ejabberd
     container_name: ejabberd
     environment:
-      - EJABBERD_MACRO_XMPPHOST=example.com
+      - EJABBERD_MACRO_HOST=example.com
-      - CTL_ON_CREATE=register admin example.com asd
+      - EJABBERD_MACRO_ADMIN=admin@example.com
+      - REGISTER_ADMIN_PASSWORD=somePassw0rd
       - CTL_ON_START=registered_users example.com ;
                      status
     ports:
@@ -511,7 +712,7 @@ services:
       - "5280:5280"
       - "5443:5443"
     volumes:
-      - ./ejabberd.yml:/opt/ejabberd/conf/ejabberd.yml:ro
+      - ./conf/ejabberd.yml:/opt/ejabberd/conf/ejabberd.yml:ro
       - ./database:/opt/ejabberd/database
 ```
 
@@ -532,8 +733,12 @@ spec:
   - name: ejabberd
     image: ghcr.io/processone/ejabberd
     env:
-    - name: CTL_ON_CREATE
+    - name: EJABBERD_MACRO_HOST
-      value: register admin example.com asd
+      value: example.com
+    - name: EJABBERD_MACRO_ADMIN
+      value: admin@example.com
+    - name: REGISTER_ADMIN_PASSWORD
+      value: somePassw0rd
     - name: CTL_ON_START
       value: registered_users example.com ;
              status
@@ -556,7 +761,7 @@ spec:
   volumes:
   - name: config
     hostPath:
-      path: ./ejabberd.yml
+      path: ./conf/ejabberd.yml
       type: File
   - name: db
     hostPath:
@@ -589,11 +794,17 @@ services:
 
   main:
     image: ghcr.io/processone/ejabberd
-    container_name: ejabberd
+    container_name: main
     environment:
       - ERLANG_NODE_ARG=ejabberd@main
       - ERLANG_COOKIE=dummycookie123
       - CTL_ON_CREATE=! register admin localhost asd
+    healthcheck:
+      test: netstat -nl | grep -q 5222
+      start_period: 5s
+      interval: 5s
+      timeout: 5s
+      retries: 120
 
   replica:
     image: ghcr.io/processone/ejabberd
@@ -692,92 +903,41 @@ spec:
 
 ```
 
-Your configuration file should use those macros to allow each ejabberd node
-use different listening port numbers:
 
-```diff
+Images Comparison
-diff --git a/ejabberd.yml.example b/ejabberd.yml.example
+-----------------
-index 39e423a64..6e875b48f 100644
---- a/ejabberd.yml.example
-+++ b/ejabberd.yml.example
-@@ -24,9 +24,19 @@ loglevel: info
- #  - /etc/letsencrypt/live/domain.tld/fullchain.pem
- #  - /etc/letsencrypt/live/domain.tld/privkey.pem
 
-+define_macro:
+Let's summarize the differences between both container images. Legend:
-+  PORT_C2S: 5222
+
-+  PORT_C2S_TLS: 5223
+- :sparkle: is the recommended alternative
-+  PORT_S2S: 5269
+- :orange_circle: added in the latest release (ejabberd 25.xx)
-+  PORT_HTTP_TLS: 5443
+- :high_brightness: added in the previous release (ejabberd 24.12)
-+  PORT_HTTP: 5280
+- :low_brightness: added in the pre-previous release (ejabberd 24.10)
-+  PORT_STUN: 5478
+
-+  PORT_MQTT: 1883
+|                       | [![ejabberd Container](https://img.shields.io/badge/ejabberd-grey?logo=opencontainersinitiative&logoColor=2094f3)](https://github.com/processone/ejabberd/pkgs/container/ejabberd) | [![ecs Container](https://img.shields.io/badge/ecs-grey?logo=docker&logoColor=2094f3)](https://hub.docker.com/r/ejabberd/ecs/) |
-+  PORT_PROXY65: 7777
+|:----------------------|:------------------|:-----------------------|
-+
+| Source code           | [ejabberd/.github/container](https://github.com/processone/ejabberd/tree/master/.github/container) | [docker-ejabberd/ecs](https://github.com/processone/docker-ejabberd/tree/master/ecs) |
- listen:
+| Generated by          | [container.yml](https://github.com/processone/ejabberd/blob/master/.github/workflows/container.yml) | [tests.yml](https://github.com/processone/docker-ejabberd/blob/master/.github/workflows/tests.yml) |
-   -
+| Built for             | stable releases <br /> `master` branch | stable releases <br /> [`master` branch zip](https://github.com/processone/docker-ejabberd/actions/workflows/tests.yml) |
--    port: 5222
+| Architectures         | `linux/amd64` <br /> `linux/arm64` | `linux/amd64` |
-+    port: PORT_C2S
+| Software              | Erlang/OTP 27.2-alpine <br /> Elixir 1.18.1 | Alpine 3.19 <br /> Erlang/OTP 26.2 <br /> Elixir 1.15.7 |
-     ip: "::"
+| Published in          | [ghcr.io/processone/ejabberd](https://github.com/processone/ejabberd/pkgs/container/ejabberd) | [docker.io/ejabberd/ecs](https://hub.docker.com/r/ejabberd/ecs/) <br /> [ghcr.io/processone/ecs](https://github.com/processone/docker-ejabberd/pkgs/container/ecs) |
-     module: ejabberd_c2s
+| :black_square_button: **Additional content** |
-     max_stanza_size: 262144
+| [ejabberd-contrib](https://docs.ejabberd.im/admin/guide/modules/#ejabberd-contrib) | included | not included |
-@@ -34,7 +44,7 @@ listen:
+| [ejabberdapi](#ejabberdapi) | included :orange_circle: | included |
-     access: c2s
+| :black_square_button: **Ports** |
-     starttls_required: true
+| [1880](#ports) for WebAdmin     | yes :orange_circle: | yes :orange_circle: |
-   -
+| [5210](#ports) for `ERL_DIST_PORT` | supported | supported :orange_circle: |
--    port: 5223
+| :black_square_button: **Paths** |
-+    port: PORT_C2S_TLS
+| `$HOME`               | `/opt/ejabberd/` | `/home/ejabberd/` |
-     ip: "::"
+| User data             | `$HOME` :sparkle: <br /> `/home/ejabberd/` :orange_circle: | `$HOME` <br /> `/opt/ejabberd/` :sparkle: :low_brightness: |
-     module: ejabberd_c2s
+| `ejabberdctl`         | `ejabberdctl` :sparkle: <br /> `bin/ejabberdctl` :orange_circle:  | `bin/ejabberdctl` <br /> `ejabberdctl` :sparkle: :low_brightness: |
-     max_stanza_size: 262144
+| [`captcha.sh`](#captcha)         | `$HOME/bin/captcha.sh` :orange_circle:  | `$HOME/bin/captcha.sh` :orange_circle: |
-@@ -42,13 +52,13 @@ listen:
+| `*.sql` files | `$HOME/sql/*.sql` :sparkle: :orange_circle: <br />  `$HOME/database/*.sql` :orange_circle: | `$HOME/database/*.sql` <br /> `$HOME/sql/*.sql` :sparkle: :orange_circle: |
-     access: c2s
+| Mnesia spool files | `$HOME/database/` :sparkle: <br /> `$HOME/database/NODENAME/` :orange_circle:  | `$HOME/database/NODENAME/` <br /> `$HOME/database/` :sparkle: :orange_circle: |
-     tls: true
+| :black_square_button: **Variables** |
-   -
+| [`EJABBERD_MACRO_*`](#macros-in-environment)      | supported :high_brightness: | supported :high_brightness: |
--    port: 5269
+| Macros used in `ejabberd.yml` | yes :orange_circle: | yes :orange_circle: |
-+    port: PORT_S2S
+| [`EJABBERD_MACRO_ADMIN`](#register-admin-account) | Grant admin rights :orange_circle: <br /> (default `admin@localhost`) <br /> | Hardcoded `admin@localhost` |
-     ip: "::"
+| [`REGISTER_ADMIN_PASSWORD`](#register-admin-account) | Register admin account :orange_circle: | unsupported |
-     module: ejabberd_s2s_in
+| `CTL_OVER_HTTP`       | enabled :orange_circle: | unsupported |
-     max_stanza_size: 524288
-     shaper: s2s_shaper
-   -
--    port: 5443
-+    port: PORT_HTTP_TLS
-     ip: "::"
-     module: ejabberd_http
-     tls: true
-@@ -60,14 +70,14 @@ listen:
-       /upload: mod_http_upload
-       /ws: ejabberd_http_ws
-   -
--    port: 5280
-+    port: PORT_HTTP
-     ip: "::"
-     module: ejabberd_http
-     request_handlers:
-       /admin: ejabberd_web_admin
-       /.well-known/acme-challenge: ejabberd_acme
-   -
--    port: 5478
-+    port: PORT_STUN
-     ip: "::"
-     transport: udp
-     module: ejabberd_stun
-@@ -77,7 +87,7 @@ listen:
-     ## The server's public IPv6 address:
-     # turn_ipv6_address: "2001:db8::3"
-   -
--    port: 1883
-+    port: PORT_MQTT
-     ip: "::"
-     module: mod_mqtt
-     backlog: 1000
-@@ -207,6 +217,7 @@ modules:
-   mod_proxy65:
-     access: local
-     max_connections: 5
-+    port: PORT_PROXY65
-   mod_pubsub:
-     access_createnode: pubsub_createnode
-     plugins:
-```