### Docker Compose: Build and Start SIP Server

Source: https://context7.com/open-condo-software/intercom-sip-server/llms.txt

This snippet demonstrates how to build and start the multi-container Docker deployment for the SIP server infrastructure, including the FreeSWITCH server, ESL handler, user generator, and STUN server. It also shows how to check the status of the running services.

```bash
# Build the containers
sudo docker compose build

# Start all services
sudo docker compose up -d

# Check service health
docker compose ps
```

--------------------------------

### XML: Generated Apartment User Configuration

Source: https://context7.com/open-condo-software/intercom-sip-server/llms.txt

An example of a FreeSWITCH user XML configuration generated for an apartment user. It defines the user ID, password, and sets the user context to 'rooms-main'. It also includes variables for codec preferences and other specific settings.

```xml
<user id="apt-205">
  <params>
    <param name="password" value="apartpass456"/>
  </params>
  <variables>
    <variable name="absolute_codec_string" value="OPUS,G722,PCMU,PCMA,VP8"/>
    <variable name="user_context" value="rooms-main"/>
```

--------------------------------

### Environment Configuration: .env File

Source: https://context7.com/open-condo-software/intercom-sip-server/llms.txt

This section details the environment variables used to configure the SIP server, including FreeSWITCH settings, push notification integration, log management, S3 storage access for user provisioning, and Telegram notifications. The example shows how to create and populate the .env file from a template.

```bash
# Create .env file from template
cp .env.example .env

# Edit configuration
cat > .env << 'EOF'
# FreeSWITCH Core Configuration
SOCKET_PASSWORD=reallySecr3tP@ssw0rd    # ESL socket password
SIP_PASSWORD=reallySecr3tP@ssw0rd       # Default SIP account password
SIP_IP=203.0.113.50                     # Public IP for SDP/RTP

# Push Notification Integration
PUSH_URL=https://api.example.com/push
CANCEL_URL=https://api.example.com/cancel-push
PUSH_API_KEY=your_api_key_here
CALL_TIMEOUT=180                        # Call timeout in seconds

# Log Management
ROLLOVER=1048576000                     # Log file size before rotation (1GB)
MAXIMUM_ROTATE=10                       # Number of log files to keep

# S3 Configuration (for auto_run_generate_users.py)
BUCKET_NAME=intercom-users
REGION=us-east-1
IAM_USER_ACCESS_KEY=AKIAIOSFODNN7EXAMPLE
IAM_USER_SECRET_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
OBS_CLOUD_URL=https://obs.example.com
USERS_DIR=input-users

# Telegram Notifications
TG_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
TG_NOTIFICATIONS_CONFIG=[{"chatId": "-1001234567890", "logLevel": "error"}]
SERVER_NAME=prod-sip-01
EOF
```

--------------------------------

### XML: Generated Intercom User Configuration

Source: https://context7.com/open-condo-software/intercom-sip-server/llms.txt

An example of a FreeSWITCH user XML configuration generated for an intercom user. It includes the user ID, password, and specifies the user context as 'intercoms-main' and the AI type as 'intercom'.

```xml
<user id="intercom-101">
  <params>
    <param name="password" value="secretpass123"/>
  </params>
  <variables>
    <variable name="user_context" value="intercoms-main"/>
    <variable name="X-Doma-AI-Type" value="intercom"/>
  </variables>
</user>
```

--------------------------------

### Build Custom FreeSWITCH Docker Image

Source: https://context7.com/open-condo-software/intercom-sip-server/llms.txt

Compiles a custom FreeSWITCH Docker image from source on Ubuntu 20.04, enabling the mod_callcenter module. It installs dependencies, builds FreeSWITCH and its dependencies (libks, Sofia-SIP, SpanDSP), and copies configuration files. The image is tagged as intercom-sip-server:1.0.

