Browse Source

Move some content from README to new COMPILE and CONTAINER files

pull/3532/merge
Badlop 4 months ago
parent
commit
bb2cb19a5c
  1. 126
      COMPILE.md
  2. 288
      CONTAINER.md
  3. 255
      README.md

126
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
```

288
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
```

255
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.
Key Features
------------
- **Cross-platform**
ejabberd runs under Microsoft Windows and Unix-derived systems such as
Linux, FreeBSD and NetBSD.
- **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.
Additional Features
-------------------
Moreover, ejabberd comes with a wide range of other state-of-the-art features:
- **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
Check the features in [ejabberd.im][im], [ejabberd Docs][features],
[ejabberd at ProcessOne][p1home], and a list of [supported protocols and XEPs][xeps].
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)
Installation
------------
### 3. Use ejabberd locally
There are several ways to install ejabberd:
Alternatively, you can setup ejabberd without installing in your system:
- 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
./configure --with-rebar=rebar3
make dev
Or, if you have Elixir available and plan to develop Elixir code:
Documentation
-------------
./configure --with-rebar=mix
make dev
Please check the [ejabberd Docs][docs] website.
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
-----------
Using any gettext editor, you can improve the translation files found in
`priv/msgs/*.po`, and then submit your changes.
ejabberdctl help
man ejabberd.yml
Alternatively, a simple way to improve translations is using our Weblate project:
https://hosted.weblate.org/projects/ejabberd/ejabberd-po/
Development
-----------
Links
-----
- Documentation: https://docs.ejabberd.im
- Community site: https://www.ejabberd.im
- ejabberd commercial offering and support: https://www.process-one.net/en/ejabberd
Bug reports and features are tracked using [GitHub Issues][issues],
please check [CONTRIBUTING](CONTRIBUTING.md) for details.
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].
Community
---------
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/

Loading…
Cancel
Save