From 15045cf793d380cdb735cdf292bc4d88baa22695 Mon Sep 17 00:00:00 2001 From: Badlop Date: Mon, 5 Apr 2021 21:29:24 +0200 Subject: [PATCH] Major reordering of sections, Markdown, badges, rephrasal ... --- ecs/README.md | 209 ++++++++++++++++++++++++++------------------------ 1 file changed, 109 insertions(+), 100 deletions(-) diff --git a/ecs/README.md b/ecs/README.md index aaa8561..2851fbe 100644 --- a/ecs/README.md +++ b/ecs/README.md @@ -1,25 +1,29 @@ -[![Docker Stars](https://img.shields.io/docker/stars/ejabberd/ecs.svg)](https://hub.docker.com/r/ejabberd/ecs/) -[![Docker Pulls](https://img.shields.io/docker/pulls/ejabberd/ecs.svg)](https://hub.docker.com/r/ejabberd/ecs/) -[![](https://images.microbadger.com/badges/version/ejabberd/ecs.svg)](https://microbadger.com/images/ejabberd/ecs) -[![](https://images.microbadger.com/badges/image/ejabberd/ecs.svg)](https://microbadger.com/images/ejabberd/ecs) -[![GitHub stars](https://img.shields.io/github/stars/processone/docker-ejabberd.svg?style=social)](https://github.com/processone/docker-ejabberd) +[![Docker Image Version (latest by date)](https://img.shields.io/docker/v/ejabberd/ecs)](https://hub.docker.com/r/ejabberd/ecs/) +[![Docker Image Size (latest by date)](https://img.shields.io/docker/image-size/ejabberd/ecs)](https://hub.docker.com/r/ejabberd/ecs/) +[![Docker Stars](https://img.shields.io/docker/stars/ejabberd/ecs)](https://hub.docker.com/r/ejabberd/ecs/) +[![Docker Pulls](https://img.shields.io/docker/pulls/ejabberd/ecs)](https://hub.docker.com/r/ejabberd/ecs/) +[![GitHub stars](https://img.shields.io/github/stars/processone/docker-ejabberd?style=social)](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 +`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 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 +- `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 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.