search

ugoviti / izpbx

izPBX is a Turnkey Cloud Native Telephony System powered by Asterisk Engine and FreePBX Management GUI
GNU General Public License v3.0
179 stars 74 forks source link

readme

Name

izPBX Cloud Native VoIP Telephony System

Description

izPBX is a Turnkey Cloud Native VoIP Telephony System powered by Asterisk Engine and FreePBX Management GUI

Supported tags

Production Branch:

Development Branches:

Version notes:

Tags format: Z.Y.X-[BUILD]

where:

Look into project Tags page to discover the latest versions

Dockerfile

Targets of this project

Cloud and On-Premise, Fast, Automatic and Repeatable deploy of VoIP PBX systems

Features

Screenshots

izPBX Dashboard (FreePBX):

izpbx-dashboard

izPBX Operator Panel (FOP2):

izpbx-izpbx-operator-panel

izPBX Monitoring Dashboard (Zabbix):

izpbx-zabbix-dashboard

izPBX CLI (Asterisk):

izpbx-console

Deploy izPBX

Using docker compose is the suggested method:

Note: by default, to correctly handle SIP NAT and SIP-RTP UDP traffic, the izpbx container will use the network_mode: host, so the izpbx container will be exposed directly to the outside network without using docker internal network range (network_mode: host will prevent multiple izpbx containers from running inside the same host).
Modify compose.yml and comment #network_mode: host if you want run multiple izpbx containers in the same host (not production tested. There will be problems with RTP traffic). Another available option is to disable network_mode: host and use macvlan network mode used for running izPBX into multi-tenant mode.

Customizing compose.yml

If you need to customize the default compose.yml, don't edit it, but create an override file:

and specify the options you want to override, for example:

version: '3'

services:
  db:
    image: docker.io/mariadb:10.11.4
  izpbx:
    image: docker.io/izdock/izpbx-asterisk:20.16.7

and start the deploy with the same command docker compose up -d

Alternative deploy method via 'docker run' command (not suggested)

If you want test izPBX without using docker compose command, you can use the following docker commands:

  1. Start MySQL:
    docker run --rm -ti -v ./data/db:/var/lib/mysql -e MYSQL_ROOT_PASSWORD=CHANGEM3 -e MYSQL_PASSWORD=CHANGEM3 --name izpbx-db mariadb:10.4

  2. Start izPBX:
    docker run --rm -ti --network=host --privileged --cap-add=NET_ADMIN -v ./data/izpbx:/data -e MYSQL_ROOT_PASSWORD=CHANGEM3 -e MYSQL_PASSWORD=CHANGEM3 -e MYSQL_SERVER=127.0.0.1 -e MYSQL_DATABASE=asterisk -e MYSQL_USER=asterisk -e APP_DATA=/data --name izpbx izpbx-asterisk:latest

Upgrade izPBX

  1. Upgrade the version of izpbx by downloading a new tgz release, or changing image tag into compose.yml file (from git releases page, verify if upstream docker compose was updated), or if you cloned directly from GIT, use the following commands as quick method:

    cd /opt/izpbx
git checkout main
git pull
git fetch --tags --all -f
git checkout tags/$(git tag | sort --version-sort | tail -1)

  2. Upgrade the izpbx deploy with:
    (NB. First verify if compose.yml and default.env was updated a make the same changes in your .env file)

    docker compose pull
docker compose up -d

  3. If the mariadb database version was changed, rememeber to update tables schema with command
    source .env ; docker exec -it izpbx-db mysql_upgrade -u root -p$MYSQL_ROOT_PASSWORD

  4. Open FreePBX Web URL and verify if exist any modules updates from FreePBX Menu: Admin --> Modules Admin --> Check Online --> Upgade all --> Process

That's all

Upgrade path to a major FreePBX release

FreePBX will be installed into persistent data dir on initial deploy only (when no installations already exist).

Successive container updates on the same release (example from 18.15.1 to 18.15.2) will not upgrade the FreePBX Framework (only Asterisk engine will be updated).

If you want upgrade FreePBX Framework/Core to a major release (example from 15 to 16), you have 2 options:

  1. Automatic upgrade using izPBX container release (example, switching from 18.15.x to 18.16.x release)
  2. Manual upgrade using FreePBX Upgrader tool

method 1: Automatic upgrade using izPBX container release (suggested)

method 2: Manual upgrade using FreePBX Upgrader tool

Advanced Production Configuration Examples

Multi-Tenant VoIP PBX with dedicated Databases

Objective

Configuration

Create a directory where you want deploy izpbx data and create compose.yml and .env files:

Example:

mkdir yourgreatpbx
cd yourgreatpbx
vim compose.yml
vim .env

NOTE:

version: '3'

networks:
  izpbx-0-ext:
    driver: macvlan
    driver_opts:
      parent: eth0
    ipam:
      config:
      - subnet: 10.1.1.0/24
        #ip_range: "10.1.1.221/30"
        #gateway: 10.1.1.1
  izpbx-1:
    driver: bridge

