English
中文

Why My AI Calling Course Uses an Offline FreeSWITCH Docker Image

I recently published the outline for a course on building an AI calling platform from scratch. It starts with the first working call, then moves through FCC call control, a management interface, real-time audio, ASR, LLM, TTS, and a business knowledge base.

There is a practical problem with asking every participant to compile FreeSWITCH before the course begins. Source downloads can be slow or unavailable on some networks. Linux distributions provide different library versions. Build options can also leave out a module that a later lesson needs.

Each problem can be diagnosed, but that changes the first lesson into a build troubleshooting session. I have prepared an offline Docker bundle containing the FreeSWITCH environment used by the course. The following lessons will use that image as their common starting point.

Why the course does not begin with a source build

Building FreeSWITCH from source is useful. Anyone modifying the core, developing a native module, or maintaining a custom distribution will eventually need to understand the build process.

That is not the first result this course promises. The immediate goal is to give developers who are new to telephony a working system where they can place a call and inspect what happened.

When participants use different distributions, dependencies, compiler options, and module sets, the same symptom can have several unrelated causes. A command that works in one build may fail in another because the required module was never compiled.

The Docker image is there to keep the course environment consistent.

What the course image contains

The current course baseline contains:

• FreeSWITCH 1.10.12-release
• FCC module: mod_fcc 1.2.1-open
• Call center module: mod_callcenter
• Common modules including mod_sofia, mod_event_socket, mod_conference, mod_fifo, mod_distributor, and mod_limit
• MariaDB/MySQL, PostgreSQL, SQLite, ODBC, and Redis support
• mod_shout, higher-quality prompt audio, and music on hold

FreeSWITCH 1.10.12 is an official upstream release. Here it is the course version, not a claim that it is the latest FreeSWITCH release. Fixing the version keeps the modules, configuration layout, and commands consistent across lessons. When the course image needs an upgrade, I will document what changed and how to migrate.

FreeSWITCH and its runtime libraries are already built into the image. The target server does not need Git, CMake, a compiler, FreeSWITCH development packages, or a fresh source download.

Why the image is not on Docker Hub

A public registry is convenient when every participant has reliable access to it. One docker pull command is enough.

This course image is meant to remove network-dependent source and dependency downloads from the initial setup. Making Docker Hub availability another hard prerequisite would bring part of that problem back.

The current delivery format is a complete offline bundle. It includes the image archive, compose.yaml, .env.example, start.sh, and configuration notes. Docker officially supports importing an archived image with docker load. Compose can then start the local image without pulling FreeSWITCH from a registry.

The bundle still has to reach the server through a download, SCP, SFTP, removable storage, or an internal file server. Once the complete file has arrived and its checksum has been verified, installation no longer depends on an external container registry.

What the server still needs

The current image targets Linux x86_64/amd64. I recommend a native Linux server with a standard rootful Docker Engine. macOS, Windows Docker Desktop, and WSL2 are not the production target for this course deployment.

Prepare the following before importing the bundle:

• Docker Engine
• Docker Compose V2, invoked as docker compose
• tar and gzip
• A root user or trusted administrator who can run Docker commands

Check the server with:

uname -m
docker version
docker compose version
tar --version

uname -m should return x86_64.

An offline FreeSWITCH image does not mean Docker Engine is included. A server without Docker must install it from the appropriate distribution packages. On a completely disconnected server, prepare the matching Docker RPM or DEB packages and their dependencies on another system, or ask the system administrator to install them in advance. Docker documents Compose V2 as a Linux CLI plugin.

How to verify the course environment

After extracting the bundle, enter its directory and run:

./start.sh

The script checks Docker and Compose V2. On its first run, it imports the bundled image, creates the local environment and configuration files, then runs docker compose up -d --no-build. It skips the import when the image already exists.

A running container is only the first check. Verify FreeSWITCH and the two modules needed by the course:

docker compose ps
docker compose exec -T freeswitch fs_cli -x status
docker compose exec -T freeswitch fs_cli -x 'module_exists mod_fcc'
docker compose exec -T freeswitch fs_cli -x 'module_exists mod_callcenter'

The expected result is a healthy container, FreeSWITCH 1.10.12-release, and true for both module queries. Those are the basic conditions for continuing with the course.

On the first start, the image also copies its version-matched default configuration into the host-side conf/ directory. Later changes to SIP profiles, dialplans, users, gateways, FCC, or call center configuration remain on the host when the container is recreated.

What the image does not solve

A common image removes many build differences. It cannot hide the operational work required by a telephony system.

SIP trunks, NAT, public addresses, RTP ranges, and firewall rules still depend on the real network. The Compose configuration uses network_mode: host, so the container shares the host network. Docker's host networking documentation explains that the container receives no separate IP address and published-port options do not apply in this mode.

The default FreeSWITCH configuration is for initialization and course exercises. Before connecting a real trunk or considering production use, the operator still needs to:

• Change default user passwords
• Change the Event Socket password, restrict its ACL, and keep port 8021 off the public Internet
• Replace the FCC token and restrict access to its API
• Configure SIP, NAT, and RTP for the actual network and carrier
• Remove unused sample users, gateways, and dialplans
• Back up configuration, databases, logs, and recordings
• Test inbound and outbound calls, transfers, queues, recording, music on hold, DTMF, and failure recovery
• Size CPU and memory from measured concurrency, CPS, recording, and transcoding workloads

Seeing a container run proves that the process started. It does not prove that the calling platform is ready for production. Later parts of the course will cover that gap.

How this connects to the rest of the course

With one FreeSWITCH baseline, the course can move through a predictable sequence:

• Register test extensions and complete the first extension-to-extension call
• Connect a test SIP trunk and verify a real inbound or outbound call
• Control calls through the FCC HTTP and WebSocket APIs
• Build a small management interface with Vue 3
• Receive PCM audio from a call and send backend audio into it
• Connect ASR, LLM, and TTS while handling interruptions, timeouts, and failures
• Add knowledge retrieval, call summaries, monitoring, load tests, and production checks

The commands, paths, and module versions in later lessons will refer to this image. When something fails, we can spend less time asking whether a build omitted a module and more time examining the actual call and AI audio path.

Download and image updates

Follow my WeChat Official Account and send the Chinese keyword 镜像包 to receive the download link. I will continue updating the course material and related files in the same cloud drive, so keep the link after you receive it.

After receiving the file, verify its SHA-256 checksum before extracting and importing it. A future image upgrade should not overwrite an existing production configuration. Back up conf/, databases, and recordings, import the new image, switch the image tag, then verify the version, modules, SIP profiles, FCC, and an actual call.

If you plan to follow the course for AI outbound calling, customer service, a voice bot, or a conventional calling platform, you can prepare a Linux x86_64 server with Docker Engine and Compose V2 now. Once the bundle has been downloaded, the first practical task will be placing a working call.