@ -1,25 +1,29 @@
[](https://hub.docker.com/r/ejabberd/ecs/)
[](https://hub.docker.com/r/ejabberd/ecs/)
[](https://microbadger.com/images/ejabberd/ecs )
[](https://microbadger.com/images/ejabberd/ecs )
[](https://github.com/processone/docker-ejabberd)
[](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://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
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:
@ -27,102 +31,64 @@ To stop the running container, you can run:
docker stop ejabberd
```
If needed you can restart the stopped ejabberd container with:
If needed, you can restart the stopped ejabberd container with:
```bash
docker restart ejabberd
```
### Registering an admin account
## Start with Erlang console attached
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:
If you would like to start ejabberd with an Erlang console attached you can use the `live` command:
```bash
docker exec -it ejabberd bin/ejabberdctl register admin localhost passw0rd
```
### 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"
docker run -it -p 5222:5222 ejabberd/ecs live
```
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
```
This command will use default configuration file and XMPP domain "localhost".
### 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
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
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
docker exec -it ejabberd bin/ejabberdctl register admin localhost passw0rd
```
### 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
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
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:
@ -130,7 +96,7 @@ You can open a live debug Erlang console attached to a running container:
docker exec -it ejabberd bin/ejabberdctl debug
```
### CAPTCHA
## CAPTCHA
ejabberd includes two example CAPTCHA scripts.
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 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.
- 5280: This is the port for admin interface, API, Websockets and XMPP BOSH.
- 5269: Optional. This is the port for XMPP federation. Only needed if you want to communicate with users on other servers.
For example, if you configure ejabberd like this:
```yaml
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).
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:
- /home/ejabberd/logs/: Directory containing log files
- /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/conf/: Directory containing configuration and certificates
- /home/ejabberd/upload/: Directory containing uploaded files. This should also be backed up.
- `/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/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
UID:GID is 9000:9000. 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
` ` is ` ` . If you prefer bind mounts instead of docker volumes, then
you need to map this to valid ` ` on your host to get read/write access on
mounted directories.
## Generating ejabberd release
# Generating ejabberd release
### Configuration
## 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
- rel/prod.exs: ejabberd environment configuration for production Docker release
- vars.config: ejabberd compilation configuration options
- conf/ejabberd.yml: ejabberd default config file
- ` ` : Customize ejabberd release
- ` ` : ejabberd environment configuration for development release
- ` ` : ejabberd environment configuration for production Docker release
- ` ` : ejabberd compilation configuration options
- ` ` : ejabberd default config file
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
./build.sh 18.03
```
### TODO
- Rebuild last version of bin/ejabberdapi tool when creating container.
Badlop
3 years ago