services:
  db:
    image: mariadb:10.5.9
    ## WARNING: if you upgrade image tag enter the container and run mysql_upgrade:
    ## source .env ; docker exec -it izpbx-db mysql_upgrade -u root -p$MYSQL_ROOT_PASSWORD
    command: --sql-mode=ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION
    restart: unless-stopped
    env_file:
    - .env
    environment:
    - MYSQL_ROOT_PASSWORD
    - MYSQL_DATABASE
    - MYSQL_USER
    - MYSQL_PASSWORD
    ## database configurations 
    volumes:
    - ./data/db:/var/lib/mysql
    networks:
      izpbx-1:

  izpbx:
    #hostname: ${APP_FQDN}
    image: izdock/izpbx-asterisk:18.15.11
    restart: unless-stopped
    depends_on:
    - db
    env_file:
    - .env
    volumes:
    - ./data/izpbx:/data
    cap_add:
    - SYS_ADMIN
    - NET_ADMIN
    privileged: true
    networks:
      izpbx-0-ext:
        ipv4_address: 10.1.1.221
      izpbx-1:

Repeat the procedure for every izPBX you want deploy. Remember to create a dedicated directory for every izpbx deploy.

Deploy

Enter in every directory containig configuration files and run:

Multi-Tenant VoIP PBX with shared global Database and single compose.yml file

Objective

Configuration

Create a directory where you want deploy all izpbx data and create compose.yml and a PBXNAME.env file for every izpbx deploy:

Example:

mkdir izpbx
cd izpbx
vim compose.yml
vim izpbx1.env
vim izpbx2.env
vim izpbx3.env

etc...

NOTE:

version: '3'

networks:
  izpbx-0-ext:
    driver: macvlan
    driver_opts:
      parent: enp0s13f0u3u1u3
    ipam:
      config:
      - subnet: 10.1.1.0/24
  izpbx-1:
    driver: bridge

services:
  db:
    image: mariadb:10.5.9
    ## WARNING: if you upgrade image tag enter the container and run mysql_upgrade:
    ## source .env ; docker exec -it izpbx-db mysql_upgrade -u root -p$MYSQL_ROOT_PASSWORD
    command: --sql-mode=ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION
    restart: unless-stopped
    env_file:
    - db.env
    environment:
    - MYSQL_ROOT_PASSWORD
    - MYSQL_DATABASE
    - MYSQL_USER
    - MYSQL_PASSWORD
    ## database configurations 
    volumes:
    - ./data/db:/var/lib/mysql
    networks:
      izpbx-1:

  izpbx1:
    #hostname: ${APP_FQDN}
    image: izdock/izpbx-asterisk:18.15.11
    restart: unless-stopped
    depends_on:
    - db
    env_file:
    - izpbx1.env
    volumes:
    - ./data/izpbx1:/data
    cap_add:
    - NET_ADMIN
    privileged: true
    networks:
      izpbx-0-ext:
        ipv4_address: 10.1.1.221
      izpbx-1:

  izpbx2:
    #hostname: ${APP_FQDN}
    image: izdock/izpbx-asterisk:18.15.11
    restart: unless-stopped
    depends_on:
    - db
    env_file:
    - izpbx2.env
    volumes:
    - ./data/izpbx2:/data
    cap_add:
    - NET_ADMIN
    privileged: true
    networks:
      izpbx-0-ext:
        ipv4_address: 10.1.1.222
      izpbx-1:

  izpbx3:
    #hostname: ${APP_FQDN}
    image: izdock/izpbx-asterisk:18.15.11
    restart: unless-stopped
    depends_on:
    - db
    env_file:
    - izpbx3.env
    volumes:
    - ./data/izpbx3:/data
    cap_add:
    - NET_ADMIN
    privileged: true
    networks:
      izpbx-0-ext:
        ipv4_address: 10.1.1.223
      izpbx-1:

Deploy

Enter the directory containig configuration files and run:

Services Management

Command to restart whole izPBX deploy

docker compose restart izpbx

Command to restart izPBX container only

docker restart izpbx

Command to restart DB container only

docker restart izpbx-db

If you want restart single services inside izpbx container

Enter the container:
docker exec -it izpbx bash

Restart izpbx service (Asterisk Engine):
supervisorctl restart izpbx

To restart others available services use supervisorctl restart SERVICE

Available services:

Tested systems and host compatibility

Tested Docker Runtime:

Tested Host Operating Systems:

Environment default variables

Consult the default.env file:

Zabbix Agent Configuration

Consult official repository page for installation and configuration of Asterisk Zabbix Template in you Zabbix Server:

FreePBX Configuration Best Practices

Configuring VoIP XML PhoneBook Lookup

Define every PhoneBooks you want to use

For Yealink / Fanvil phones you can use a single Phonebook Menu: http://IZPBX_ADDRESS/pb/yealink/menu

FAQ / Troubleshooting

TODO / Future Development

BUGS and Limits of this project

Quick reference