```dockerfile
# dockerfile
FROM ubuntu:20.04

# Install dependencies
RUN apt-get update && apt-get install -yq \
    build-essential git cmake autoconf libtool \
    libssl-dev libsqlite3-dev libcurl4-openssl-dev \
    libpcre3-dev libspeexdsp-dev libldns-dev libedit-dev \
    libopus-dev libsndfile-dev uuid-dev

# Build libks (FreeSWITCH dependency)
RUN git clone https://github.com/signalwire/libks.git -bv2.0.4 && \
    cd libks && cmake . && make && make install

# Build Sofia-SIP (SIP stack)
RUN git clone https://github.com/freeswitch/sofia-sip.git -bv1.13.17 && \
    cd sofia-sip && ./bootstrap.sh && ./configure && make && make install

# Build SpanDSP (DTMF/fax support)
RUN git clone https://github.com/freeswitch/spandsp.git && \
    cd spandsp && ./bootstrap.sh && ./configure && make && make install

# Build FreeSWITCH with mod_callcenter
RUN git clone https://github.com/signalwire/freeswitch.git -bv1.10.11 && \
    cd freeswitch && ./bootstrap.sh -j && \
    sed -i -E '/mod_(signalwire|pgsql)/d' modules.conf && \
    echo "applications/mod_callcenter" >> modules.conf && \
    ./configure && make -j && make install

# Copy configurations
COPY config/conf /usr/local/freeswitch/conf
COPY entrypoint.sh /usr/local/bin/entrypoint.sh

ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]
```

--------------------------------

### User CSV File Format for Provisioning

Source: https://context7.com/open-condo-software/intercom-sip-server/llms.txt

Defines the structure of CSV files used for automatic user provisioning in the SIP server. The format includes fields for apartment/unit number, SIP extension, UDP extension, and password. The example illustrates how to define intercom and apartment users.

```csv
kvartira;extension;extension_udp;password
x;intercom-building-a;intercom-building-a-udp;9YHxK8mQ2nP3vR7s
101;apt-101;apt-101-udp;aB5dE8fG1hJ4kL6m
102;apt-102;apt-102-udp;nP9qR2sT5uV8wX1y
103;apt-103;apt-103-udp;zA3bC6dE9fG2hJ5k
```

--------------------------------

### Integrate with Push Notification API

Source: https://context7.com/open-condo-software/intercom-sip-server/llms.txt

Demonstrates how to use `curl` to send POST requests to external API endpoints for managing mobile push notifications. It includes examples for sending a notification when a call arrives and canceling it when the call is answered or ended, using an authorization token.

```bash
# Send push notification (called when call arrives)
curl -X POST https://api.example.com/push/apt-205 \
  -H "Authorization: Bearer ${PUSH_API_KEY}"

# Response: 200 OK
# Push notification delivered to apt-205's mobile devices

# Cancel push notification (called when call answered/ended)
curl -X POST https://api.example.com/cancel-push/apt-205 \
  -H "Authorization: Bearer ${PUSH_API_KEY}"

# Response: 200 OK
```

--------------------------------

### Python: Automatic User Generation Logic

Source: https://context7.com/open-condo-software/intercom-sip-server/llms.txt

This Python snippet describes the automatic user provisioning process. CSV files placed in the 'input-users/' directory are processed by 'generate_users.py'. The script transliterates filenames, creates intercom and apartment users with specific contexts, generates FreeSWITCH XML configurations, and saves them in the 'output-users/' directory, triggering an automatic reload of FreeSWITCH configurations.

```python
# Place CSV files in input-users/ directory
# File: input-users/Building_A.csv (Cyrillic names supported)

import os

# Files are automatically processed by generate_users.py
# - Filename is transliterated: "Здание А.csv" -> "Zdanie_A_.xml"
# - kvartira="x" creates intercom user with context "intercoms-main"
# - Other values create apartment user with context "rooms-main"
# - Generated XML files placed in output-users/ directory
# - FreeSWITCH automatically reloads via fs_cli reloadxml
```

--------------------------------

### Build Docker Compose Project

Source: https://github.com/open-condo-software/intercom-sip-server/blob/main/README.md

This command builds the Docker Compose project for the intercom-prod-sip-server. It requires sudo privileges to execute.

```sh
sudo docker compose build
```

--------------------------------

### Automated S3 User Provisioning with Python

Source: https://context7.com/open-condo-software/intercom-sip-server/llms.txt

This Python script automates user provisioning by fetching CSV files from an S3 bucket, creating users, and sending Telegram notifications. It includes logic to prevent multiple instances from running simultaneously using a temporary lock file and relies on the boto3 library for S3 interactions.

