Customer Onboarding Runbook — FreeSWITCH

This runbook walks an operator through onboarding a new customer on the FreeSWITCH provider — from an empty host to a smoke-tested phone system. It is an ordered checklist with pointers: the detailed reference for every screen, field and failure mode lives in FreeSWITCH Integration Setup and Firewall Service; this page only fixes the order of the steps and the values that must be captured along the way.

Onboarding at a glance

1. Collect prerequisites
2. Provision the host
3. DNS, Traefik, Let's Encrypt
4. Compose layout and secrets
5. Odoo: modules and FreeSWITCH settings
6. Firewall service
7. Trunk gateway, DIDs, routes, caller IDs
8. Users and endpoints
9. Smoke tests
10. Handover record

1. Prerequisites

Collect before starting; every item below blocks a later step.

Ports that must be reachable on the FreeSWITCH host (open in the cloud security group / host firewall):

Internal-only, never expose: 8080/tcp (mod_xml_rpc plain HTTP, behind Traefik), 8081/tcp (firewall service HTTP, behind Traefik), 8021/tcp (FreeSWITCH ESL, localhost only).

2. Provision the host

1. Install Docker and the compose plugin (official instructions).

2. Copy the deploy folder from the addons repo to the host, e.g.:

   scp -r connect_freeswitch/deploy/ root@fs.customer.example.com:/opt/freeswitch

   The folder carries the FreeSWITCH image build sources, the Traefik dynamic config (traefik/) and the .env / compose templates that the next steps customize. The production container uses the bootstrap configuration baked into oduist/freeswitch; the host copy under freeswitch/conf/ is not mounted at runtime. Keep /opt/freeswitch under configuration management or note it in the handover record — it is the only state on the host besides Docker volumes.

3. DNS, Traefik, Let's Encrypt

1. Create an A record for the FQDN pointing at the host's public IP and wait until it resolves publicly — ACME validation fails otherwise.

2. Edit /opt/freeswitch/.env:

   COMPOSE_PROJECT_NAME=fs
   # Customer's Odoo, used by FreeSWITCH for xml_curl/CDR/recording callbacks
   ODOO_URL=https://odoo.customer.example.com
   FS_DOMAIN=fs.customer.example.com
   ACME_EMAIL=ops@example.com
   # Keep the staging CA enabled until the whole stack comes up cleanly,
   # then comment it out and remove the acme volume to get the real cert:
   ACME_CASERVER=https://acme-staging-v02.api.letsencrypt.org/directory

3. Traefik requests the certificate automatically on first start (next step); the FreeSWITCH entrypoint extracts the same certificate from the shared ACME volume for Verto WSS and DTLS-SRTP. Details: TLS/SSL Certificates.

4. Compose layout

The shipped connect_freeswitch/deploy/docker-compose.yml is the production FreeSWITCH host stack. It starts only traefik, fs and firewall, with oduist/freeswitch:2.1.2 and oduist/freeswitch-firewall:2.1.1. The all-in-one local stack that also starts Odoo + Postgres lives in docker-compose.full.yml.

The FreeSWITCH image owns its static bootstrap configuration. Do not mount ./freeswitch/conf over /usr/local/freeswitch/etc/freeswitch: Odoo provides the dynamic users, gateways, ACLs and dialplan over mod_xml_curl, while the image bootstrap is what loads those modules and keeps ESL bound to loopback.

Generate only the host-local secrets here and record them in the vault. Odoo generates FS_WEBHOOK_TOKEN and FIREWALL_AGENT_TOKEN when connect_freeswitch is installed; retrieve them in step 5 instead of creating parallel values:

# ESL password (fs and firewall containers must match)
openssl rand -base64 24 | tr '+/' '-_'

Append them to /opt/freeswitch/.env:

FS_ESL_PASSWORD=<esl password>
FIREWALL_DASHBOARD_PASSWORD=<pick a strong password>

The copied docker-compose.yml and traefik/dynamic.yml already include the firewall service and the /firewall Traefik route. Traefik runs on the host network and proxies to the loopback-only listeners 127.0.0.1:8080 (FreeSWITCH XML-RPC) and 127.0.0.1:8081 (firewall).

Do not start fs or firewall yet. Their required tokens are generated by Odoo in the next step. Starting with made-up or empty values produces expected 401 errors and adds no useful bootstrap capability.

5. Odoo: modules and settings

1. Install connect and connect_freeswitch in the customer's Odoo — see Installation.

