Skip to main content

FreeSWITCH Docker Container Setup Documentation

Overview​

This guide will walk you through the process of containerizing FreeSWITCH using Docker in an Ubuntu environment. FreeSWITCH is a powerful, open-source telephony platform designed for building communication applications. This documentation is designed for beginners, and we’ll be covering the setup step-by-step.

Prerequisites​

Before proceeding, ensure you have the following:

  • A machine with Docker installed. If Docker is not installed, follow this guide.
  • Basic knowledge of terminal commands.

Steps​

Cloning the Repository​

First, download or clone the repository containing the FreeSWITCH Docker setup.

git clone https://git.bngrenew.com/eva/freeswitch-docker
cd docker

The repository contains the necessary files for containerizing FreeSWITCH in an Ubuntu environment using Docker. Here’s a breakdown of the key contents and their purposes:

  • Dockerfile: This file contains the instructions to build a Docker image that will install and configure FreeSWITCH on an Ubuntu base. The Dockerfile is essential for setting up the containerized environment.

  • freeswitch.sh: This updated shell script manages the lifecycle of the FreeSWITCH service within the Docker container. Key features include:

    • Starting FreeSWITCH: The script starts FreeSWITCH in the background, logging the start process to a log file located at /var/log/freeswitch_monitor.log.
    • Logging: Each action and status check is logged with a timestamp, ensuring that the status of FreeSWITCH can be monitored easily.
    • Monitoring FreeSWITCH: The script continuously monitors the FreeSWITCH process by checking if it is still running. If the process crashes or stops, the script logs the event and exits the container.

  • config/: This directory holds the configuration files for FreeSWITCH, which define how the software operates. The specific files include:

    • acl.conf.xml: Manages access control lists (ACLs), which determine which IP addresses can interact with FreeSWITCH.
    • public.xml: Controls the public context for FreeSWITCH, which is used to route incoming calls.
    • verto.conf.xml: Configures Verto, a WebRTC interface for real-time voice, video, and chat through web browsers.
    • modules.conf.xml: Manages which FreeSWITCH modules are loaded, enabling or disabling certain features.
    • event_socket.conf.xml: Configures the event socket, which allows external applications to interact with FreeSWITCH using the Event Socket Protocol (ESP).

Build the Docker Image​

To build the Docker image, run the following command in the project directory:

docker build -t freeswitch:x.y.z .

This command does the following:

  • Builds a Docker image from the current directory (.): The . specifies the current directory as the location of the Dockerfile and context for building the image.
  • Tags the image with a custom name and version (-t freeswitch:x.y.z): Assigns the name freeswitch and version x.y.z (which can be replaced with the desired version, e.g., freeswitch:1.0.0) to the Docker image. This tag makes it easier to reference the image when running containers.

Running the FreeSWITCH Container​

Once the image is built, you can run the FreeSWITCH container with the following command:

tip

Using the -p option to map ports in container can lead to significant consumption of system resources, such as RAM and CPU, potentially causing instability in your system. This is particularly relevant in a Docker environment, where resource efficiency is crucial.

Instead, it is recommended to use the --network=host parameter. This approach allows the Docker container to share the host's networking stack, which eliminates the overhead of port mapping and reduces resource usage. As a result, this method enhances performance and stability, making it more suitable for applications like FreeSWITCH that require efficient network handling.

docker run -d \
    --name freeswitch \
    --restart unless-stopped \
    --network=host \
    -e SIP_PORT=59687 \
    -e RTP_START_PORT=45000 \
    -e RTP_END_PORT=45050 \
    -e ALLOWED_SIP_IPS="127.0.0.1" \
    -v /path/to/host/dir:/path/to/container/dir
    bngnext/freeswitch:latest

Explanation of the command:

  • -d: The container runs in detached mode, meaning it operates in the background and frees up your terminal for other commands.
  • --name freeswitch: Assigns the name freeswitch to the container, making it easier to reference in future commands (e.g., docker stop freeswitch).
  • --restart unless-stopped: Ensures that the container automatically restarts if it crashes or if the system reboots, unless manually stopped by the user, providing more resilience for the service.
  • --network=host: This option configures the container to use the host's networking stack. This means the container will share the host's IP address and network interfaces, allowing for direct access to the host's network resources without port mapping overhead.
  • -e SIP_PORT=5060: Sets the environment variable SIP_PORT to 5060, allowing for dynamic SIP port configuration.
  • -e RTP_START_PORT=16384: Sets the environment variable RTP_START_PORT to 16384, defining the start of the RTP port range.
  • -e RTP_END_PORT=32768: Sets the environment variable RTP_END_PORT to 32768, defining the end of the RTP port range.
  • -e ALLOWED_SIP_IPS="127.0.0.1,192.168.1.1": This sets the ALLOWED_SIP_IPS environment variable with both IP addresses separated by a comma. Make sure to wrap the entire value in double quotes to ensure it is treated as a single string.
  • -v /path/to/host/dir:/path/to/container/dir: This flag mounts a directory from the host machine to a corresponding directory inside the container. It ensures that FreeSWITCH has access to necessary resources, such as audio files. This is especially important for functionality like Text-to-Speech (TTS), as FreeSWITCH requires access to these files for playback. Without this volume mount, FreeSWITCH will be unable to access or play the audio files stored outside its own filesystem. It's essential that both the host and container paths (/path/to/host/dir and /path/to/container/dir) are specified correctly and are identical to ensure proper file sharing between the two environments.
    Disclaimer

    Both paths /path/to/host/dir and /path/to/container/dir should be exactly identical, means container path should be identical to the host path and rest docker will manage. If paths are different then freeSWITCH will not be able to access the TTS/recording directories and files resulting in failures.

  • bngnext/freeswitch:latest: Specifies the FreeSWITCH Docker image with the version tag x.y.z or use latest to use latest version image (Recommended). Replace x.y.z with the specific version you intend to use (e.g., bngnext/freeswitch:1.0.0).
Note

It is essential that the environment variable values for SIP_PORT, RTP_START_PORT, ALLOWED_SIP_IPS and RTP_END_PORT match the corresponding mapped ports allowed publically on the system. These environment variables are mandatory for the proper configuration of FreeSWITCH. If they are not set or do not match the mapped ports, the container will fail to start.

Disclaimer

You should customize the port mappings to suit your specific environment and firewall configurations. Make sure:

  • SIP Signaling Ports: Ensure that the configured SIP signaling ports (e.g., 5060 or any alternative port) align with your communication setup. This ensures proper signaling for voice and video calls.
  • Event Socket Layer (ESL) Port: Verify that the ESL port (e.g., 8021 or any configured alternative) is accessible for applications that intend to interact with FreeSWITCH using the Event Socket Protocol, enabling seamless integration and communication.
  • RTP Port Range: Ensure that the designated RTP port range (e.g., 16384-32768 or any configured range) is open and properly configured to facilitate audio and video communication in VoIP services. Adjust this range based on your specific requirements and network settings to optimize performance and security.

Additionally, you may need to update your firewall rules to allow traffic on these ports.

Customizing FreeSWITCH Configuration​

The config/ directory contains several configuration files with default options. You can modify these to suit your specific requirements.

Key Configuration Files:

  • acl.conf.xml: Modify IP access control settings.
  • public.xml: Manage public context for FreeSWITCH.
  • verto.conf.xml: Configure WebRTC support.
  • modules.conf.xml: Enable or disable specific FreeSWITCH modules.
  • event_socket.conf.xml: Set up and configure the event socket.

Accessing the FreeSWITCH Container​

To access the FreeSWITCH container’s shell and perform administrative tasks, run the following command:

docker exec -it freeswitch /bin/bash

Command Breakdown:​

  • docker exec: This command allows you to run a command inside a running Docker container.
  • -it: This option is a combination of two flags:
    • -i: Keeps the STDIN (standard input) open, which allows you to interact with the container.
    • -t: Allocates a pseudo-TTY, which gives you an interactive terminal session inside the container.
  • freeswitch: This is the name of the running container in which you want to execute the command. In this case, it’s the FreeSWITCH container that was named when you ran it (--name freeswitch).
  • /bin/bash: This is the command being executed inside the container. It starts a Bash shell session within the FreeSWITCH container, allowing you to run commands directly in the container’s environment.

What You Can Do:​

Once you’ve accessed the container’s shell, you can perform various administrative tasks, such as:

  • Viewing logs to troubleshoot or monitor the system.
  • Managing FreeSWITCH processes (e.g., restarting or checking the status of the service).
  • Editing or inspecting configuration files.
  • Installing additional tools or making adjustments within the container.

Important Notes:​

  • Exit the shell: Once your tasks are complete, you can exit the container shell by typing exit or pressing Ctrl+D. The container will continue running in the background even after you exit the shell.
  • Logging: It’s a good idea to monitor the logs inside the container for any potential issues. You can access logs within the container by navigating to the appropriate log directories.
Disclaimer

Ensure you have the necessary permissions to interact with and modify the container’s environment. Unauthorized changes can disrupt the FreeSWITCH service or other running processes within the container.

Conclusion​

Congratulations! You have successfully containerized FreeSWITCH using Docker in an Ubuntu environment. With FreeSWITCH now running in a container, you can easily manage the service, customize its configuration, and start building robust telecommunication solutions.

By leveraging the flexibility of Docker, you can efficiently scale and maintain your FreeSWITCH setup, making it an ideal platform for VoIP, WebRTC, and other real-time communication applications.

For more detailed guidance on configuring and optimizing your FreeSWITCH instance, be sure to explore the FreeSWITCH documentation. This resource offers in-depth information on modules, configuration files, and advanced telephony features to help you fine-tune your deployment.