Installation

Database Servers

By following the database installation steps outlined in the APIO Core Deployment Guide, you ensure a robust database setup, including redundancy through replication. Once the database is operational, execute the necessary commands to create a dedicated database for the APIO Broadworks Gateway.

Generate a random password that will be used to authenticate the application:

[postgres@db1 ~]$ openssl rand -base64 12

Swith to user postgres and connect to the DB:

[root@db1 ~]# su - postgres
[postgres@db1 ~]$ psql

Create the apio_gtw user, replacing <password> with the one previously generated:

postgres=# CREATE ROLE apio_gtw LOGIN PASSWORD '<password>';
CREATE ROLE

Create the database apio_gtw, owned by user apio_gtw and set the databse timezone to UTC:

postgres=# CREATE DATABASE apio_gtw OWNER apio_gtw;
CREATE DATABASE

TIP

In multi-gateway deployments that share the same database server, ensure that each gateway uses a distinct database name to prevent conflicts.

Core/GW Servers

Containers Setup

The BWGW is deployed as a container alongside the APIO Core, with its configuration managed through the following environment variables. Environment variables with acceptable default values do not need to be explicitly defined in the docker-compose.yml file.

Parameter	Description	Default Value
BWGW_LOG_LEVEL	Log level: DEBUG, INFO, WARN, CRITICAL	INFO
BWGW_DB_NAME	PostgreSQL database name	apio_gtw
BWGW_DB_USERNAME	PostgreSQL connection user	apio_gtw
BWGW_DB_PASSWORD	PostgreSQL connection password	""
BWGW_DB_HOST	PostgreSQL database host	127.0.0.1
BWGW_DB_PORT	PostgreSQL database port	5432
BWGW_DB_RENTENTION	Database retention (months)	6
BWGW_NUM_PROCS	Number of gateway processes (inside container)	4
BWGW_SYSTEM_DEFAULT_DOMAIN	System default domain	netaxis.cloud
BWGW_DEFAULT_DOMAIN	Default domain	sip.netaxis.cloud
BWGW_TIMEZONE	Timezone	Europe/Brussels
BWGW_COUNTRY_CODE	Country code	BE
BWGW_AS_SYSTEM_USERNAME	Broadworks system user name
BWGW_AS_SYSTEM_PASSWORD	Broadworks system user password
BWGW_AS_SUPER_USERNAME	Broadworks super user name
BWGW_AS_SUPER_PASSWORD	Broadworks super user password
BWGW_DJANGO_ADMIN_USERNAME	Gateway Django admin interface username
BWGW_DJANGO_ADMIN_PASSWORD	Gateway Django admin interface password
BWGW_AS_IP	Broadworks application server IP
BWGW_OCI_VERSION	Broadworks OCI protocol version	22.0
BWGW_XSI_VERSION	Broadworks XSI protocol version	22.0
BWGW_NSOSS_VERSION	Broadworks NS OSS protocol version	22.0

The BWGW container generates all logs in the /var/log/apio directory. For simplified log management, this directory should be mapped to the host's /var/log/apio_gtw.

The container exposes ports 80 and 443 for both the Django admin interface and the API endpoints accessible by the Core. These ports can be published on the host, either restricted to localhost or made publicly accessible by using the 0.0.0.0 listen address.

WARNING

The Core communicates with the BWGW exclusively through Docker's internal networking, eliminating the need to publish BWGW ports externally. However, for administrative purposes and access to the BWGW admin interface, it is recommended to expose the HTTPS port. For security reasons, this should be limited to localhost. The BWGW admin interface must never be accessible from the public Internet.

Below is a sample docker-compose.yml configuration. Environment variables that are not explicitly defined will inherit their default values as specified in the environment variables table.

yaml

