Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Install PortSIP PBX

Upgrading

This guide applies only to fresh installations of the latest PortSIP PBX v22.x.

If you are upgrading from an earlier version, such as v16.x, v22.1.x, or v22.2.x, please follow the appropriate upgrade guide below:

Minimal Hardware Requirements

The following minimum hardware configuration is required for a basic deployment:

  • CPU: 2 cores

  • Memory: 4 GB

  • Disk: 50 GB

With this configuration, the PBX can support:

  • Up to 1,000 online (registered) users

  • Approximately 300–500 simultaneous calls

Supported Operating Systems

PortSIP PBX v22.x supports the following Linux operating systems:

  • Ubuntu: 22.04, 24.04

  • Debian: 12

Preparing the Server for Installation

The following tasks must be completed before installing PortSIP PBX.

System Preparation

  • Ensure the system date and time are correctly synchronized.

  • Performing the installation using sudo is recommended.

  • Assign static IP addresses:

    • If the PBX server is on a LAN, assign a static private IP address.

    • If the PBX server is on a public network, assign both a static public IP and a static private IP.

  • Install all available OS updates and service packs before installing the PBX.

  • Do not install PostgreSQL on the PortSIP PBX server.

  • Disable all power-saving options for the system and network adapters (set the system to High-Performance mode).

  • Do not install TeamViewer, VPN software, or similar tools on the host machine.

  • The PortSIP PBX must not be installed on a server acting as a DNS or DHCP server.

Firewall and Network Requirements

The following ports must be allowed by the firewall and must not be used by other applications.

  • UDP: 5060, 5066, 25000–34999, 45000–65000

  • TCP: 5061, 5063, 5065, 5067, 8882, 8883, 8887, 8888, 10443

❗Important If the PBX is deployed on a cloud platform such as AWS, Azure, or other providers, you must also open these ports in the cloud platform’s firewall or security group.

Installing PortSIP PBX

❗ Important Follow every step in this guide in order. Do not skip any steps unless the guide explicitly says you can.

Step 1: Download Installation Scripts

Run the following commands to download the installation scripts and initialize the environment:

Step 2: Set Up the Docker Environment

All commands must be executed in the /opt/portsip directory.

Run the following command to install the Docker and Docker-Compose environment:

If you are prompted with:

Enter Y and press Enter to continue.

Step 3: Create and Run the PBX Docker Instance

The following command creates and runs the PortSIP PBX Docker instance on a server with the public IP address 66.175.221.120. If the PBX is deployed on a LAN without a public IP, replace 66.175.221.120 with the PBX server’s private LAN IP address.

Command Parameters Explained

  • -p: Specifies the directory for storing PBX data.

  • -a: Specifies the PBX server IP address (public or private, depending on deployment).

  • -i: Specifies the PBX Docker image version.

  • -f : (Optional) Specifies a separate directory for storing call recording files.

The -f parameter is optional and allows you to specify a separate path for storing recording files. If this parameter is not specified, the recording files will be stored in the path defined by the -p parameter.

For example, if you mount a device or an external NAS device to /pbx/recordings and want to store the recording files there, you can create and run the PBX Docker instance using the following command:

If you have mounted a local disk or an external NAS device at /pbx/recordings, you can store recording files there by running:

Configure the PortSIP PBX

After the installation completes successfully, access the PBX web portal at: https://66.175.221.120:8887

Click on "Sign in as the administrator or dealer" to navigate to the administrator login page, as shown in the screenshot below. Enter admin as both the username and password to log in to the web portal.

❗Important For security reasons, change the default administrator password immediately after logging in.

For a new installation, the PBX automatically launches a Setup Wizard after the first successful login to the PBX web portal. This wizard guides you through the mandatory initial configuration steps.

1. Network Environment

In the Network Environment step, configure the PBX IP addresses.

The loopback interface (127.0.0.1) is not suitable for a private IP address. Only the static IP for the LAN where the PBX is located is allowed (do not use a DHCP dynamic IP).

Private IPv4 Address

  • Enter the server’s private IPv4 address.

  • If the server does not have a private IP address, enter the public IP address instead.

Public IPv4 Address

  • If the PBX server has a static public IP address, enter it in the Public IPv4 field.

  • If the server does not have a static public IP address, leave this field blank.

Important Notes on IP Configuration

  • The IP addresses configured here are used by SIP clients and IP phones to register with the PBX.

  • The configured IP address will act as the SIP server address and should be set as the Outbound Proxy Server on SIP endpoints.

  • Cloud Deployment: Both Private IPv4 and Public IPv4 addresses must be entered.

  • LAN Deployment: Only the Private IPv4 address is required.

2. SSL Certificate

To enable TLS transport for SIP and provide secure HTTPS access to the PBX Web Portal and REST API, a trusted SSL certificate must be configured during this step.

Domain Setup

You must have a web domain for the PBX. For example, you can purchase a domain from providers such as GoDaddy and point it to your PBX server’s IP address.

SSL Certificate Requirements

  • A trusted SSL certificate is strongly recommended to avoid browser security warnings.

  • Common certificate providers include:

    • DigiCert

    • GeoTrust

    • GoDaddy

    • Other trusted Certificate Authorities (CAs)