```python
# auto_run_generate_users.py runs continuously
# Monitors S3 bucket for new CSV files

from auto_run_generate_users import main, Settings
import os

# Workflow:
# 1. Check if script is already running via temp file
# 2. Connect to S3 using boto3 with provided credentials
# 3. List objects in bucket
# 4. Download all CSV files
# 5. Write files to input-users/ directory
# 6. Delete files from S3 bucket
# 7. Run generate_users() function
# 8. Send Telegram notification on success/failure
# 9. Remove temp lock file

# Run manually:
if __name__ == "__main__":
    temp_file = 'generate_users_is_running.temp'
    if not os.path.exists(temp_file):
        with open(temp_file, 'w') as f:
            f.write("running")
        main(temp_file)
    else:
        print("Script already running")
```

--------------------------------

### Bash: Manual User Generation Script Execution

Source: https://context7.com/open-condo-software/intercom-sip-server/llms.txt

Provides commands to manually trigger the user generation script, which creates FreeSWITCH user XML configurations from CSV files. It includes options for running the script directly within a Docker container or using a shell script wrapper that also sets up callcenter queues and reloads FreeSWITCH configurations.

```bash
# Run user generation manually
docker compose exec sip-server python3 /generate_users.py

# Or use the shell script version with callcenter queue setup
./generate_users.sh
```

--------------------------------

### Manage Callcenter Queues via FreeSWITCH CLI

Source: https://context7.com/open-condo-software/intercom-sip-server/llms.txt

Provides commands to interact with FreeSWITCH callcenter queue configurations using the `fs_cli` tool. Includes reloading, unloading, and listing queue information, requiring the socket password for authentication.

```bash
# Reload queue configuration via CLI
docker compose exec -Td sip-server \
  /usr/local/freeswitch/bin/fs_cli -rRS \
  --password ${SOCKET_PASSWORD} \
  -x "callcenter_config queue load apt-205@default"

# Unload queue
docker compose exec -Td sip-server \
  /usr/local/freeswitch/bin/fs_cli -rRS \
  --password ${SOCKET_PASSWORD} \
  -x "callcenter_config queue unload apt-205@default"

# Check queue status
 freeswitch> callcenter_config queue list
 freeswitch> callcenter_config queue list members apt-205@default
```

--------------------------------

### Configure Callcenter Queues in FreeSWITCH

Source: https://context7.com/open-condo-software/intercom-sip-server/llms.txt

Defines callcenter queues with a 'ring-all' strategy for apartment users, including settings for music on hold, maximum wait times, and discarding abandoned calls. The configuration is intended to be loaded into FreeSWITCH via its command-line interface.

```xml
<!-- Generated in volume-configs/callcenter.conf.xml -->
<configuration name="callcenter.conf" description="CallCenter">
  <settings>
    <param name="truncate-agents-on-load" value="true"/>
    <param name="truncate-tiers-on-load" value="true"/>
  </settings>

  <queues>
    <queue name="apt-205@default">
      <param name="strategy" value="ring-all"/>
      <param name="moh-sound" value="${hold_music}"/>
      <param name="max-wait-time" value="120"/>
      <param name="max-wait-time-with-no-agent" value="0"/>
      <param name="discard-abandoned-after" value="60"/>
    </queue>
  </queues>

  <agents></agents>
  <tiers></tiers>
</configuration>
```

--------------------------------

### Monitor FreeSWITCH Logs and Container Output

Source: https://context7.com/open-condo-software/intercom-sip-server/llms.txt

Details how to view live logs from FreeSWITCH and related services using `docker compose logs`. It also shows how to inspect log files within the FreeSWITCH container and monitor a specific log file (`auto_run_generate_users_script.log`) using `tail`.

```bash
# View live logs
docker compose logs -f sip-server
docker compose logs -f sip-esl
docker compose logs -f generate-users

# Log files inside container
docker compose exec sip-server ls -lh /usr/local/freeswitch/log/
# freeswitch.log - main log (rotated at ROLLOVER size)
# Maximum MAXIMUM_ROTATE files kept

# Check auto_run_generate_users.py log
cat auto_run_generate_users_script.log

# Monitor with tail
tail -f auto_run_generate_users_script.log

# Log levels configured in entrypoint.sh:
# ROLLOVER=1048576000      # 1GB per file
# MAXIMUM_ROTATE=10        # Keep 10 files (10GB total)
```