services:
  bwgw:
    image: docker.bxl.netaxis.be/apio_bsft/bsft_gw:1.11.3
    restart: always
    ports:
      - 8443:443
    volumes:
      - /var/log/apio_gtw:/var/log/apio
    environment:
      BWGW_DB_HOST: 10.0.10.30
      BWGW_DB_USERNAME: apio_gtw
      BWGW_DB_PASSWORD: zeratul
      BWGW_AS_IP: 10.0.32.58
      BWGW_SYSTEM_DEFAULT_DOMAIN: provider.com
      BWGW_DEFAULT_DOMAIN: sip.voip.com
      BWGW_TIMEZONE: Europe/Paris
      BWGW_COUNTRY_CODE: FR
      BWGW_AS_SYSTEM_USERNAME: fenix@provider.com
      BWGW_AS_SYSTEM_PASSWORD: ...
      BWGW_AS_SUPER_USERNAME: raynor@provider.com
      BWGW_AS_SUPER_PASSWORD: ...
      BWGW_DJANGO_ADMIN_USERNAME: admin
      BWGW_DJANGO_ADMIN_PASSWORD: ...
      BWGW_NUM_PROCS: 4

When merged with an existing Core docker-compose.yml file, the resulting configuration will look like the one below. In this example, the BWGW container service, named bwgw, will be accessible from the Core using this hostname over the Docker internal network.

yaml

services:
  nginx:
    image: nginx:latest
    restart: always
    ports:
      - "0.0.0.0:80:80"
    volumes:
      - static-files:/www/
      - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
      - /var/log/apio_core:/var/log/nginx
    depends_on:
      - core
      - p1
    logging:
      driver: syslog
      options:
        tag: "{{.Name}}"

  core:
    image: docker.bxl.netaxis.be/apio_bsft/core:2.15.2
    command: /usr/local/go/server -workflows -port=5000 -host=0.0.0.0 -cleanup -metrics
    restart: always
    ports:
      - "0.0.0.0:9090:9090"
    environment:
      - DB=postgres://postgres:postgres@db:5432/apio_core
      - VIRTUAL_ENV=/opt/apio_core
    volumes:
      - static-files:/usr/local/www/
      - /var/run/docker.sock:/var/run/docker.sock
    logging:
      driver: syslog
      options:
        tag: "{{.Name}}"

  scheduler:
    image: docker.bxl.netaxis.be/apio_bsft/core:2.15.2
    command: /usr/local/go/scheduler -pprof
    restart: always
    environment:
      - DB=postgres://postgres:postgres@db:5432/apio_core
      - VIRTUAL_ENV=/opt/apio_core
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    logging:
      driver: syslog
      options:
        tag: "{{.Name}}"

  p1:
    image: docker.bxl.netaxis.be/apio_bsft/core:2.15.2
    command: /usr/local/go/server -workflows -port=5000 -host=0.0.0.0 -proxy=/api/v01/p1:bwks -runMigration=false
    restart: always
    environment:
      - DB=postgres://postgres:postgres@db:5432/apio_core
      - VIRTUAL_ENV=/opt/apio_core
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    logging:
      driver: syslog
      options:
        tag: "{{.Name}}"

  bwgw:
    image: docker.bxl.netaxis.be/apio_bsft/bsft_gw:1.11.3
    restart: always
    ports:
      - 8443:443
    volumes:
      - /var/log/apio_gtw:/var/log/apio
    environment:
      BWGW_DB_HOST: 10.0.10.30
      BWGW_DB_USERNAME: apio_gtw
      BWGW_DB_PASSWORD: zeratul
      BWGW_AS_IP: 10.0.32.58
      BWGW_SYSTEM_DEFAULT_DOMAIN: provider.com
      BWGW_DEFAULT_DOMAIN: sip.voip.com
      BWGW_TIMEZONE: Europe/Paris
      BWGW_COUNTRY_CODE: FR
      BWGW_AS_SYSTEM_USERNAME: fenix@provider.com
      BWGW_AS_SYSTEM_PASSWORD: ...
      BWGW_AS_SUPER_USERNAME: raynor@provider.com
      BWGW_AS_SUPER_PASSWORD: ...
      BWGW_DJANGO_ADMIN_USERNAME: admin
      BWGW_DJANGO_ADMIN_PASSWORD: ...
      BWGW_NUM_PROCS: 4

volumes:
  static-files:

INFO

In this example configuration, the BWGW service is accessible from the Core using the hostname bwgw. As a result, the Core configuration can define a new gateway with http://bwgw (or https://bwgw) as its URL.

First Start

You can use the docker compose logs bwgw command to monitor the logs of the bwgw service. Below is an example output with key log lines highlighted:

