@ -1,25 +1,29 @@
[](https://hub.docker.com/r/ejabberd/ecs/)
[](https://hub.docker.com/r/ejabberd/ecs/)
[](https://hub.docker.com/r/ejabberd/ecs/)
[](https://hub.docker.com/r/ejabberd/ecs/)
[](https://microbadger.com/images/ejabberd/ecs )
[](https://hub.docker.com/r/ejabberd/ecs/ )
[](https://microbadger.com/images/ejabberd/ecs )
[](https://hub.docker.com/r/ejabberd/ecs/ )
[](https://github.com/processone/docker-ejabberd)
[](https://github.com/processone/docker-ejabberd)
# # ejabberd Community Server - Base # ejabberd Community Server
This ejabberd Docker image allows you to run a single node ejabberd instance in a Docker container.
ejabberd is an open-source XMPP server, robust, scalable and modular,
built using Erlang/OTP, and also includes MQTT Broker and SIP Service.
## Running ejabberd This Docker image allows you to run a single node ejabberd instance in a Docker container.
### Default configuration for domain localhost
# Start ejabberd
You can run ejabberd in a new container with the following command:
## With default configuration
You can start ejabberd in a new container with the following command:
```bash
```bash
docker run --name ejabberd -d -p 5222:5222 ejabberd/ecs
docker run --name ejabberd -d -p 5222:5222 ejabberd/ecs
```
```
This command will run Docker image as a daemon, using ejabberd default configuration file and XMPP domain "localhost".
This command will run Docker image as a daemon,
using ejabberd default configuration file and XMPP domain "localhost".
To stop the running container, you can run:
To stop the running container, you can run:
@ -27,102 +31,64 @@ To stop the running container, you can run:
docker stop ejabberd
docker stop ejabberd
```
```
If needed you can restart the stopped ejabberd container with:
If needed, you can restart the stopped ejabberd container with:
```bash
```bash
docker restart ejabberd
docker restart ejabberd
```
```
### Registering an admin account
## Start with Erlang console attached
The default ejabberd configuration has already granted admin privilege
If you would like to start ejabberd with an Erlang console attached you can use the `live` command:
to an account that would be called `admin@localhost` ,
so you just need to register such an account
to start using it for administrative purposes.
You can register this account using the `ejabberdctl` script, for example:
```bash
```bash
docker exec -it ejabberd bin/ejabberdctl register admin localhost passw0rd
docker run -it -p 5222:5222 ejabberd/ecs live
```
### Using ejabberdapi
When the container is running (and thus ejabberd), you can exec commands inside the container.
To execute those commands you can use `ejabberdctl` or any other of the available interfaces, see
https://docs.ejabberd.im/developer/ejabberd-api/#understanding-ejabberd-commands
Additionally, this Docker 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:
This command will use default configuration file and XMPP domain "localhost".
```bash
docker exec -it ejabberd bin/ejabberdapi register --endpoint=http://127.0.0.1:5282/ --jid=admin@localhost --password=passw0rd
```
### Running ejabberd with Erlang console attached
## Start with your configuration and database
If you would like to run it with Erlang console attached you can use the `live` command:
The following command will pass config file using Docker volume feature
and share local directory to store database:
```bash
```bash
docker run -it -p 5222:5222 ejabberd/ecs live
mkdir database
docker run -d --name ejabberd -v $(pwd)/ejabberd.yml:/home/ejabberd/conf/ejabberd.yml -v $(pwd)/database:/home/ejabberd/database -p 5222:5222 ejabberd/ecs
```
```
This command will use default configuration file and XMPP domain "localhost". # Next steps
### Running ejabberd with your config file and database host directory
## Register the administrator account
The following command will pass config file using Docker volume feature and share local directory to store database:
The default ejabberd configuration has already granted admin privilege
to an account that would be called `admin@localhost` ,
so you just need to register such an account
to start using it for administrative purposes.
You can register this account using the `ejabberdctl` script, for example:
```bash
```bash
mkdir database
docker exec -it ejabberd bin/ejabberdctl register admin localhost passw0rd
docker run -d --name ejabberd -v $(pwd)/ejabberd.yml:/home/ejabberd/conf/ejabberd.yml -v $(pwd)/database:/home/ejabberd/database -p 5222:5222 ejabberd/ecs
```
```
### Inspecting the container state
## Check ejabberd log files
The container is packaging Alpine Linux. You can check the state with the command:
You can execute a Docker command to check the content of the log files from
inside to container, even if you do not put it on a shared persistent drive:
```bash
```bash
docker exec -it ejabberd sh
docker exec -it ejabberd tail -f logs/ejabberd.log
```
```
### Checking ejabberd log files
## Inspect the container files
You can execute a Docker command to check the content of the log files from inside to container, even if you do not put it on a shared persistent drive :The container uses Alpine Linux. You can start a shell there with :
```bash
```bash
docker exec -it ejabberd tail -f logs/ejabberd.log
docker exec -it ejabberd sh
```
```
### Open ejabberd debug console
## Open ejabberd debug console
You can open a live debug Erlang console attached to a running container:
You can open a live debug Erlang console attached to a running container:
@ -130,7 +96,7 @@ You can open a live debug Erlang console attached to a running container:
docker exec -it ejabberd bin/ejabberdctl debug
docker exec -it ejabberd bin/ejabberdctl debug
```
```
### CAPTCHA
## CAPTCHA
ejabberd includes two example CAPTCHA scripts.
ejabberd includes two example CAPTCHA scripts.
If you want to use any of them, first install some additional required libraries:
If you want to use any of them, first install some additional required libraries:
@ -155,46 +121,93 @@ Finally, reload the configuration file or restart the container:
docker exec ejabberd bin/ejabberdctl reload_config
docker exec ejabberd bin/ejabberdctl reload_config
```
```
## Docker image advanced configuration
## Use ejabberdapi
### Ports
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 )
ejabberd base Docker image exposes the following port:
Additionally, this Docker image includes the `ejabberdapi` executable.
Please check the [ejabberd-api homepage ](https://github.com/processone/ejabberd-api )
for configuration and usage details.
- 5222: This is the default XMPP port for clients.
For example, if you configure ejabberd like this:
- 5280: This is the port for admin interface, API, Websockets and XMPP BOSH.
```yaml
- 5269: Optional. This is the port for XMPP federation. Only needed if you want to communicate with users on other servers.
listen:
-
port: 5282
module: ejabberd_http
request_handlers:
"/api": mod_http_api
### Volumes
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 bin/ejabberdapi register --endpoint=http://127.0.0.1:5282/ --jid=admin@localhost --password=passw0rd
```
# Advanced Docker configuration
## Ports
This Docker image exposes the ports:
- `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.
- `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
## Volumes
ejabberd produces two types of data: log files and database (Mnesia).
ejabberd produces two types of data: log files and database (Mnesia).
This is the kind of data you probably want to store on a persistent or local drive (at least the database).
This is the kind of data you probably want to store on a persistent or local drive (at least the database).
Here are the volume you may want to map:
Here are the volume you may want to map:
- /home/ejabberd/logs/: Directory containing log files
- `/home/ejabberd/conf/` : Directory containing configuration and certificates
- /home/ejabberd/database/: Directory containing Mnesia database. You should back up or export the content of the directory to persistent storage (host storage, local storage, any storage plugin)
- `/home/ejabberd/database/` : Directory containing Mnesia database.
- /home/ejabberd/conf/: Directory containing configuration and certificates
You should back up or export the content of the directory to persistent storage
- /home/ejabberd/upload/: Directory containing uploaded files. This should also be backed up.
(host storage, local storage, any storage plugin)
- `/home/ejabberd/logs/` : Directory containing log files
- `/home/ejabberd/upload/` : Directory containing uploaded files. This should also be backed up.
All these files are owned by ejabberd user inside the container. Corresponding
All these files are owned by ejabberd user inside the container. Corresponding
UID:GID is 9000:9000. If you prefer bind mounts instead of docker volumes, then
` ` is ` ` . If you prefer bind mounts instead of docker volumes, then
you need to map this to valid UID:GID on your host to get read/write access on
you need to map this to valid ` ` on your host to get read/write access on
mounted directories.
mounted directories.
## Generating ejabberd release
# Generating ejabberd release
### Configuration
## Configuration
Image is built by embedding an ejabberd Erlang/OTP standalone release in the image.
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 configuration of ejabberd Erlang/OTP release is customized with:
- rel/config.exs: Customize ejabberd release
- ` ` : Customize ejabberd release
- rel/dev.exs: ejabberd environment configuration for development release
- ` ` : ejabberd environment configuration for development release
- rel/prod.exs: ejabberd environment configuration for production Docker release
- ` ` : ejabberd environment configuration for production Docker release
- vars.config: ejabberd compilation configuration options
- ` ` : ejabberd compilation configuration options
- conf/ejabberd.yml: ejabberd default config file
- ` ` : ejabberd default config file
Build ejabberd Community Server base image from ejabberd master on Github:
Build ejabberd Community Server base image from ejabberd master on Github:
@ -207,7 +220,3 @@ Build ejabberd Community Server base image for a given ejabberd version:
```bash
```bash
./build.sh 18.03
./build.sh 18.03
```
```
### TODO
- Rebuild last version of bin/ejabberdapi tool when creating container.
Badlop
3 years ago