Preparing FreeSWITCH for development or integration can mean collecting dependencies, compiling modules and sorting out sound files before any call routing work begins. An isolated server makes that preparation harder.
I have packaged a compiled FreeSWITCH installation into an offline Docker bundle and uploaded it to GitHub. The aim is to let others start with configuration and call testing instead of repeating the build on each target server.
This guide is for contact center developers, integrators and operators. It covers importing the image, starting the container and checking the installation.
What the bundle contains
The release contains FreeSWITCH 1.10.12-release, mod_fcc 1.2.1-open and the commercially licensed mod_taering_stream 0.54. It also includes common modules such as mod_sofia, mod_event_socket, mod_callcenter and mod_conference, along with prompts and music on hold.
The repository lists PostgreSQL, MariaDB/MySQL, SQLite, ODBC and Redis support, plus mod_shout for uses including MP3 playback. These are capabilities included in the image. The Compose file does not deploy an external database server or configure your agents, queues and carrier gateways.
The bundle provides a starting point for development, integration and deployments where building online is inconvenient. Custom compile options or additional modules still require an appropriate image.
Download the release attachment
Use the release page and download:
freeswitch-1.10.12-fcc1.2.1-offline-bundle.tar.gz- The matching
.tar.gz.sha256checksum file
GitHub's automatically generated Source code archives do not include the image. Cloning the repository alone does not provide the complete deployment bundle either.
The target needs native Linux on x86_64/amd64, Docker Engine and the Docker Compose V2 plugin. Check the environment:
# 确认目标架构；预期输出为 x86_64。
uname -m
# 检查 Docker 服务及 Compose V2。
docker version
docker compose version
The current package does not support ARM64. Its startup script explicitly checks for Linux and x86_64. Mac users should deploy it to a compatible Linux server. Although some Docker Desktop versions offer optional host networking, that does not change this project's startup checks or deployment requirements.
Install Docker and Compose beforehand. For a completely disconnected server, obtain the matching Docker installation packages and dependencies separately; they are not part of this FreeSWITCH bundle.
Verify, extract and start
Copy both attachments to /opt on the Linux server. Run these commands with an account that has permission to use Docker and access the deployment directory:
# 进入离线包和校验文件所在目录。
cd /opt
# 依据发布方提供的文件校验下载包。
sha256sum -c freeswitch-1.10.12-fcc1.2.1-offline-bundle.tar.gz.sha256
The checksum check should report OK. Stop if it fails. After a successful check:
# 解压完整包并进入部署目录。
tar -xzf freeswitch-1.10.12-fcc1.2.1-offline-bundle.tar.gz
cd freeswitch-1.10.12-fcc1.2.1
# 从本地归档导入镜像并启动服务。
bash start.sh
The script checks prerequisites, imports the image with docker load, creates .env if absent and starts the service through Compose. The image tag is local/freeswitch:1.10.12-fcc1.2.1. There is no need to look for that tag on Docker Hub or run docker pull.
The current repository's start.sh imports the bundled image on every invocation and uses --force-recreate. Running it on an active system recreates the container and interrupts calls. Use the relevant Compose commands for routine operations after installation.
Check the running installation
From the deployment directory, run:
# 检查容器状态与 FreeSWITCH 版本。
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 repository describes the expected result as 1.10.12-release, true for both module checks and a healthy container after initialization. Those are acceptance targets, not claimed test results from your machine.
If the checks fail, inspect startup logs and SIP profiles:
# 查看近期日志，定位权限、端口与 XML 配置问题。
docker compose logs --tail=200 freeswitch
# 查看 SIP profile 的实际运行状态。
docker compose exec -T freeswitch fs_cli -x 'sofia status'
Then test inbound and outbound calls, two-way audio, DTMF, transfers, queueing and recording. A healthy container is only a basic service check; it does not establish that a carrier route or media path works.
Keep configuration and data outside the container
When conf/freeswitch.xml is absent, the image initializes a full default configuration. The host's ./conf is mounted at /usr/local/freeswitch/etc/freeswitch. That relative path belongs to the directory containing compose.yaml, rather than a fixed /opt/conf location.
Edit users, gateways, dialplans, SIP profiles and module settings there. XML changes often begin with reloadxml, but already loaded gateway, queue or module settings can require their own rescan or reload. Schedule a restart when changing listener addresses, ports or TLS startup parameters.
# 重新读取 XML；按配置类型决定是否还需模块级重载。
docker compose exec -T freeswitch fs_cli -x reloadxml
# 需要重启时先安排好现有通话，再执行此命令。
docker compose restart freeswitch
Existing configuration is retained on subsequent starts. The README also documents targeted migrations of older defaults, so back up and compare configuration before upgrading.
Database files, logs and recordings use separate named volumes. They survive container recreation, and an ordinary docker compose down retains them. Adding -v deletes the named volumes declared by this project. Back up conf/, .env, the database volume and recordings that must be retained. Persistence across container replacement still requires a separate backup process.
Prepare networking, credentials and licensing
The project uses network_mode: host, so service ports occupy the host directly. Documented defaults are SIP on 5060 and 5080, RTP on UDP 16384–32768, Event Socket on local port 8021 and the FCC API on local port 18080. Check the actual configuration and host firewall; adding Docker port publishing is unnecessary in this mode.
Replace default extension passwords, the Event Socket password and ACLs, and the FCC API token. Remove unused example users and routes, then configure SIP/NAT/RTP for the actual network. Host networking removes container port-mapping work; public address advertisement and two-way media still need correct configuration.
Offline deployment describes the image import and FreeSWITCH installation. The bundled mod_taering_stream is commercially licensed and, according to the repository, checks authorization online on first startup. A pending license is awaiting authorization. Compose mounts the host's /etc/machine-id read-only; the project states that its SHA-256 is used as a stable host identifier. Confirm licensing arrangements before using this module on a disconnected network.
Compose sets no CPU or memory limits by default. Shared hosts can set limits in .env and recreate the container to apply them. Choose values through tests covering calling, transcoding and recording rather than assuming a fixed concurrency figure.
The project README contains installation, migration and operations details. For help, open a repository issue with the host architecture, Docker/Compose versions, reproduction steps and sanitized logs. Leave out passwords, tokens, phone numbers and recordings.