bwgw-1  | WARNING:root:>>> Performing initialization tasks
bwgw-1  | WARNING:root:Generating YAML template vars from environment variables: jinja -X 'BWGW.*' -o /docker/template_vars.yaml /docker/template_vars.yaml.tmpl
bwgw-1  | WARNING:root:Generating Django settings file: jinja -f yaml -d /docker/template_vars.yaml -o /opt/apio-gateway_frontend/apio-gateway/apio_gateway_frontend/settings/apio_gateway-default.py /opt/apio-gateway_frontend/apio-gateway/apio_gateway_frontend/settings/apio_gateway_template.py
bwgw-1  | WARNING:root:Generating PROQ settings file: jinja -f yaml -d /docker/template_vars.yaml -o /opt/apio-gateway_frontend/apio-gateway/apio_gateway_frontend/proq/proq-default.cfg /opt/apio-gateway_frontend/apio-gateway/apio_gateway_frontend/proq/proq_template.cfg
bwgw-1  | WARNING:root:Generating cleanup audit script: jinja -f yaml -d /docker/template_vars.yaml -o /opt/apio-gw-core/ops/scripts/clean_audit_default.sh /opt/apio-gw-core/ops/scripts/template_clean_audit_project.sh
bwgw-1  | WARNING:root:Running chmod +x /opt/apio-gw-core/ops/scripts/clean_audit_default.sh
bwgw-1  | WARNING:root:Generating cleanup Django sessions script: jinja -f yaml -d /docker/template_vars.yaml -D apio_name apio-gateway -o /opt/apio-gw-core/ops/scripts/clean_django_sessions_default.sh /opt/apio-gw-core/ops/scripts/template_clean_django_sessions_project.sh
bwgw-1  | WARNING:root:Running chmod +x /opt/apio-gw-core/ops/scripts/clean_django_sessions_default.sh
bwgw-1  | WARNING:root:Generating Caddy configuration file: jinja -f yaml -d /docker/template_vars.yaml -o /etc/caddy/Caddyfile /docker/Caddyfile.tmpl
bwgw-1  | WARNING:root:Generating Supervisord configuration file: jinja -f yaml -d /docker/template_vars.yaml -o /etc/supervisord.d/supervisord-programs.ini /docker/supervisord-programs.ini.tmpl
bwgw-1  | WARNING:root:Generating update Django DB script: jinja -f yaml -d /docker/template_vars.yaml -D apio_name apio-gateway -o /opt/apio-gw-core/ops/scripts/update_django_db_default.sh /opt/apio-gw-core/ops/scripts/template_update_django_db_project.sh
bwgw-1  | WARNING:root:Running sh /opt/apio-gw-core/ops/scripts/update_django_db_default.sh
bwgw-1  | Upgrading DB structure (if needed)
bwgw-1  | Operations to perform:
bwgw-1  |   Apply all migrations: admin, auth, authentication, authtoken, contenttypes, services, sessions, sites
bwgw-1  | Running migrations:
bwgw-1  |   No migrations to apply.
bwgw-1  |   Your models in app(s): 'authentication', 'services' have changes that are not yet reflected in a migration, and so won't be applied.
bwgw-1  |   Run 'manage.py makemigrations' to make new migrations, and then re-run 'manage.py migrate' to apply them.
bwgw-1  | WARNING:root:>>> Ready to launch all process via Supervisord
bwgw-1  | WARNING:root:Running supervisord -n -c /etc/supervisord.conf
bwgw-1  | 2025-05-09 11:05:16,947 CRIT Supervisor is running as root.  Privileges were not dropped because no user is specified in the config file.  If you intend to run as root, you can set user=root in the config file to avoid this message.
bwgw-1  | 2025-05-09 11:05:16,947 INFO Included extra file "/etc/supervisord.d/supervisord-programs.ini" during parsing
bwgw-1  | 2025-05-09 11:05:17,252 INFO RPC interface 'supervisor' initialized
bwgw-1  | 2025-05-09 11:05:17,252 CRIT Server 'unix_http_server' running without any HTTP authentication checking
bwgw-1  | 2025-05-09 11:05:17,252 INFO supervisord started with pid 26
bwgw-1  | 2025-05-09 11:05:18,255 INFO spawned: 'apio_gtw-0' with pid 29
bwgw-1  | 2025-05-09 11:05:18,256 INFO spawned: 'caddy' with pid 30
bwgw-1  | 2025-05-09 11:05:19,283 INFO success: apio_gtw-0 entered RUNNING state, process has stayed up for > than 1 seconds (startsecs)
bwgw-1  | 2025-05-09 11:05:19,283 INFO success: caddy entered RUNNING state, process has stayed up for > than 1 seconds (startsecs)

