Running MikoPBX in a container

MikoPBX Installation Guide using Docker container

To work with MikoPBX in a container, you need to install Docker and Docker Compose, as well as create a user and directories for storing configuration settings and call recordings according to the instructions

Docker installation and creating a user and directories

Launching the Docker container

To launch the container with your application, use the following commands:

# Pulling the container image
sudo docker pull ghcr.io/mikopbx/mikopbx-x86-64

# Running the container in unprivileged mode
sudo docker run --cap-add=NET_ADMIN --net=host --name mikopbx --hostname mikopbx \
           -v /var/spool/mikopbx/cf:/cf \
           -v /var/spool/mikopbx/storage:/storage \
           -e SSH_PORT=23 \
           -e ID_WWW_USER="$(id -u www-user)" \
           -e ID_WWW_GROUP="$(id -g www-user)" \
           -it -d --restart always ghcr.io/mikopbx/mikopbx-x86-64

Testing the functionality

To ensure that your MikoPBX application is posted and working in the Docker container, you can follow these steps after launching it. These steps will help you verify the container's status and view its logs.

Step 1: Check container status

First, ensure that the container is successfully launched and running. To do this, use the command docker ps, which will show a list of running containers and their statuses.

sudo docker ps

This command will display information about all active containers. Make sure that the mikopbx container is present in the list and its status indicates that it is running (e.g., status up).

Step 2: View container logs

After confirming that the container is running, the next step is to view the logs to ensure that the application has loaded without errors and is functioning properly. The docker logs command will allow you to see the output generated by your application.

sudo docker logs mikopbx

Check the command output for a message similar to the one below. This message indicates that MikoPBX is successfully loaded and ready for use:

++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|               All services are fully loaded welcome                |
|                       MikoPBX 2024.1.60.                           |
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|                        Web Interface Access                        |
|                                                                    |
| Local Network Address:                                             |
| https://10.0.0.4                                                   |
|                                                                    |
| Web credentials:                                                   |
|    Login: admin                                                    |
|    Password: admin                                                 |
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
| SSH access disabled!                                               |
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

If you see the MikoPBX startup process, wait a moment and re-run the command sudo docker logs mikopbx

Step 3: Check access to the web Interface

When the container starts, it lacks information about the host system's address, so you need to open the external address of the host system, in this case, Ubuntu, in a web browser. https://<host machine IP>

Log into the web interface using the admin login and the admin password to make sure that the web interface is accessible and functioning correctly.

Features of containerized MikoPBX

• The NET_ADMIN flag is required for the proactive protection system fail2ban and the firewall iptables to function inside the container. When an access block is triggered, for example, by entering an incorrect password, access from the IP address of the attacker will be blocked.

• If you need to use the "Backup Module", the container should be run with the –privileged flag. When MikoPBX is run in a container, backups can also be performed by manually archiving the cf and storage directories. In this case, the privileged mode is not necessary, but the container must be stopped during copying.

• The –net=host flag indicates that NAT between the host and container will not be used. MikoPBX will be directly connected to the host machine's network. All ports that the container needs to occupy will also be occupied on the host machine. If any port on the host machine is unavailable, errors will occur when loading MikoPBX. More details in the Docker documentation...

• If necessary, you can adjust the standard set of ports used by MikoPBX. This can be done by declaring environment variables when launching the container.

Creating a container from a tar archive

In addition to using our official registry, you might need to create a container from an image, for example, for a beta version. Our published releases and pre-releases include a tar archive, which we use to create a container.

Here is an example code for its use:

# Create a container from a tar archive
sudo docker import \
  --change 'ENTRYPOINT ["/bin/sh", "/sbin/docker-entrypoint"]' \
  mikopbx-2024.1.114-x86_64.tar \
  "mikopbx:2024.1.114"

# Launch the created container
sudo docker run --cap-add=NET_ADMIN --net=host --name mikopbx --hostname mikopbx \
	 -v mikopbx_cf:/cf \
	 -v mikopbx_storage:/storage \
	 -e SSH_PORT=23 \
	 -e ID_WWW_USER="$(id -u www-user)" \
	 -e ID_WWW_GROUP="$(id -g www-user)" \
	 -it mikopbx:2024.1.114

Environment variables for configuring MikoPBX

Below are some of the environment variables that will allow you to adjust the MikoPBX ports and settings used.

• SSH_PORT - port for SSH (22)

• WEB_PORT - port for the web interface via HTTP protocol (80)

• WEB_HTTPS_PORT - port for the web interface via HTTPS protocol (443)

• SIP_PORT - port for connecting a SIP client (5060)

• TLS_PORT - port for connecting a SIP client with encryption (5061)

• RTP_PORT_FROM - beginning of the RTP port range, voice transmission (10000)

• RTP_PORT_TO - end of the RTP port range, voice transmission (10800)

• IAX_PORT - port for connecting IAX clients (4569)

• AMI_PORT - AMI port (5038)

• AJAM_PORT - AJAM port used for connecting the telephony panel for 1C (8088)

• AJAM_PORT_TLS - AJAM port used for connecting the telephony panel for 1C (8089)

• BEANSTALK_PORT - port for the Beanstalkd queue server (4229)

• REDIS_PORT - port for the Redis server (6379)

• GNATS_PORT - port for the gnatsd server (4223)

• ID_WWW_USER - identifier for www-user (can be set with the expression $(id -u www-user), where www-user is NOT a root user)

• ID_WWW_GROUP - group identifier for www-user (can be set with the expression $(id -g www-user), where www-user is NOT a root group)

• WEB_ADMIN_LOGIN - login for Web interface access

• WEB_ADMIN_PASSWORD - password for Web interface access

A full list of all possible setting parameters is available in the source code here.