FreePBX 17 Docker Setup on Spoljarevic's Knowledgebase

Introduction

Mon, 01 Jan 0001 00:00:00 +0000

What is FreePBX?

FreePBX is an open-source web GUI for Asterisk, the PBX/VoIP engine that underpins it. Asterisk on its own is configured through plain-text dialplan files; FreePBX wraps it in a web interface for managing extensions, trunks, inbound/outbound routes, IVRs, voicemail, and the rest of what a phone system needs, without hand-editing Asterisk config. Version 17 is the current release line, built on Asterisk 22 and PHP 8.2.

Usage

Mon, 01 Jan 0001 00:00:00 +0000

Prerequisites

Docker and Docker Compose (docker-compose or the docker compose plugin) on the host.
A host willing to run a privileged container — this setup needs --privileged and an unconfined seccomp profile for systemd to manage services inside the container.

1. Clone the repository and build the image

git clone https://codeberg.org/Spoljarevic/FreePBX-17-Container.git
cd FreePBX-17-Container
sudo docker-compose build

The build stage (see Code Explanation) only installs the OS-level prerequisites and copies in the install script — FreePBX itself is not installed at build time.

Code Explanation

Mon, 01 Jan 0001 00:00:00 +0000

`Dockerfile`

FROM debian:bookworm
...
RUN apt-get update && apt-get install -y \
 wget curl gnupg2 sudo git vim ca-certificates lsb-release software-properties-common \
 systemd systemd-sysv dbus net-tools openssh-client \
 && apt-get clean
WORKDIR /usr/src
COPY sng_freepbx_debian_install.sh .
RUN chmod +x ./sng_freepbx_debian_install.sh
RUN ln -s /var/lib/asterisk/bin/fwconsole /usr/sbin/fwconsole || true
EXPOSE 80 443 5060/udp 5160/udp 18000-18100/udp
CMD ["/bin/bash"]

The image is deliberately thin:

Base: debian:bookworm — Sangoma’s install script hard-codes support for Debian 12 only (it checks VERSION_CODENAME//etc/debian_version and exits if it isn’t bookworm).
Installed at build time: only systemd/systemd-sysv/dbus (so the container can boot like a real init system) plus generic tooling the install script or an admin would want (wget, curl, git, vim, etc). FreePBX, Asterisk, MariaDB, Apache, and PHP are not installed here — that all happens later, at container runtime, by running the copied-in script manually.
The fwconsole symlink: fwconsole is FreePBX’s CLI (module management, restarts, etc). The install script normally expects it at a path that isn’t always on PATH yet immediately after install in a fresh container; the symlink into /usr/sbin pre-empts that so fwconsole works without extra steps once FreePBX is installed. The || true makes the build tolerant of the target not existing yet at build time.
CMD ["/bin/bash"]: the image’s default command is just a shell — the actual PID 1 process is overridden by docker-compose.yml’s command: ["/sbin/init"], not this line.

Installing FreePBX at build time isn’t possible here: the installer needs a running init system managing services (systemctl), which only exists once the container is actually started, not while docker build is assembling image layers.

FAQ

Mon, 01 Jan 0001 00:00:00 +0000

Why does the container need `privileged: true`?

Because it runs systemd as PID 1, and systemd needs privileges Docker doesn’t grant by default (managing cgroups, mounting filesystems, controlling devices) to supervise the services FreePBX depends on — Apache, MariaDB, Asterisk. Without it, /sbin/init won’t boot cleanly inside the container. See Introduction for the trade-off this implies.

Why isn’t FreePBX installed automatically when I build the image?

Sangoma’s install script assumes it’s running on an already-booted system with a working init system managing services — that’s only true once the container is actually running, not while docker build is assembling layers. So the build stage only prepares the environment (Debian + systemd + the script itself); you run the installer yourself after docker-compose up -d. See Usage for the exact steps.

FreePBX 17 Docker Setup on Spoljarevic's Knowledgebase

Introduction

What is FreePBX?

Usage

Prerequisites

1. Clone the repository and build the image

Code Explanation

Dockerfile

FAQ

Why does the container need privileged: true?

Why isn’t FreePBX installed automatically when I build the image?

`Dockerfile`

Why does the container need `privileged: true`?