--------------------------------

### FreeSWITCH CLI Access and Commands

Source: https://context7.com/open-condo-software/intercom-sip-server/llms.txt

This section provides essential bash commands for accessing and interacting with the FreeSWITCH console, typically within a Docker container. It covers common commands for checking status, managing registrations and calls, reloading configurations, and monitoring events, which are crucial for debugging and system administration.

```bash
# Connect to fs_cli inside container
sudo docker compose exec -it sip-server \
  /usr/local/freeswitch/bin/fs_cli -rRS --password ${SOCKET_PASSWORD}

# Common commands:
freeswitch> sofia status
freeswitch> sofia status profile internal
freeswitch> show registrations
freeswitch> show channels
freeswitch> show calls
freeswitch> uuid_kill <uuid>
freeswitch> reloadxml
freeswitch> reload mod_sofia

# Check specific user registration
freeswitch> sofia_contact apt-205
# Output: sofia/internal/apt-205@192.168.1.100:5060,sofia/internal/apt-205@10.0.0.50:5060

# Originate test call
freeswitch> originate user/apt-205 &echo

# Monitor events
freeswitch> /log 7
freeswitch> /events plain all
```

--------------------------------

### Docker Compose Deployment and Logging

Source: https://context7.com/open-condo-software/intercom-sip-server/llms.txt

Provides bash commands for deploying the services using Docker Compose and for monitoring their logs. This is essential for running and debugging the application in a containerized environment, ensuring services are up and accessible.

```bash
# Deploy as scheduled job
docker compose up -d

# Check logs
docker compose logs -f generate-users
```

```bash
# Build and run ESL handler
cd on_call
npm install
npm start

# Or via Docker
docker compose up -d sip-esl
```

--------------------------------

### Network Ports and Firewall Configuration Summary

Source: https://context7.com/open-condo-software/intercom-sip-server/llms.txt

This section outlines the essential network ports and firewall configurations required for the SIP server and related services to function correctly. It details standard ports for SIP signaling, RTP media streams, WebSocket communication, and management interfaces, emphasizing the need for these ports to be open and accessible.

```bash
# Required port mappings (host network mode used by default)
# TCP/UDP 5060  - SIP signaling
# TCP 5061      - SIP over TLS
# TCP/UDP 5080  - Alternative SIP port
# TCP 8021      - Event Socket Layer (internal only)
# UDP 24000-25000 - RTP media streams (must be open for audio/video)
# TCP 4443      - WSS (WebSocket Secure) with self-signed cert
# TCP 7443      - WS (WebSocket)
# TCP 7000      - ESL handler API
```

--------------------------------

### Run Custom FreeSWITCH Docker Image

Source: https://context7.com/open-condo-software/intercom-sip-server/llms.txt

Executes the custom FreeSWITCH Docker image (intercom-sip-server:1.0) as a detached container. It configures network mode, sets essential environment variables for socket password, SIP credentials, and SIP IP, and mounts a local directory for user configurations.

```bash
# Build image
docker build -t intercom-sip-server:1.0 .

# Run with environment variables
docker run -d --network host \
  -e SOCKET_PASSWORD=secret123 \
  -e SIP_PASSWORD=sippass456 \
  -e SIP_IP=203.0.113.50 \
  -v ./output-users:/usr/local/freeswitch/conf/directory/autousers \
  intercom-sip-server:1.0
```

--------------------------------

### Configure Firewall Rules for SIP Server

Source: https://context7.com/open-condo-software/intercom-sip-server/llms.txt

Sets up iptables and ufw rules to allow necessary UDP and TCP traffic for the SIP server. It ensures ports 5060 (SIP signaling), 24000-25000 (RTP media), 4443, and 7443 are accessible. Verifies port bindings for FreeSWITCH and node processes.