Initial Setup

After the BWGW container is up and running, access the container using the appropriate command.

docker compose exec bwgw bash

Once inside, execute the load-initial-data command to populate the database with the default BroadWorks configuration.

[root@95ef11842497 /]# /docker/entrypoint.py load-initial-data
Running the command /opt/apio-gateway_frontend/apio-gateway-ops/scripts/load_initial_data.sh /opt/apio-gw-core apio_gateway_frontend.settings.apio_gateway-default Backend_default-default.json requires confirmation.
This action loads initial data into the DB. It must be performed on a new system only.
Continue? ([Y]es/[N]o) y
WARNING:root:Running /opt/apio-gateway_frontend/apio-gateway-ops/scripts/load_initial_data.sh /opt/apio-gw-core apio_gateway_frontend.settings.apio_gateway-default Backend_default-default.json
Important initial configuration objects
2025-05-12 11:24:43,837 - DEBUG - Using selector: EpollSelector
2025-05-12 11:24:43,940 - DEBUG - *** Using APIO_COMMON_UTILS: apio_gateway_commons.utils.ApioGwApioUtils
Installed 4 object(s) from 1 fixture(s)
2025-05-12 11:24:45,598 - DEBUG - Using selector: EpollSelector
2025-05-12 11:24:45,702 - DEBUG - *** Using APIO_COMMON_UTILS: apio_gateway_commons.utils.ApioGwApioUtils
Installed 5 object(s) from 1 fixture(s)
2025-05-12 11:24:47,386 - DEBUG - Using selector: EpollSelector
2025-05-12 11:24:47,487 - DEBUG - *** Using APIO_COMMON_UTILS: apio_gateway_commons.utils.ApioGwApioUtils
Installed 4 object(s) from 1 fixture(s)
2025-05-12 11:24:49,161 - DEBUG - Using selector: EpollSelector
2025-05-12 11:24:49,264 - DEBUG - *** Using APIO_COMMON_UTILS: apio_gateway_commons.utils.ApioGwApioUtils
Installed 4 object(s) from 1 fixture(s)
2025-05-12 11:24:50,896 - DEBUG - Using selector: EpollSelector
2025-05-12 11:24:50,998 - DEBUG - *** Using APIO_COMMON_UTILS: apio_gateway_commons.utils.ApioGwApioUtils
Installed 11 object(s) from 1 fixture(s)

To create a Django admin user with the credentials specified in the previously defined environment variables, execute the create-django-admin command.

[root@1b4e962b272d /]# /docker/entrypoint.py create-django-admin
WARNING:root:Generating YAML template vars from environment variables: jinja -X 'BWGW.*' -o /docker/template_vars.yaml /docker/template_vars.yaml.tmpl
WARNING:root:Generating Django admin script: jinja -f yaml -d /docker/template_vars.yaml -D apio_name apio-gateway -o /opt/apio-gw-core/ops/scripts/create_django_admin_default.sh /opt/apio-gw-core/ops/scripts/template_create_django_admin.sh
Running the command sh /opt/apio-gw-core/ops/scripts/create_django_admin_default.sh requires confirmation.
This action creates a new super admin user on the Django interface.
Continue? ([Y]es/[N]o) y
WARNING:root:Running sh /opt/apio-gw-core/ops/scripts/create_django_admin_default.sh
**** Creating adminNetaxis
2025-05-12 11:36:58,294 - DEBUG - Using selector: EpollSelector
2025-05-12 11:36:58,395 - DEBUG - *** Using APIO_COMMON_UTILS: apio_gateway_commons.utils.ApioGwApioUtils

Installation ​

Database Servers ​

Core/GW Servers ​

Containers Setup ​