(Unofficial) Docker image of FreePBX 15 + Asterisk 16 - izPBX project

if someone is interested, I’m writing here to make it know that we are developing a (unofficial) docker image of FreePBX 15 with Asterisk 16 LTS.
Right now the release (0.9.1) is in advanced testing phase (using it in production since two weeks).
Other testers and positive feedback are welcome :slight_smile:

This is the actual features list:

  • 60 secs install from zero to a running full features PBX system.
  • Really fast initial bootstrap to deploy a full stack Asterisk+FreePBX system
  • Small image footprint
  • CentOS 8 64bit powered
  • Asterisk PBX Engine (compiled from scratch)
  • Opus, G729, Motif codecs compiled
  • FreePBX WEB Management GUI (with predownloaded modules for quicker initial deploy)
  • First automatic installation managed when deploying the izpbx, subsequent updates managed by FreePBX Official Version Upgrade
  • Persistent storage mode for configuration data (define APP_DATA variable to enable)
  • Misc izpbx scripts (into container shell digit izpbx+TAB to discover)
  • tcpdump and sngrep utility to debug VoIP packets
  • fail2ban as security monitor to block SIP and HTTP brute force attacks
  • supervisord as services management with monitoring and automatic restart
  • postfix MTA daemon for sending mails (notifications, voicemails and FAXes)
  • cron daemon
  • Apache 2.4 and PHP 7.3 (mpm_prefork+mod_php configuration mode)
  • Automatic Let’s Encrypt HTTPS Certificate management for exposed PBXs to internet
  • Commercial SSL Certificates support
  • Logrotating of services logs
  • FOP2 Operator Panel (optional)
  • Integrated Asterisk Zabbix agent for active health monitoring
  • All Bootstrap configurations made via single central .env file
  • Many customizable variables to use (look inside default.env file)
  • Two containers setup: (antipattern docker design but needed by the FreePBX ecosystem to works)
    • izpbx-asterisk: Asterisk Engine + FreePBX Frontend + others services
    • mariadb: Database Backend

for more info, consult the official izPBX project docker hub page:


Because make successfully running Asterisk/FreePBX SIP protocol on a Cloud Native Environment is a challenge, based on user feedback, will follow FAQ and troubleshooting guide to make a little less pain the deployment (future work will be in a Kubernetes deploy via Helm Chart)

Kind regards


