savagecore/freepbx repository overview

⁠github.com/SavageCore/docker-freepbx

⁠Introduction

Dockerfile to build a FreePBX⁠ - A Voice over IP manager for Asterisk. Upon starting this image it will give you a turn-key PBX system for SIP calling.

• Latest release FreePBX 17
• Latest release Asterisk 22
• Installed from Sangoma packages, no source compile
• Choice of running embedded database or modifies to support external MariaDB Database and only require one DB.
• Supports data persistence
• Fail2Ban installed to block brute force attacks
• Debian Bookworm base w/ Apache2
• NodeJS stock Bookworm
• PHP 8.2
• Redis for caching, replaces MongoDB and XMPP lets-chat
• Automatically installs User Control Panel and displays at first page
• Option to Install Flash Operator Panel 2⁠
• Customizable FOP and Admin URLs

If you are presently running this image when it utilized FreePBX 14 and Asterisk 14 and can no longer use your image, please see this post⁠

Changelog⁠

⁠Maintainer

• SavageCore⁠

This project is a fork of tiredofit/docker-freepbx⁠ by Dave Conroy⁠, which provided the original container layout, init scripts, and documentation this image builds on.

⁠Table of Contents

• Introduction⁠
• Maintainer⁠
• Table of Contents⁠
• Prerequisites and Assumptions⁠
• Installation⁠
  • Build from Source⁠
  • Prebuilt Images⁠
• Configuration⁠
  • Quick Start⁠
  • Persistent Storage⁠
  • Environment Variables⁠
    • Base Images used⁠
  • Networking⁠
  • Fail2Ban⁠
• Maintenance⁠
  • Shell Access⁠
• Support⁠
  • Usage⁠
  • Bugfixes⁠
  • Feature Requests⁠
  • Updates⁠
• License⁠
• References⁠

⁠Prerequisites and Assumptions

• Assumes you are using some sort of SSL terminating reverse proxy such as:
  • Traefik⁠
  • Nginx⁠
  • Caddy⁠
• You must have access to create records on your DNS server to be able to setup the demo installation before configuration.

You will also need an external MySQL/MariaDB container, although it can use an internally provided service (not recommended).

⁠Installation

⁠Build from Source

Clone this repository and build the image with docker build -t (imagename) .

⁠Prebuilt Images

Builds of the image are available on Docker Hub⁠ and is the recommended method of installation.

docker pull savagecore/freepbx:(imagetag)

The following image tags are available along with their tagged release based on what's written in the Changelog⁠:

⁠Configuration

⁠Quick Start

The quickest way to get started is using docker-compose⁠. See the examples folder for a working docker-compose.yml⁠ that can be modified for development or production use.

• Set various environment variables⁠ to understand the capabilities of this image. A Sample docker-compose.yml is provided that will work right out of the box for most people without any fancy optimizations.
• Map persistent storage⁠ for access to configuration and data files for backup.
• Make networking ports⁠ available for public access if necessary

The first boot can take from 3 minutes - 30 minutes depending on your internet connection as there is a considerable amount of downloading to do!

Login to the web server's admin URL (default /admin) and enter in your admin username, admin password, and email address and start configuring the system!

⁠Persistent Storage

The container supports data persistence and during Dockerfile build creates symbolic links for /var/lib/asterisk, /var/spool/asterisk, /home/asterisk, and /etc/asterisk. Upon startup configuration files are copied and generated to support portability.

The following directories should be mapped for persistent storage in order to utilize the container effectively.

⁠Environment Variables

⁠Base Images used

This image is based on Debian Bookworm with the s6-overlay⁠ init system for added capabilities. Outgoing SMTP capabilities are handlded via msmtp. Individual container performance monitoring is performed by zabbix-agent⁠. Additional tools include: bash,curl,less,logrotate, nano,vim.

The container layout and base init scripts were originally adapted from the tiredofit/docker-debian⁠ base image family.

ADMIN_DIRECTORY and FOP_DIRECTORY may not work correctly if WEBROOT is changed or UCP_FIRST=FALSE

⁠Networking

The following ports are exposed.

⁠Fail2Ban

• For fail2ban rules to kickin, the security log level needs to be enable for asterisk full log file. This can be done from the Settings > Log File Settings > Log files.

⁠Migration from 15 (skip 16)

There is no in-place upgrade. 15 to 17 crosses Debian Buster to Bookworm, PHP 5.6 to 8.2, and Asterisk 17 to 22 (dialplan macros removed).

1. On the 15 system: Admin, Backup and Restore, run a Full Backup, download the tarball.
2. Deploy this 17 image with an EMPTY /data volume and complete first boot.
3. On the 17 system: Admin, Backup and Restore, Restore from the 15 tarball.
4. If the 15 system used an external database and the 17 system does not, re-point Settings, Advanced Settings, CDR Database Settings (host, name, user, password) at the new database, then fwconsole reload so Asterisk ODBC follows.
5. Audit custom dialplan and third-party modules for Asterisk macro usage (Macro(), MacroExit) and rewrite as GoSub before cutover.
6. Re-issue/renew certificates (cert paths move with the new Apache/PHP layout) and re-test trunks, routes, voicemail, UCP.

⁠Maintenance

• There seems to be a problem with the CDR Module when updating where it refuses to update when using an external DB Server. If that happens, simply enter the container (as shown below) and execute upgrade-cdr, which will download the latest CDR module, apply a tweak, install, and reload the system for you.

⁠Known Bugs

• When installing Parking Lot or Feature Codes you sometimes get SQLSTATE[22001]: String data, right truncated: 1406 Data too long for column 'helptext' at row 1. To resolve login to your SQL server and issue this statement: alter table featurecodes modify column helptext varchar(500);
• If you find yourself needing to update the framework or core modules and experience issues, enter the container and run upgrade-core which will truncate the column and auto upgrade the core and framework modules.

⁠Shell Access

For debugging and maintenance purposes you may want access the containers shell.

docker exec -it (whatever your container name is e.g. freepbx) bash

⁠Support

These images were built to serve a specific need in a production environment and gradually have had more functionality added based on requests from the community.

⁠Usage

• The Discussions board⁠ is a great place for working with the community on tips and tricks of using this image.

⁠Bugfixes

• Please, submit a Bug Report⁠ if something isn't working as expected. I'll do my best to issue a fix in short order.

⁠Feature Requests

• Feel free to submit a feature request, however there is no guarantee that it will be added, or at what timeline.

⁠Updates

• Best effort to track upstream changes, More priority if I am actively using the image in a production environment.

⁠License

MIT. See LICENSE⁠ for more details.

⁠References

• https://freepbx.org/⁠