Deployment Overview of FreePBX on Server¶

Prerequisites and Basic Requirements¶

The deployment of FreePBX requires a server running Debian 12. The installation process involves updating the system package lists and installing essential utilities such as wget and curl. The system hostname must be configured to match the Fully Qualified Domain Name (FQDN) of the application.

The following components are required:

Operating System: Debian 12
Privileges: Root access is required for installation and configuration.
Domain: The server must be accessible via the hostkey.in zone.
Ports:
Internal application port: 3000
External HTTPS port: 443

FQDN of the Final Panel¶

The application is accessible via a specific FQDN constructed using the prefix freepbx, the server ID, and the hostkey.in domain. The format for the final address is:

freepbx<Server ID>.hostkey.in:443

The system hostname is automatically set to this FQDN, and the entry is added to the /etc/hosts file to ensure local resolution.

File and Directory Structure¶

The FreePBX installation places configuration files, data, and certificates in specific directories within the server's filesystem.

Configuration Files: Located in /etc/asterisk/ and /etc/apache2/.
Certificates: Let's Encrypt certificates are stored in /etc/asterisk/keys/.
Runtime Data: The Asterisk runtime directory is located at /var/run/asterisk.
Nginx Configuration: Custom proxy configurations are stored in /data/nginx/user_conf.d/.
Docker Compose: The Nginx proxy configuration is defined in /root/nginx/compose.yml.

Application Installation Process¶

FreePBX version 17 is installed using the official Debian 12 installation script. The process involves downloading the script from the FreePBX GitHub repository and executing it with elevated privileges.

The installation script is downloaded to /tmp/sng_freepbx_debian_install.sh.
The script is executed, and the output is logged to /root/freepbx-install.log.
Upon successful completion, the server is automatically rebooted to apply changes.
After the reboot, the fwconsole chown command is executed to set correct file ownership.

The installation script is sourced from: https://github.com/FreePBX/sng_freepbx_debian_install/raw/master/sng_freepbx_debian_install.sh

Access Rights and Security¶

Security is enforced through the use of Let's Encrypt SSL certificates and firewall configurations managed by the application.

SSL Certificates: Let's Encrypt certificates are generated for the FQDN using the fwconsole certificates command.
Certificate Details:
Country Code: NL
State: NH
Email: [email protected]
Default Certificate: The generated certificate is set as the default for the system using fwconsole cert --default.
Apache Configuration: The Apache SSL configuration (/etc/apache2/sites-available/default-ssl.conf) is updated to point to the Let's Encrypt certificate and key files.

Databases¶

The FreePBX application utilizes an internal database managed by the Asterisk and FreePBX services. The database configuration is handled automatically during the installation process via the sng_freepbx_debian_install.sh script. No external database connection parameters are exposed in the provided configuration.

Docker Containers and Their Deployment¶

A Docker container running Nginx with Certbot support is deployed to handle SSL termination and proxying. The container is managed using a docker-compose file located at /root/nginx/compose.yml.

Image: jonasal/nginx-certbot:latest
Restart Policy: unless-stopped
Network Mode: host
Volumes:
nginx_secrets (external) mounted to /etc/letsencrypt
/data/nginx/user_conf.d mounted to /etc/nginx/user_conf.d
Environment:
CERTBOT_EMAIL: [email protected]
Configuration loaded from /data/nginx/nginx-certbot.env

Proxy Servers¶

Nginx acts as a reverse proxy for the FreePBX application, handling HTTPS traffic on port 443 and forwarding requests to the internal application port.

Proxy Configuration: The proxy rule is defined in /data/nginx/user_conf.d/freepbx<Server ID>.hostkey.in.conf.
Proxy Target: Requests are forwarded to http://127.0.0.1:3000.
SSL Termination: SSL termination is handled by the Nginx container using Let's Encrypt certificates.
Path Mapping:
Internal Path: /
External Path: /

Permission Settings¶

File and directory permissions are managed by the FreePBX installation script and the fwconsole chown command.

Asterisk Runtime: The directory /var/run/asterisk is owned by the asterisk user and group with mode 0755.
Nginx Directory: The directory /root/nginx is owned by root with mode 0755.
Compose File: The file /root/nginx/compose.yml is owned by root with mode 0644.

Location of Configuration Files and Data¶

Key configuration files and data locations are as follows:

Component	File Path	Description
Apache SSL Config	`/etc/apache2/sites-available/default-ssl.conf`	SSL certificate paths for Apache
Nginx Proxy Config	`/data/nginx/user_conf.d/freepbx<Server ID>.hostkey.in.conf`	Proxy pass rules
Docker Compose	`/root/nginx/compose.yml`	Nginx container definition
Certificates	`/etc/asterisk/keys/`	Let's Encrypt certificate files
Install Log	`/root/freepbx-install.log`	Installation output log

Available Ports for Connection¶

The following ports are configured for the application:

Port 443: HTTPS traffic for the web interface (external access).
Port 3000: Internal HTTP traffic for the FreePBX application (accessed via proxy).

Starting, Stopping, and Updating¶

Service management for FreePBX is handled via the fwconsole utility, while the Nginx proxy is managed via Docker Compose.

Reload FreePBX:
```
fwconsole reload
```

Set Default Certificate:

fwconsole cert --default=<certificate_id>

Update All Certificates:
```
fwconsole cert --updateall
```
Start Nginx Proxy:
```
docker compose up -d
```
(Execute from the /root/nginx directory)

The Apache service is reloaded automatically after certificate updates to apply new SSL configurations.