Move some content from README to new COMPILE and CONTAINER files

3 files changed, 499 insertions, 170 deletions

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.
 
-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/