Note If you do not have a domain or SSL certificate, you may use the PBX server’s IP address as the Web Domain and proceed with the default certificate. However, PortSIP PBX uses a self-signed certificate by default, which will cause browsers to block the connection and display security warnings.

To purchase and prepare an SSL certificate, follow the guide: Preparing TLS Certificates for TLS/HTTPS/WebRTC.

After completing the steps in that guide, you will have the following certificate files:

  • portsip.pem — Certificate file

  • portsip.key — Private key file

Configuring the Certificate

In this guide, we assume the PBX web domain is uc.portsip.cc.

  1. In the Web Domain field, enter: uc.portsip.cc

  2. Open the portsip.pem file in a text editor (such as Windows Notepad), and copy the entire contents into the Certificate File field.

  3. Open the portsip.key file and copy the entire contents into the Private Key File field.

3. Transport Protocol

Click Add to create or review the transport protocols. By default, PortSIP PBX uses the following transport ports:

  • UDP: 5060

  • TCP: 5063

  • TLS: 5061

Customizing Transport Ports

You may change the default transport ports to any values that suit your deployment requirements.

❗Important

  • Ensure the selected port is not already in use by another application.

  • Use TLS whenever possible to secure SIP signaling.

Firewall and Client Configuration

After adding or modifying a transport protocol:

  • Update your firewall rules to allow traffic on the newly assigned port.

  • Configure IP phones and client applications to use the same transport protocol and port when connecting to the PBX.

The transport protocol and port configured here are used by:

  • SIP phones

  • Desktop and mobile client apps

  • Other SIP endpoints registering to the PBX

Click the OK button to complete the setup wizard.

Install the Instant Messaging (IM) Service

Starting with PortSIP PBX v22.0, an integrated Instant Messaging (IM) service is available, providing modern collaboration features such as:

  • One-to-one messaging

  • Group chat

The IM service requires a separate installation step.

For high-concurrency or large-scale deployments, we recommend installing the IM service on a dedicated server to achieve better performance and scalability.

Please follow the guide below to install and configure the IM service: Install IM Service

Install the Data Flow Service

Starting with PortSIP PBX v22.3.0, PortSIP introduces the Data Flow service, which delivers:

  • Advanced data analytics

  • Real-time metrics

  • Dashboards and wallboards

The Data Flow service is built on ClickHouse, a high-performance, column-oriented database optimized for analytics workloads. Due to its resource-intensive nature, this service must be installed on a dedicated, high-performance server and runs independently from the core PBX.

Please follow the guide below to install and configure the Data Flow service: Install Data Flow Service

Note Installing the Data Flow service is optional.

  • Call processing is not affected if it is not installed.

  • However, analytics, wallboards, and certain metrics features will be unavailable.

Restart the PBX to Apply the SSL Certificate

If in above step 2. SSL Certificate, you uploaded a trusted SSL certificate instead of using the default self-signed certificate, you must restart the PBX to apply the changes.

Run the following commands to restart the PBX:

Now that the PortSIP PBX is successfully installed, you can use https://uc.portsip.cc:8887 to access the PortSIP PBX web portal.

Managing PortSIP PBX Docker Instance

After successfully installing the PortSIP PBX, you can use the following commands to manage the PBX Docker instance.

All commands must be executed from the following directory:

Show PBX Status

Start the PBX

Stop the PBX

Restart the PBX

Remove the PBX Container

This command does not delete PBX data.

Managing PortSIP IM Service Docker Instance

To manage the PortSIP Instant Messaging (IM) Service Docker instance, first ensure you are in the /opt/portsip directory:

Show IM Service Status

Start the IM Service

Stop the IM Service

Restart the IM Service

Remove the IM Service Container

This command does not delete IM service data.

Managing PortSIP Data Flow Service Docker Instance

To manage the PortSIP Data Flow Service Docker instance, ensure you are in the /opt/portsip directory:

Show Data Flow Service Status

Start the Data Flow Service

Stop the Data Flow Service

Restart the Data Flow Service

Remove the Data Flow Service Container

This command does not delete Data Flow service data.

Delete the PBX Docker Instance

This command will not delete the data of the PBX.

Managing PortSIP IM Service Docker Instance

First, you will need to at the /opt/portsip folder, then you can use the following commands to manage the PortSIP IM Service Docker instance.

Show the IM Service Docker Instance Status

Start the IM Service Docker Instance

Stop the IM Service Docker Instance

Restart the IM Service Docker Instance

Delete the IM Service Docker Instance

This command will not delete the data of the PBX.

Managing PortSIP Data Flow Service Docker Instance

First, you will need to be at the /opt/portsip folder, then you can use the following commands to manage the PortSIP Data Flow Service Docker instance.

Show the Data Flow Service Docker Instance Status

Start the Data Flow Service Docker Instance

Stop the Data Flow Service Docker Instance

Restart the Data Flow Service Docker Instance

Delete the Data Flow Service Docker Instance

This command will not delete the data of the PBX.

If you wish to delete the data associated with Data Flow, use the following commands:

Note: If you specified a custom path for storing the data instead of using the default path, replace /var/lib/portsip/dataflow and /var/lib/portsip/clickhouse in the above commands with your specified path that was used during the installation of the Data Flow service.

PreviousInstallation of PortSIP PBX v22.xNextInstall IM Service

Last updated

Was this helpful?