I really wish people would stop doing this 8-(

You have a whole bunch of problems waiting for you. Firstly, you have a new and exciting level of NAT problems by putting it inside docker.

Secondly, because Docker has to proxy ports individually, you’ve limited the RTP range to be 10000-10200, which means at most 50 simultaneous calls and as a wonderful bonus to that, you’ve removed all the security that randomizing RTP gives you (which you really want because spoofing RTP is trivial)

Thirdly STOP COMPILING ASTERISK. REALLY. STOP DOING THIS. There’s a bunch of projects that do this for you, and do testing and QA and everything, and even more importantly compile it correctly. I was happy and pleasantly surprised to see that you did actually compile it with libunbound, which is the first I’ve seen in ages, but you also installed Motif, which is 100% useless and dead.

Finally, Docker is totally the wrong tool for this, and I don’t know how many times I can say this. The correct tool is LXD. Docker was designed for stateless microservices. They’ve put persistence in, because why not, right? But, the whole Docker idea is based around ‘one service == one container’.

FreePBX is Asterisk, Apache, MySQL and NodeJS at the bare minimum. All of those things need to update themselves, which means THEY need persistent storage, and suddenly you’ve got the entire container exported via persistant storage and… hey, that’s exactly what LXD does for you!

I am sorry to rain on your parade, but I’ve said this a bunch of times. LXD good, Docker Bad. Docker EXCEPTIONALLY BAD for VoIP unless you’re using host networking or totally ignoring RTP.


Hi Rob,

thank you for your feedback, you spent a lot of energy in answering this post and I thank you.
This challenge was born to accomplish a “personal” missing need (fast deploy FreePBX+Asterisk in a docker env. Because no official packages exist).
It is “technically” questionable running FreePBX+Asterisk ecosystem inside a docker container? Sure.
Many bricks must be in the right place to make a working cloud native PBX.
Disabling Docker proxy and running asterisk container in network host mode (as documented in the deploy quick install guide) was a needed choice to make NAT working (anyway the default shipped 200 RTP ports range is configurable by external .env file).
So what is the main target of this project? because your concern, I understand it should be well written.
The main target was to replace a traditional deploy model (VM or baremetal install via ISO image) in a fast and quick replicable way, for “small” PBX systems (so 50 concurrent calls by default, are acceptable).
Any positive comment and further enhancement is welcome, so as removing Motif codec (if you find it useless) or randomizing RTP range from 10000 to 20000 for security purpose it is an important advice that I am pleased to receive :slight_smile:

In the past many people have requested this functionality, and the only reason I wrote here is that, in some way, it could be of interest and help for those who want to try this challenge (we are still in the early stages and much development is yet to come).

If you believe that this post creates problems for the FreePBX business I ask you the kindness to remove it.

Kind regards


must admit LXD looks enticing , anyway interesting work …

Rob actually does put forward some valid concerns

1 Like

It’s because he’s been there already. People have been trying to build “FreePBX in a Docker” for something like two years, and they’ve all had to come up with some kind of workarounds for all of the issues Rob listed - the recompile of Asterisk with the incorrect options is just the shining example.

1 Like


to be honest, looking into official FreeePBX Distro Asterisk src.rpm package (http://yum.freepbxdistro.org/pbx/SRPMS/asterisk/13/asterisk13-13.29.2-2.shmz65.1.210.src.rpm) the spec file contains these build options:

./configure --libdir=%{_libdir} --with-pjproject-bundled --with-jansson-bundled
make menuselect.makeopts
#menuselect/menuselect --list-options to get the options passed below
menuselect/menuselect --disable-category MENUSELECT_CORE_SOUNDS --disable-category MENUSELECT_EXTRA_SOUNDS --disable-category MENUSELECT_MOH --enable-category MENUSELECT_ADDONS --enable res_pktccops --enable chan_mgcp --enable chan_motif --enable app_meetme --enable app_page --enable res_snmp --enable res_srtp --enable DONT_OPTIMIZE --disable BUILD_NATIVE --enable BETTER_BACKTRACES --enable res_statsd --enable res_chan_stats --enable res_endpoint_stats menuselect.makeopts


make %{makeflags}

how can we see, the chan_motif is “enabled” in the official FreePBX binary :slight_smile:

seriously: what is the difference from using “official” binary package or a self compiled asterisk binary using the same compile options and flags? exist a technical difference?

Kind regards


LXD is better suited if starting fresh, but if already using Docker I don’t know if I would add to the mix.

A fat Docker container with macvlan networking should be fine with little or no compromises, but goes against Docker dogma.

1 Like

I’ll throw my 2 cents into the ring. First off, I love that someone is trying to take this on. There are many reasons why docker could be useful to the FreePBX project and creating a simple dev environment is at the top of my list of potential applications. That being said, I don’t think that docker is particularly the wrong tool to do this, but I’m not sure that makes LXD is the right tool either.

Side Note: The project link from the OP is incorrect. The link to the project can be found here: https://hub.docker.com/r/izdock/izpbx-asterisk

A problem I see time and time again is that everyone wants to treat docker as if it acts and behaves as a Virtual Machine and it definitely is not that. By doing so, they want to make one image for FreePBX and pile a bunch of stuff into it when that is probably the wrong approach. That being said, docker works best when you split EACH process into a singe container. I would imagine a successful approach would end up looking more like a docker compose file than a docker image, which is the recommended setup for the project, however I would argue that there isn’t enough separation today for it today. When done, I would expect a ‘FreePBX Stack’ to have at least a PHP App image, a Node App image, a MySQL image, and an Asterisk Image at the minimum.

Now, the problem with putting FreePBX in Docker is that it is not designed to be spit up into several smaller containers from an architecture standpoint. As far as I know, at least two major concerns (there are probably a few more that I don’t know about as well) that hold back the FreePBX project from having really good docker support:

  1. FreePBX directly manages the config files for an Asterisk instance. The problem here is if the FreePBX php app runs in one docker container, and Asterisk runs in another, how do you update the asterisk config?

  2. Similarly, AGI also runs in the PHP app. How do you get asterisk to execute an AGI running in a different container?

Without directly addressing these problems, I believe anyone who tries to take on a FreePBX Docker project (LXD included) will end up having a bad time.

I’ll argue that this statement is partially correct. It’s correct when using the default config of docker, however, the OP used the ’ "userland-proxy": false docker option to resolve this issue, which I believe is a good strategy. Another way to resolve this issue is to run the contain’s networking directly on the host network, which will mostly resolve the proxy ports issue because they will no longer be needed. (https://docs.docker.com/network/network-tutorial-host/) HOWEVER, this does create a new issue for fail2ban and the firewall module of FreePBX because it can no longer manage the iptable routes. That being said, the network management in FreePBX is currently inadequate today for something like docker and may require a special module for it to work.

The issue here is that Sangoma doesn’t have an official Asterisk docker image. I believe having one would relieve some of the concerns here and people wouldn’t have to compile one. I am not going to say I would recommend using a third party Asterisk docker image due to security concerns as well as other obvious issues of running something not officially supported by the project maintainer.

Technically, Asterisk and MySQL in theory should be the only services that “need” persistent storage here. For MySQL this problem has been solved a million times. For Asterisk, the main issue here once again comes down to the management of config files and modifying config dynamically in a docker image. A solution would also need to be made for Asterisk to save voicemails to a more docker friendly persistent storage device as well. The persistent storage concerns of the PHP App / Node App are probably due to bad design since these apps should be stateless anyways.

All in all, I like the work that was done in this project. And if you ever want to discuss this more in detail feel free to reach out to me.


And FreePBX itself, obviously. But you then get into all the things that is FreePBX. It’s html and modules, it’s AGIs, it’s /etc/asterisk it’s sound and music files, etc.

This is why I keep saying this it’s the wrong tool.

1 Like

If docker is chosen to run your backend infrastructure, then you’re probably going to want to abandon the FreePBX managed module updates in favor of just managing them with docker. Docker is basically immutable infrastructure, and the module system of FreePBX doesn’t fit in with this philosophy.

As far as being the wrong tool, for the current state of FreePBX, I will not disagree. That being said, changes can be made to FreePBX to increase support for docker. I don’t know if this will always be the case in the future, but FreePBX needs to be modified to support it.


This topic was automatically closed 31 days after the last reply. New replies are no longer allowed.