Claude enabled me to work on projects with a speed never possible before. I would like to make the results public for other people to use that don't have access to sometimes expensive AI subscriptions. Furthermore, solving problems with AI does mean that the process is often not documented (chat just gets deleted without care). In the earlier days this information was often publicly visible because the work was done by a community in a forum or other form of textual chat. My intention is to fill this gap by uploading findings from AI chats to my website.
The information presented is not checked 100% for mistakes but was generated from a chat that lead to a confirmed working result.
Abstract
izPBX VoIP Setup Documentation — Abstract
Authors: Tobias OE3TEC, Claude (Anthropic)
==========================================
This document describes the complete setup of a self-hosted LAN VoIP system
based on izPBX (Asterisk 20 + FreePBX 16) running in Docker on a home server.
The guide covers the full process from software selection through to verified
HD audio calls, including all configuration decisions, the reasoning behind
them, and the troubleshooting steps encountered along the way.
SCOPE
The system consists of three components:
- izPBX in Docker (Asterisk engine + FreePBX web GUI + MariaDB)
- A Snom 715 SIP desk phone on the local LAN (extension 100)
- Linphone on Ubuntu on the LAN (extension 101)
- MicroSIP on Windows connecting remotely over WireGuard VPN (extension 102)
No PSTN trunk is configured. This is a purely internal extension system
for home/lab use.
NETWORK TOPOLOGY
The WireGuard setup uses NAT between the client subnet (10.66.10.0/24) and
the server LAN (10.66.1.0/24). NAT handling is configured entirely at the
per-extension level (Direct Media = No) — no global transport settings are
needed or should be changed.
KEY TOPICS COVERED
- Why izPBX was chosen over a bare Asterisk install on OpenWRT
- Docker network architecture: the interaction between network_mode: host
(izpbx container) and the bridge-networked MariaDB container, and how
a fixed subnet solves the connectivity problem between them
- Pre-deployment port conflict analysis and resolution
- Annotated compose.yml and .env configurations with full reasoning
- FreePBX NAT configuration: Direct Media = No on WireGuard extensions
- Why the Local network field must be left empty — filling it in breaks
SIP response routing and causes all phones to stop registering
- FreePBX codec configuration for G.722 HD audio
- Snom 715 web interface registration and RTP settings
- Softphone setup: Linphone (Ubuntu) and MicroSIP (Windows) — both behave
identically with this setup; G.722 issues are always server-side
- Why G.722 reports as 8kHz in call stats despite being wideband (RFC 3551)
- Why G.722 fails with one-way audio when Direct Media is enabled
- Data persistence: what survives reboots, container restarts, and image
updates — and what does not
- Troubleshooting section covering: one-way audio through NAT, all phones
losing registration after Local network field was set, SIP authentication
failures, and FreePBX config changes not taking effect
- Management commands, upgrade procedure, and future Hamnet integration notes
INTENDED AUDIENCE
Anyone looking to reproduce this setup on a similar home server environment
running Docker, with a SIP desk phone and/or softphone clients connecting
both locally and over a WireGuard VPN with NAT. Basic familiarity with
Docker Compose and Linux is assumed.
Downloads
The full documentation can be found here.
izpbx-setup.pdf
