diff --git a/COMPILE.md b/COMPILE.md new file mode 100644 index 000000000..5bcfaa581 --- /dev/null +++ b/COMPILE.md @@ -0,0 +1,126 @@ +Compile and Install ejabberd +============================ + +This document explains how to compile and install ejabberd +from source code. + +For a more detailed explanation, please check the +ejabberd Docs: [Source Code Installation][docs-source]. + +[docs-source]: https://docs.ejabberd.im/admin/installation/#source-code + + +Requirements +------------ + +To compile ejabberd you need: + + - GNU Make + - GCC + - Libexpat ≥ 1.95 + - Libyaml ≥ 0.1.4 + - Erlang/OTP ≥ 19.3 + - OpenSSL ≥ 1.0.0 + +Other optional libraries are: + + - Zlib ≥ 1.2.3, for Stream Compression support (XEP-0138) + - PAM library, for Pluggable Authentication Modules (PAM) + - ImageMagick's Convert program and Ghostscript fonts, for CAPTCHA + challenges + - Elixir ≥ 1.10.3, to support Elixir, and alternative to rebar/rebar3 + +If your system splits packages in libraries and development headers, +install the development packages too. + + +Download Source Code +-------------------- + +There are several ways to obtain the ejabberd source code: + +- Source code archive from [ProcessOne Downloads][p1dl] +- Source code package from [ejabberd GitHub Releases][ghr] +- Latest development code from [ejabberd Git repository][gitrepo] + +[p1dl]: https://www.process-one.net/en/ejabberd/downloads/ +[ghr]: https://github.com/processone/ejabberd/releases +[gitrepo]: https://github.com/processone/ejabberd + + +Compile +------- + +The general instructions to compile ejabberd are: + + ./configure + make + +If the source code doesn't contain a `configure` script, +first of all install `autoconf` and run this to generate it: + + ./autogen.sh + +To configure the compilation, features, install paths... + + ./configure --help + + +Install in the System +--------------------- + +To install ejabberd in the system, run this with system administrator rights (root user): + + sudo make install + +This will: + +- Install the configuration files in `/etc/ejabberd/` +- Install ejabberd binary, header and runtime files in `/lib/ejabberd/` +- Install the administration script: `/sbin/ejabberdctl` +- Install ejabberd documentation in `/share/doc/ejabberd/` +- Create a spool directory: `/var/lib/ejabberd/` +- Create a directory for log files: `/var/log/ejabberd/` + + +Build an OTP Release +-------------------- + +Instead of installing ejabberd in the system, you can build an OTP release +that includes all necessary to run ejabberd in a subdirectory: + + ./configure --with-rebar=rebar3 + make rel + +Or, if you have Elixir available and plan to develop Elixir code: + + ./configure --with-rebar=mix + make dev + +Check the full list of targets: + + make help + + +Start ejabberd +-------------- + +You can use the `ejabberdctl` command line administration script to +start and stop ejabberd. Some examples, depending on your installation method: + +- When installed in the system: + ``` + ejabberdctl start + /sbin/ejabberdctl start + ``` + +- When built an OTP production release: + ``` + _build/prod/rel/ejabberd/bin/ejabberdctl start + _build/prod/rel/ejabberd/bin/ejabberdctl live + ``` + +- Start interactively without installing or building OTP release: + ``` + make relive + ``` diff --git a/CONTAINER.md b/CONTAINER.md new file mode 100644 index 000000000..e62553d71 --- /dev/null +++ b/CONTAINER.md @@ -0,0 +1,288 @@ + +[![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) +[![GitHub Container](https://img.shields.io/github/v/tag/processone/ejabberd?label=container&sort=semver)](https://github.com/badlop/ejabberd/pkgs/container/ejabberd) +[![Docker Image Version (latest semver)](https://img.shields.io/docker/v/ejabberd/ecs?label=docker)](https://hub.docker.com/r/ejabberd/ecs/) + + +ejabberd Container +================== + +[ejabberd][home] is an open-source, +robust, scalable and extensible realtime platform built using [Erlang/OTP][erlang], +that includes [XMPP][xmpp] Server, [MQTT][mqtt] Broker and [SIP][sip] Service. + +[home]: https://ejabberd.im/ +[erlang]: https://www.erlang.org/ +[xmpp]: https://xmpp.org/ +[mqtt]: https://mqtt.org/ +[sip]: https://en.wikipedia.org/wiki/Session_Initiation_Protocol + +This document explains how to use the +[ejabberd container images](https://github.com/processone/ejabberd/pkgs/container/ejabberd) +available in the GitHub Container Registry, +built using the files in `.github/container/`. + +Alternatively, there are also +[ejabberd-ecs Docker images](https://hub.docker.com/r/ejabberd/ecs/) +available in Docker Hub, +built using the +[docker-ejabberd/ecs](https://github.com/processone/docker-ejabberd/tree/master/ecs) +repository. + +If you are using a Windows operating system, check the tutorials mentioned in +[ejabberd Docs > Docker Image](https://docs.ejabberd.im/admin/installation/#docker-image). + + +Start ejabberd +-------------- + +### With default configuration + +Start ejabberd in a new container: + +```bash +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 +``` + + +### Start with Erlang console attached + +Start ejabberd with an Erlang console attached using the `live` command: + +```bash +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 + +Pass a configuration file as a volume +and share the local directory to store database: + +```bash +mkdir database +chown ejabberd database + +cp ejabberd.yml.example ejabberd.yml + +docker run --name ejabberd -it \ + -v $(pwd)/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`, +and the volumes you mount must grant proper rights to that account. + + +Next steps +---------- + +### Register the administrator account + +The default ejabberd configuration does not grant admin privileges +to any account, +you may want to register a new account in ejabberd +and grant it admin rights. + +Register an account using the `ejabberdctl` script: + +```bash +docker exec -it ejabberd ejabberdctl register admin localhost passw0rd +``` + +Then edit conf/ejabberd.yml and add the ACL as explained in +[ejabberd Docs: Administration Account](https://docs.ejabberd.im/admin/installation/#administration-account) + + +### 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: + +```bash +docker exec -it ejabberd tail -f logs/ejabberd.log +``` + + +### Inspect the container files + +The container uses Alpine Linux. Start a shell inside the container: + +```bash +docker exec -it ejabberd sh +``` + + +### Open ejabberd debug console + +Open an interactive debug Erlang console attached to a running ejabberd in a running container: + +```bash +docker exec -it ejabberd ejabberdctl debug +``` + + +### CAPTCHA + +ejabberd includes two example CAPTCHA scripts. +If you want to use any of them, first install some additional required libraries: + +```bash +docker exec --user root ejabberd apk add imagemagick ghostscript-fonts bash +``` + +Now update your ejabberd configuration file, for example: +```bash +docker exec -it ejabberd vi conf/ejabberd.yml +``` + +and add the required options: +``` +captcha_cmd: /opt/ejabberd-22.04/lib/ejabberd-22.04/priv/bin/captcha.sh +captcha_url: https://localhost:5443/captcha +``` + +Finally, reload the configuration file or restart the container: +```bash +docker exec ejabberd ejabberdctl reload_config +``` + + +Advanced Container Configuration +-------------------------------- + +### Ports + +This container 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 spool files (Mnesia). +This is the kind of data you probably want to store on a persistent or local drive (at least the database). + +The volumes you may want to map: + +- `/opt/ejabberd/conf/`: Directory containing configuration and certificates +- `/opt/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) +- `/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. + +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. + + +### Commands on start + +The ejabberdctl script reads the `CTL_ON_CREATE` environment variable +the first time the docker container is started, +and reads `CTL_ON_START` every time the container is started. +Those variables can contain one ejabberdctl command, +or several commands separated with the blankspace and `;` characters. + +Example usage (see full example [docker-compose.yml](https://github.com/processone/docker-ejabberd/issues/64#issuecomment-887741332)): +```yaml + environment: + - CTL_ON_CREATE=register admin localhost asd + - CTL_ON_START=stats registeredusers ; + check_password admin localhost asd ; + status +``` + + +### Clustering + +When setting several containers to form a +[cluster of ejabberd nodes](https://docs.ejabberd.im/admin/guide/clustering/), +each one must have a different +[Erlang Node Name](https://docs.ejabberd.im/admin/guide/security/#erlang-node-name) +and the same +[Erlang Cookie](https://docs.ejabberd.im/admin/guide/security/#erlang-cookie). + +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 using environment variables (see full example [docker-compose.yml](https://github.com/processone/docker-ejabberd/issues/64#issuecomment-887741332)): +```yaml + environment: + - ERLANG_NODE_ARG=ejabberd@node7 + - ERLANG_COOKIE=dummycookie123 +``` + + +Generating a Container Image +---------------------------- + +This container image includes ejabberd as a standalone OTP release built using Elixir. + +That 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 + +Build ejabberd Community Server base image from ejabberd master on GitHub: + +```bash +VERSION = master +docker build \ + --build-arg VERSION=$(VERSION) \ + -t personal/ejabberd:$(VERSION) \ + .github/container +``` + +Build ejabberd Community Server base image for a given ejabberd version, +both for amd64 and arm64 architectures: + +```bash +VERSION = 21.12 +docker buildx build \ + --platform=linux/amd64,linux/arm64 + --build-arg VERSION=$(VERSION) \ + -t personal/ejabberd:$(VERSION) \ + .github/container +``` + +It's also possible to use podman instead of docker, just notice: +- `EXPOSE 4369-4399` port range is not supported, remove that in Dockerfile +- It mentions that `healthcheck` is not supported by the Open Container Initiative image format +- If you want to start with command `live`, add environment variable `EJABBERD_BYPASS_WARNINGS=true` +```bash +VERSION = master +podman build \ + --build-arg VERSION=$(VERSION) \ + -t ja:$(version) \ + .github/container +``` diff --git a/README.md b/README.md index f62486150..ade46445b 100644 --- a/README.md +++ b/README.md @@ -6,190 +6,105 @@ ejabberd Community Edition [![Translation status](https://hosted.weblate.org/widgets/ejabberd/-/ejabberd-po/svg-badge.svg "Translation status in Weblate")](https://hosted.weblate.org/projects/ejabberd/ejabberd-po/) [![Hex version](https://img.shields.io/hexpm/v/ejabberd.svg "Hex version")](https://hex.pm/packages/ejabberd) -ejabberd is a distributed, fault-tolerant technology that allows the creation -of large-scale instant messaging applications. The server can reliably support -thousands of simultaneous users on a single node and has been designed to -provide exceptional standards of fault tolerance. As an open source -technology, based on industry-standards, ejabberd can be used to build bespoke -solutions very cost effectively. + +[ejabberd][im] is an open-source, +robust, scalable and extensible realtime platform built using [Erlang/OTP][erlang], +that includes [XMPP][xmpp] Server, [MQTT][mqtt] Broker and [SIP][sip] Service. + +Check the features in [ejabberd.im][im], [ejabberd Docs][features], +[ejabberd at ProcessOne][p1home], and a list of [supported protocols and XEPs][xeps]. -Key Features +Installation ------------ -- **Cross-platform** - ejabberd runs under Microsoft Windows and Unix-derived systems such as - Linux, FreeBSD and NetBSD. +There are several ways to install ejabberd: -- **Distributed** - You can run ejabberd on a cluster of machines and all of them will serve the - same XMPP domain(s). When you need more capacity you can simply add a new - cheap node to your cluster. Accordingly, you do not need to buy an expensive - high-end machine to support tens of thousands concurrent users. - -- **Fault-tolerant** - You can deploy an ejabberd cluster so that all the information required for - a properly working service will be replicated permanently on all nodes. This - means that if one of the nodes crashes, the others will continue working - without disruption. In addition, nodes also can be added or replaced ‘on - the fly’. - -- **Administrator-friendly** - ejabberd is built on top of the Open Source Erlang. As a result you do not - need to install an external database, an external web server, amongst others - because everything is already included, and ready to run out of the box. - Other administrator benefits include: - - Comprehensive documentation. - - Straightforward installers for Linux. - - Docker packaging to help with deploy / development on Linux, Windows or MacOS. - - Deb and RPM packaging to support most Linux distributions. - - Web administration. - - Shared roster groups. - - Command line administration tool. - - Can integrate with existing authentication mechanisms. - - Capability to send announce messages. - -- **Internationalized** - ejabberd leads in internationalization. Hence it is very well suited in a - globalized world. Related features are: - - Translated to 25 languages. - - Support for IDNA. - -- **Open Standards** - ejabberd is the first Open Source XMPP server claiming to fully comply to - the XMPP standard. - - Fully XMPP-compliant. - - XML-based protocol. - - Many protocols supported. +- Source code: compile yourself, see [COMPILE](COMPILE.md) +- Installers from [ProcessOne Downloads][p1dl] (run/deb/rpm for x64) +- Installers from [ejabberd GitHub Releases][releases] (run/deb/rpm for x64 and arm64) +- Container image from [ejabberd Docker Hub][hubecs], see [ecs README][docker-ecs-readme] (for x64) +- Container image from [ejabberd Github Packages][packages], see [CONTAINER](CONTAINER.md) (for x64 and arm64) +- Using your [Operating System package][osp] +- Using the [Homebrew][homebrew] package manager -Additional Features -------------------- +Documentation +------------- -Moreover, ejabberd comes with a wide range of other state-of-the-art features: +Please check the [ejabberd Docs][docs] website. -- **Modularity** - - Load only the modules you want. - - Extend ejabberd with your own custom modules. - -- **Security** - - SASL and STARTTLS for c2s and s2s connections. - - STARTTLS and Dialback s2s connections. - - Web Admin accessible via HTTPS secure access. - -- **Databases** - - Internal database for fast deployment (Mnesia). - - Native MySQL support. - - Native PostgreSQL support. - - ODBC data storage support. - - Microsoft SQL Server support. - -- **Authentication** - - Internal authentication. - - PAM, LDAP and ODBC. - - External authentication script. - -- **Others** - - Support for virtual hosting. - - Compressing XML streams with Stream Compression (XEP-0138). - - Statistics via Statistics Gathering (XEP-0039). - - IPv6 support both for c2s and s2s connections. - - Multi-User Chat module with support for clustering and HTML logging. - - Users Directory based on users vCards. - - Publish-Subscribe component with support for Personal Eventing. - - Support for web clients: HTTP Polling and HTTP Binding (BOSH). - - Component support: interface with networks such as AIM, ICQ and MSN. - - -Quickstart guide ----------------- - -### 0. Requirements - -To compile ejabberd you need: - - - GNU Make. - - GCC. - - Libexpat ≥ 1.95. - - Libyaml ≥ 0.1.4. - - Erlang/OTP ≥ 19.3. - - OpenSSL ≥ 1.0.0. - - Zlib ≥ 1.2.3, for Stream Compression support (XEP-0138). Optional. - - PAM library. Optional. For Pluggable Authentication Modules (PAM). - - ImageMagick's Convert program and Ghostscript fonts. Optional. For CAPTCHA - challenges. - - Elixir ≥ 1.10.3. Optional. Alternative to build ejabberd - -If your system splits packages in libraries and development headers, you must -install the development packages also. - -### 1. Compile and install on *nix systems - -To compile ejabberd, execute the following commands. The first one is only -necessary if your source tree didn't come with a `configure` script (In this -case you need autoconf installed). - - ./autogen.sh - ./configure - make - -To install ejabberd, run this command with system administrator rights (root -user): - - sudo make install - -These commands will: - -- Install the configuration files in `/etc/ejabberd/` -- Install ejabberd binary, header and runtime files in `/lib/ejabberd/` -- Install the administration script: `/sbin/ejabberdctl` -- Install ejabberd documentation in `/share/doc/ejabberd/` -- Create a spool directory: `/var/lib/ejabberd/` -- Create a directory for log files: `/var/log/ejabberd/` - - -### 2. Start ejabberd - -You can use the `ejabberdctl` command line administration script to -start and stop ejabberd. For example: - - ejabberdctl start - - -For detailed information please refer to the -[ejabberd Documentation](https://docs.ejabberd.im) - - -### 3. Use ejabberd locally - -Alternatively, you can setup ejabberd without installing in your system: - - ./configure --with-rebar=rebar3 - make dev - -Or, if you have Elixir available and plan to develop Elixir code: - - ./configure --with-rebar=mix - make dev - -Check the full list of targets: +When compiling from source code, you can get some help with: + ./configure --help make help +Once ejabberd is installed, try: -Translation + ejabberdctl help + man ejabberd.yml + + +Development ----------- -Using any gettext editor, you can improve the translation files found in -`priv/msgs/*.po`, and then submit your changes. +Bug reports and features are tracked using [GitHub Issues][issues], +please check [CONTRIBUTING](CONTRIBUTING.md) for details. -Alternatively, a simple way to improve translations is using our Weblate project: -https://hosted.weblate.org/projects/ejabberd/ejabberd-po/ +Translations can be improved online [using Weblate][weblate] +or in your local machine as explained in [Localization][localization]. + +Documentation for developers is available in [ejabberd docs: Developers][docs-dev]. + +Security reports or concerns should preferably be reported privately, +please send an email to the address: contact [at] process-one [dot] net +or some other method from [ProcessOne Contact][p1contact]. + +For commercial offering and support, including _ejabberd Business Edition_ +and _Fluux (ejabberd in the Cloud)_, please check [ProcessOne ejabberd page][p1home]. -Links ------ +Community +--------- -- Documentation: https://docs.ejabberd.im -- Community site: https://www.ejabberd.im -- ejabberd commercial offering and support: https://www.process-one.net/en/ejabberd +There are several places to get in touch with other ejabberd developers and administrators: + +- [ejabberd XMPP chatroom][muc]: ejabberd@conference.process-one.net +- [Mailing list][list] +- [GitHub Discussions][discussions] +- [Stack Overflow][stackoverflow] + + +License +------- + +ejabberd is released under the GNU General Public License v2 (see [COPYING](COPYING.md)), +and [ejabberd translations](https://github.com/processone/ejabberd-po/) under MIT License. + + +[discussions]: https://github.com/processone/ejabberd/discussions +[docker-ecs-readme]: https://github.com/processone/docker-ejabberd/tree/master/ecs#readme +[docs-dev]: https://docs.ejabberd.im/developer/ +[docs]: https://docs.ejabberd.im +[erlang]: https://www.erlang.org/ +[features]: https://docs.ejabberd.im/admin/introduction/ +[github]: https://github.com/processone/ejabberd +[homebrew]: https://docs.ejabberd.im/admin/installation/#homebrew +[hubecs]: https://hub.docker.com/r/ejabberd/ecs/ +[im]: https://ejabberd.im/ +[issues]: https://github.com/processone/ejabberd/issues +[list]: https://lists.jabber.ru/mailman/listinfo/ejabberd +[localization]: https://docs.ejabberd.im/developer/extending-ejabberd/localization/ +[mqtt]: https://mqtt.org/ +[muc]: xmpp:ejabberd@conference.process-one.net +[osp]: https://docs.ejabberd.im/admin/installation/#operating-system-packages +[p1contact]: https://www.process-one.net/en/company/contact/ +[p1dl]: https://www.process-one.net/en/ejabberd/downloads/ +[p1home]: https://www.process-one.net/en/ejabberd/ +[packages]: https://github.com/processone/ejabberd/pkgs/container/ejabberd +[releases]: https://github.com/processone/ejabberd/releases +[sip]: https://en.wikipedia.org/wiki/Session_Initiation_Protocol +[stackoverflow]: https://stackoverflow.com/questions/tagged/ejabberd?sort=newest +[weblate]: https://hosted.weblate.org/projects/ejabberd/ejabberd-po/ +[xeps]: https://www.process-one.net/en/ejabberd/protocols/ +[xmpp]: https://xmpp.org/