mirror of
https://github.com/processone/ejabberd
synced 2025-10-03 17:59:31 +02:00
CONTAINER.md: Include documentation for ecs container image
This commit is contained in:
Badlop
parent
cfa6575b4f
commit
60324d4b7a
1 changed files with 367 additions and 207 deletions
572
CONTAINER.md
572
CONTAINER.md
|
|
@ -1,10 +1,10 @@
|
|||
|
||||
[](https://github.com/processone/ejabberd/tags)
|
||||
[](https://github.com/processone/ejabberd/pkgs/container/ejabberd)
|
||||
[](https://github.com/processone/ejabberd/pkgs/container/ejabberd)
|
||||
[](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
|
||||
[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.
|
||||
This page documents those container images ([images comparison](#images-comparison)):
|
||||
|
||||
Alternatively, there is also the `ecs` container image available in
|
||||
[docker.io/ejabberd/ecs](https://hub.docker.com/r/ejabberd/ecs/),
|
||||
built using the
|
||||
[docker-ejabberd/ecs](https://github.com/processone/docker-ejabberd/tree/master/ecs)
|
||||
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).
|
||||
- [](https://github.com/processone/ejabberd/pkgs/container/ejabberd)
|
||||
published in [ghcr.io/processone/ejabberd](https://github.com/processone/ejabberd/pkgs/container/ejabberd),
|
||||
built using [ejabberd](https://github.com/processone/ejabberd/tree/master/.github/container) repository,
|
||||
both for stable ejabberd releases and the `master` branch, in x64 and arm64 architectures.
|
||||
|
||||
If you are using a Windows operating system, check the tutorials mentioned in
|
||||
[ejabberd Docs > Docker Image](https://docs.ejabberd.im/admin/install/container/#ejabberd-container-image).
|
||||
- [](https://hub.docker.com/r/ejabberd/ecs/)
|
||||
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
|
||||
chown ejabberd database
|
||||
mkdir conf && cp ejabberd.yml.example conf/ejabberd.yml
|
||||
|
||||
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
|
||||
|
||||
#### [](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_HOST=example.org` --> `admin@example.org`
|
||||
- None of those variables are set --> `admin@localhost`
|
||||
- `EJABBERD_MACRO_ADMIN=juliet@example.org` -> `juliet@example.org`
|
||||
- `EJABBERD_MACRO_HOST=example.org` -> `admin@example.org`
|
||||
- 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
|
||||
[ejabberd Docs: Administration Account](https://docs.ejabberd.im/admin/install/next-steps/#administration-account):
|
||||
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).
|
||||
|
||||
---
|
||||
|
||||
#### [](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 files
|
||||
### Check ejabberd log
|
||||
|
||||
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,
|
||||
[this comment](https://github.com/processone/docker-ejabberd/issues/81#issuecomment-1036115146)
|
||||
explains how to install an additional module using docker-compose.
|
||||
If using Docker, try:
|
||||
```bash
|
||||
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.
|
||||
That OTP release is configured with:
|
||||
Example using environment variables (see the full
|
||||
[`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` [](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` [](https://hub.docker.com/r/ejabberd/ecs/)
|
||||
|
||||
By default, `.github/container/Dockerfile` builds this container by directly compiling ejabberd,
|
||||
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:
|
||||
The ejabberd Erlang/OTP release is configured 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
|
||||
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
|
||||
mkdir conf && cp ejabberd.yml.example conf/ejabberd.yml
|
||||
```
|
||||
|
||||
Create the database directory and allow the container access to it:
|
||||
```bash
|
||||
mkdir database
|
||||
sudo chown 9000:9000 database
|
||||
```
|
||||
|
||||
- Docker:
|
||||
```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
|
||||
- CTL_ON_CREATE=register admin example.com asd
|
||||
- EJABBERD_MACRO_HOST=example.com
|
||||
- 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
|
||||
value: register admin example.com asd
|
||||
- name: EJABBERD_MACRO_HOST
|
||||
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
|
||||
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
|
||||
Images Comparison
|
||||
-----------------
|
||||
|
||||
+define_macro:
|
||||
+ PORT_C2S: 5222
|
||||
+ PORT_C2S_TLS: 5223
|
||||
+ PORT_S2S: 5269
|
||||
+ PORT_HTTP_TLS: 5443
|
||||
+ PORT_HTTP: 5280
|
||||
+ PORT_STUN: 5478
|
||||
+ PORT_MQTT: 1883
|
||||
+ PORT_PROXY65: 7777
|
||||
+
|
||||
listen:
|
||||
-
|
||||
- port: 5222
|
||||
+ port: PORT_C2S
|
||||
ip: "::"
|
||||
module: ejabberd_c2s
|
||||
max_stanza_size: 262144
|
||||
@@ -34,7 +44,7 @@ listen:
|
||||
access: c2s
|
||||
starttls_required: true
|
||||
-
|
||||
- port: 5223
|
||||
+ port: PORT_C2S_TLS
|
||||
ip: "::"
|
||||
module: ejabberd_c2s
|
||||
max_stanza_size: 262144
|
||||
@@ -42,13 +52,13 @@ listen:
|
||||
access: c2s
|
||||
tls: true
|
||||
-
|
||||
- port: 5269
|
||||
+ port: PORT_S2S
|
||||
ip: "::"
|
||||
module: ejabberd_s2s_in
|
||||
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:
|
||||
```
|
||||
Let's summarize the differences between both container images. Legend:
|
||||
|
||||
- :sparkle: is the recommended alternative
|
||||
- :orange_circle: added in the latest release (ejabberd 25.xx)
|
||||
- :high_brightness: added in the previous release (ejabberd 24.12)
|
||||
- :low_brightness: added in the pre-previous release (ejabberd 24.10)
|
||||
|
||||
| | [](https://github.com/processone/ejabberd/pkgs/container/ejabberd) | [](https://hub.docker.com/r/ejabberd/ecs/) |
|
||||
|:----------------------|:------------------|:-----------------------|
|
||||
| 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) |
|
||||
| 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) |
|
||||
| Architectures | `linux/amd64` <br /> `linux/arm64` | `linux/amd64` |
|
||||
| Software | Erlang/OTP 27.2-alpine <br /> Elixir 1.18.1 | Alpine 3.19 <br /> Erlang/OTP 26.2 <br /> Elixir 1.15.7 |
|
||||
| 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) |
|
||||
| :black_square_button: **Additional content** |
|
||||
| [ejabberd-contrib](https://docs.ejabberd.im/admin/guide/modules/#ejabberd-contrib) | included | not included |
|
||||
| [ejabberdapi](#ejabberdapi) | included :orange_circle: | included |
|
||||
| :black_square_button: **Ports** |
|
||||
| [1880](#ports) for WebAdmin | yes :orange_circle: | yes :orange_circle: |
|
||||
| [5210](#ports) for `ERL_DIST_PORT` | supported | supported :orange_circle: |
|
||||
| :black_square_button: **Paths** |
|
||||
| `$HOME` | `/opt/ejabberd/` | `/home/ejabberd/` |
|
||||
| User data | `$HOME` :sparkle: <br /> `/home/ejabberd/` :orange_circle: | `$HOME` <br /> `/opt/ejabberd/` :sparkle: :low_brightness: |
|
||||
| `ejabberdctl` | `ejabberdctl` :sparkle: <br /> `bin/ejabberdctl` :orange_circle: | `bin/ejabberdctl` <br /> `ejabberdctl` :sparkle: :low_brightness: |
|
||||
| [`captcha.sh`](#captcha) | `$HOME/bin/captcha.sh` :orange_circle: | `$HOME/bin/captcha.sh` :orange_circle: |
|
||||
| `*.sql` files | `$HOME/sql/*.sql` :sparkle: :orange_circle: <br /> `$HOME/database/*.sql` :orange_circle: | `$HOME/database/*.sql` <br /> `$HOME/sql/*.sql` :sparkle: :orange_circle: |
|
||||
| Mnesia spool files | `$HOME/database/` :sparkle: <br /> `$HOME/database/NODENAME/` :orange_circle: | `$HOME/database/NODENAME/` <br /> `$HOME/database/` :sparkle: :orange_circle: |
|
||||
| :black_square_button: **Variables** |
|
||||
| [`EJABBERD_MACRO_*`](#macros-in-environment) | supported :high_brightness: | supported :high_brightness: |
|
||||
| Macros used in `ejabberd.yml` | yes :orange_circle: | yes :orange_circle: |
|
||||
| [`EJABBERD_MACRO_ADMIN`](#register-admin-account) | Grant admin rights :orange_circle: <br /> (default `admin@localhost`) <br /> | Hardcoded `admin@localhost` |
|
||||
| [`REGISTER_ADMIN_PASSWORD`](#register-admin-account) | Register admin account :orange_circle: | unsupported |
|
||||
| `CTL_OVER_HTTP` | enabled :orange_circle: | unsupported |
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue