Deployment Overview of FreePBX on Server¶

Prerequisites and Basic Requirements¶

The deployment requires a Debian 12 operating system. The server must be configured with a Fully Qualified Domain Name (FQDN) constructed from a specific prefix, server ID, and zone. The system hostname is set to match this FQDN, and the /etc/hosts file is updated to resolve 127.0.1.1 to the new FQDN.

The following network ports and services are utilized: - Port 80 and 443 for web traffic and SSL termination. - Port 3000 for internal proxy communication. - The apache2 service is used as the primary web server. - The asterisk service runs the core telephony functions.

File and Directory Structure¶

The application and its components are organized in the following directories:

• /etc/asterisk/keys/: Stores SSL certificates and keys, including Let's Encrypt certificates named after the FQDN (e.g., {{ freepbx_fqdn }}.crt and {{ freepbx_fqdn }}.key).
• /var/run/asterisk/: Runtime directory for the Asterisk service.
• /root/nginx/: Contains the Docker Compose configuration for the reverse proxy.
• /data/nginx/user_conf.d/: Stores custom Nginx configuration files for specific host keys.
• /etc/apache2/sites-available/default-ssl.conf: Apache SSL configuration file.
• /tmp/sng_freepbx_debian_install.sh: Temporary location for the installation script.
• /root/freepbx-install.log: Log file capturing the installation output.

Application Installation Process¶

FreePBX version 17 is installed on Debian 12 using a dedicated installation script. The process involves the following steps:

1. The installation script is downloaded from the official FreePBX GitHub repository to /tmp/sng_freepbx_debian_install.sh.
2. The script is executed with bash, and output is logged to /root/freepbx-install.log.
3. Upon successful completion, the server is automatically rebooted to finalize the installation.
4. After the server reconnects, the fwconsole chown command is executed to ensure correct file ownership.

The installation script handles the core setup of the FreePBX environment, including the Asterisk telephony platform and the web interface.

Access Rights and Security¶

Security is managed through the following mechanisms:

• Firewall and Network: The system relies on the host's network configuration. The apache2 service is reloaded after SSL configuration changes to apply new security policies.
• User Permissions: The fwconsole chown command ensures that the asterisk user owns the necessary files and directories.
• SSL Certificates: Let's Encrypt certificates are generated and managed via the fwconsole utility. The certificate generation requires the following parameters:
• --type=le
• --hostname set to the server FQDN.
• --country-code, --state, and --email for registration details.
• Certificate Management: The generated certificate is set as the default using fwconsole cert --default and applied to all integrations via fwconsole cert --updateall.

Proxy Servers¶

A reverse proxy is deployed using Docker to handle SSL termination and traffic routing. The proxy stack consists of Nginx and Certbot.

• Container Image: jonasal/nginx-certbot:latest
• Configuration Location: /root/nginx/compose.yml
• Volume Mounts:
• nginx_secrets (external volume) mounted to /etc/letsencrypt for certificate storage.
• /data/nginx/user_conf.d mounted to /etc/nginx/user_conf.d for custom configurations.
• Network Mode: The container runs in host network mode.
• Environment:
• CERTBOT_EMAIL is set to [email protected].
• Additional environment variables are loaded from /data/nginx/nginx-certbot.env.

The proxy configuration includes a custom rule in /data/nginx/user_conf.d/{{ prefix }}{{ server_id }}.hostkey.in.conf that directs traffic to the internal application: - proxy_pass http://127.0.0.1:3000;

The Apache SSL configuration is updated to point to the Let's Encrypt certificates located in /etc/asterisk/keys/: - SSLCertificateFile points to /etc/asterisk/keys/{{ freepbx_fqdn }}.crt. - SSLCertificateKeyFile points to /etc/asterisk/keys/{{ freepbx_fqdn }}.key.

Docker Containers and Their Deployment¶

The proxy infrastructure is deployed using Docker Compose. The configuration file is located at /root/nginx/compose.yml.

The nginx service is defined with the following parameters: - Image: jonasal/nginx-certbot:latest - Restart Policy: unless-stopped - Volumes: - nginx_secrets:/etc/letsencrypt - /data/nginx/user_conf.d:/etc/nginx/user_conf.d - Environment: - [email protected] - env_file: /data/nginx/nginx-certbot.env - Network: host

The deployment process involves generating the compose.yml file and ensuring the custom Nginx configuration file is updated with the correct proxy_pass directive.

Permission Settings¶

File and directory permissions are managed to ensure the services can read and write necessary data:

• The /root/nginx directory is owned by root with mode 0755.
• The compose.yml file is owned by root with mode 0644.
• The /var/run/asterisk directory is owned by asterisk:asterisk with mode 0755.
• The fwconsole chown command is executed post-installation to correct ownership of FreePBX files.

Starting, Stopping, and Updating¶

Service management is handled through the following commands and utilities:

• Apache Service:
• Configuration test: apache2ctl configtest
• Reload: systemctl reload apache2 (triggered automatically after SSL updates).
• FreePBX Console:
• Reload Asterisk: fwconsole reload
• Set default certificate: fwconsole cert --default=<certificate_id>
• Update integrations: fwconsole cert --updateall
• Docker Proxy:
• The proxy container is managed via Docker Compose located in /root/nginx.
• Start/Stop commands are executed using docker compose in the /root/nginx directory.