Installing FreeSWITCH from Source Using Docker and Docker Compose

Installing FreeSWITCH from Source Using Docker and Docker Compose

By Anil Kumar Singh — System Architect, Real-Time Media & Embedded AI

📦 Step 1: Crafting the Dockerfile

I started with Ubuntu 22.04 as the base image and layered in all the build tools and dependencies required by FreeSWITCH. Here’s a simplified version of the Dockerfile:

FROM ubuntu:22.04
LABEL maintainer="Anil Kumar Singh" 
LABEL description="FreeSWITCH build from source with modular, debug-friendly setup" 
ENV DEBIAN_FRONTEND=noninteractive 
ENV PKG_CONFIG_PATH=/usr/local/lib/pkgconfig:/usr/lib/pkgconfig 
ENV PATH="/usr/local/freeswitch/bin:$PATH" 
# Base build tools 
RUN apt update && apt install -y \ 
build-essential cmake git wget curl pkg-config \ 
libtool libtool-bin autoconf automake bash \ 
software-properties-common ca-certificates gnupg 

# Core dependencies 
RUN apt install -y \ 
libssl-dev libsqlite3-dev libcurl4-openssl-dev libpcre2-dev \ 
libspeex-dev libspeexdsp-dev libsofia-sip-ua-dev libldns-dev \ 
uuid-dev libpq-dev libopus-dev libsndfile1-dev libavformat-dev \ 
libavcodec-dev libavutil-dev libswscale-dev libjpeg-dev libtiff-dev \ 
libedit-dev liblua5.3-dev yasm nasm 

# Build libks and signalwire-c 
RUN git clone https://github.com/signalwire/libks.git /usr/src/libks && \ 
cd /usr/src/libks && cmake . && make -j$(nproc) && make install

RUN git clone https://github.com/signalwire/signalwire-c.git /usr/src/signalwire-c && \ 
cd /usr/src/signalwire-c && cmake . && make -j$(nproc) && make install 

# Build spandsp and sofia-sip from source 
RUN git clone https://github.com/freeswitch/spandsp.git /usr/src/spandsp && \ 
cd /usr/src/spandsp && ./bootstrap.sh && ./configure && make -j$(nproc) && make install && ldconfig 
RUN git clone https://github.com/freeswitch/sofia-sip.git /usr/src/sofia-sip && \ 
cd /usr/src/sofia-sip && ./bootstrap.sh && ./configure && make -j$(nproc) && make install && ldconfig 

# Clone and build FreeSWITCH 
RUN git clone https://github.com/signalwire/freeswitch.git /usr/src/freeswitch && \ 
cd /usr/src/freeswitch && chmod +x bootstrap.sh && bash ./bootstrap.sh -j && \ 
./configure && make -j$(nproc) && make install && \ 
make sounds-install && make moh-install 
WORKDIR /usr/src/freeswitch 
CMD ["bash"]

� Step 2: Docker Compose Setup

To simplify container management and volume mounting, I created a docker-compose.yml:

Note : Make sure you are using correct image name instead of freeswitch-custom.

services:
  freeswitch:
    image: freeswitch-custom
    container_name: freeswitch-dev
    ports:
      - "5060:5060/udp"         # SIP
      - "5080:5080/udp"         # External SIP
      - "5060:5060"
      - "5080:5080"
      - "8021:8021"             # Event Socket
      - "8081:8081"             # WebSocket (mod_verto)
      - "7443:7443"             # TLS WebSocket
      - "16384-20000:16384-20000/udp"  # RTP media
    volumes:
      - ./freeswitch-conf:/usr/local/freeswitch/conf        # Config override
      - ./freeswitch-logs:/usr/local/freeswitch/log         # Logs
      - ./custom-modules:/usr/src/freeswitch/src/mod        # Optional: custom modules
    restart: unless-stopped
    command: [ "-nc", "-conf", "/usr/local/freeswitch/conf", "-log", "/usr/local/freeswitch/log", "-db", "/usr/local/freeswitch/db"]
    #entrypoint: ["sleep", "3600"]

This setup allows me to mount configuration and log directories from the host, making it easy to tweak dialplans and inspect runtime behavior.

Just use “docker compose up — build -d” command to build and run.

⚠️ Challenges I Faced (and Solved)

1. Docker Volume Mount Errors on Windows

Using $(pwd) in volume paths caused errors:

"$(pwd)/conf" includes invalid characters for a local volume name

✅ Fix: Use %cd% in Command Prompt or ${PWD} in PowerShell for absolute paths.

2. Missing Dependencies During ./configure

Errors like:

No package ‘libpcre2–8’ found No usable sofia-sip No usable spandsp

✅ Fix: Installed libpcre2-dev, built sofia-sip and spandsp from source, and updated PKG_CONFIG_PATH.

3. Assembly Tools Not Found

Neither yasm nor nasm have been found.

✅ Fix: Installed yasm and nasm to enable libvpx compilation.

4. Lua Headers Missing

fatal error: lua.h: No such file or directory

✅ Fix: Installed liblua5.3-dev to compile mod_lua.

🚀 Running FreeSWITCH

After building the image:

docker-compose build docker-compose up

To access the FreeSWITCH CLI:

docker exec -it freeswitch fs_cli

🧠 Final Thoughts

Building FreeSWITCH from source in Docker isn’t just about getting it to run — it’s about creating a reproducible, modular, and debug-friendly environment. By resolving each dependency manually and layering the build process, I now have a container that’s ready for SIP testing, dialplan customization, and media server experimentation.

If you’re working on real-time media systems or SIP telephony, this setup is a solid foundation for deeper integration and automation.