```bash
sudo iptables -A INPUT -p udp --dport 5060 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 5060 -j ACCEPT
sudo iptables -A INPUT -p udp --dport 24000:25000 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 4443 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 7443 -j ACCEPT

sudo ufw allow 5060/tcp
sudo ufw allow 5060/udp
sudo ufw allow 24000:25000/udp
sudo ufw allow 4443/tcp
sudo ufw allow 7443/tcp

sudo netstat -tulpn | grep freeswitch
sudo netstat -tulpn | grep node
```

--------------------------------

### Connect to SIP Server Socket

Source: https://github.com/open-condo-software/intercom-sip-server/blob/main/README.md

This command allows you to connect to the SIP server's event socket for administrative tasks. It requires the SOCKET_PASSWORD to be set in the environment.

```sh
sudo docker compose exec -it sip-server /usr/local/freeswitch/bin/fs_cli -rRS --password ${SOCKET_PASSWORD}
```

--------------------------------

### ESL Call Handler with Push Notifications (Node.js/TypeScript)

Source: https://context7.com/open-condo-software/intercom-sip-server/llms.txt

A Node.js/TypeScript service that handles incoming calls using the ESL (Event Socket Layer) protocol. It sends mobile push notifications for incoming calls and then rings all registered devices for an apartment extension, bridging the call to the first device that answers. Dependencies include ESL and an external push notification service.

```typescript
// on_call/index.ts
import { FreeSwitchServer } from 'esl';

// Configuration via environment variables
const CALL_TIMEOUT_MS = parseInt(process.env.CALL_TIMEOUT ?? '180') * 1000;

// Call flow:
// 1. Intercom calls apartment extension
// 2. ESL receives CHANNEL_CREATE event
// 3. Send push notification to mobile app
// 4. Ring apartment devices (queries sofia_contact)
// 5. Parallel originate calls to all registered devices
// 6. First answered device bridges to caller
// 7. Cancel push and kill other pending calls

// Start ESL server
const server = new FreeSwitchServer({
    all_events: true,
    my_events: true,
});

server.on('connection', async (call, { data, uuid }) => {
    const fromUser = data.variable_sip_from_user; // e.g., "intercom-101"
    const toUser = data.variable_sip_to_user;     // e.g., "apt-205"

    // Send push notification
    await fetch(`${process.env.PUSH_URL}/${toUser}`, {
        headers: { Authorization: `Bearer ${process.env.PUSH_API_KEY}` }
    });

    // Ring caller side
    await call.command('ring_ready');

    // Query registered devices
    const result = await call.bgapi(`sofia_contact ${toUser}`);
    const contacts = result.body._body.split(',');

    // Originate to all devices in parallel
    for (const contact of contacts) {
        if (contact === 'error/user_not_registered') continue;
        const contactUuid = randomUUID(); // Assuming randomUUID is available
        call.bgapi(`originate ${contact} &park()`);
    }

    // Bridge first answered call
    await call.bgapi(`uuid_bridge ${uuid} ${contactUuid}`); // contactUuid needs to be correctly assigned within the loop

    // Cancel push and kill other calls
    await fetch(`${process.env.CANCEL_URL}/${toUser}`);
});

server.listen({ port: 7000 });

```

--------------------------------

### Manage Push Notification Lifecycle with ESL Handler

Source: https://context7.com/open-condo-software/intercom-sip-server/llms.txt

This TypeScript function utilizes an ESL (Event Socket Library) handler to manage the push notification lifecycle. It sends push notifications for call events and handles cancellation requests, integrating with environment variables for API keys and URLs. The function logs success or error messages based on the response from the push notification service.

```typescript
async function sendPush(fromUser: string, toUser: string, cancel = false) {
    const url = cancel ? process.env.CANCEL_URL : process.env.PUSH_URL;
    const response = await fetch(`${url}/${toUser}`, {
        headers: { Authorization: `Bearer ${process.env.PUSH_API_KEY}` }
    });

    if (response.ok) {
        console.log(`Push ${cancel ? 'canceled' : 'sent'} to ${toUser}`);
    } else {
        console.error(`Push error: ${await response.text()}`);
    }
}

// Usage in call flow:
// 1. Call arrives -> sendPush(from, to, false)
// 2. Call answered -> sendPush(from, to, true)
// 3. Call hangup -> sendPush(from, to, true)
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.