2. Open Connect → FreeSWITCH → Configuration → Settings and fill in (field-by-field reference: Odoo Configuration):

   Field	Value
   WebSocket URL	wss://fs.customer.example.com:48082
   Domain	fs.customer.example.com
   XML-RPC Host	fs.customer.example.com

   XML-RPC always uses verified HTTPS on port 443. The username is fixed to odoo; Odoo generates and stores the password internally. Changing the host rotates that password.

3. Retrieve the automatically generated protected settings with Oduflow's run_odoo_shell (or an equivalent administrative Odoo shell for a manual deployment):

   settings = env["connect.settings"].sudo()
   print("FS_WEBHOOK_TOKEN=" + (settings.get_param("freeswitch_webhook_token") or ""))
   print("FIREWALL_AGENT_TOKEN=" + (settings.get_param("firewall_service_token") or ""))

   Append those two values to /opt/freeswitch/.env. Do not commit them or repeat them in tickets and deployment summaries. Oduflow service updates must preserve the complete existing environment because env_vars is a full replacement. 4. Start the stack and verify ESL:

   cd /opt/freeswitch
   docker compose up -d
   docker exec freeswitch sh -c 'fs_cli -p "$FS_ESL_PASSWORD" -x status'

4. Click CHECK STATUS on the settings form — Server Status must show UP — <version>. Anything else: follow the decision table in Checking server status.

   Restart FreeSWITCH after every later XML-RPC host change so mod_xml_rpc loads the rotated password.

6. Firewall

Full reference: Firewall Service. Onboarding order:

1. In Connect → FreeSWITCH → Configuration → Settings, page Firewall:
   • toggle Firewall Enabled on;
   • set Firewall Service URL to https://fs.customer.example.com (Odoo appends /firewall/sync; Traefik routes the /firewall prefix to the service — the default http://host.docker.internal:8081 only works when Odoo runs on the same host);
   • leave the generated Firewall Service Token unchanged; the value already deployed as AGENT_TOKEN is the same protected Odoo setting;
   • keep the default port lists (5060,5061,5080,5081) and timeouts.

2. Connect → FreeSWITCH → Firewall → Whitelist: add the trunk provider's signaling IPs and the customer's office NAT exits. Saving syncs to the service immediately.

   Whitelist vs. gateway Inbound IPs

   The firewall whitelist only keeps an IP from being auto-banned at the kernel level. Accepting unauthenticated INVITEs from an IP-auth trunk is separate — that is the Inbound IPs field on the SIP Gateway record (sofia ACL).

3. Connect → FreeSWITCH → Firewall → Agent Status must show the agent online within one heartbeat interval (60 s). If not: firewall troubleshooting.

7. Trunk gateway, DIDs, routes, caller IDs

All under the Connect → FreeSWITCH menu; saving a gateway restarts the sofia external profile automatically — no manual reload step.

1. Configuration → SIP Gateways — create the trunk from the provider's credentials (fields: SIP Gateways). For IP-auth trunks fill Inbound IPs. Verify registration:

   docker exec -it freeswitch fs_cli -x "sofia status gateway <name>"
   # State must be REGED (for register=true trunks)

2. Numbers — one record per DID, each routed to a user, callflow or FIFO. A leading + is matched tolerantly; digits beyond that must match what the trunk actually delivers (see DID format mismatch).

3. Configuration → Outgoing Routes — at minimum one catch-all route (pattern ^\+\d{7,}$) through the trunk gateway; add national/emergency patterns per customer dial habits (examples).
4. Outgoing Caller IDs — create the customer's DIDs as caller IDs and flag one as Default; optionally assign per-user numbers on the Connect User form. Resolution order: Outbound Caller ID.

8. Users and endpoints

1. Create PBX users under Connect → Users — extension, Odoo user link, groups (PBX Users). With several provider modules co-installed, set each user's Originate Provider to FreeSWITCH so click-to-call uses this host.
2. For every user create at least one endpoint under Connect → FreeSWITCH → Endpoints — the SIP/Verto password is auto-generated; copy it from the form for desk phones (Endpoints).

9. Smoke tests

Run all of these before declaring the customer live. Each line has a detailed fallback reference.

10. Handover record

Record these in the customer's operations vault/wiki when the smoke tests pass — the next operator (and the next onboarding) starts from this table:

Routine operations after handover (trunk password rotation, unbanning IPs, monitoring) are covered by the Operations Runbook section and Firewall daily operations.