Deployment Overview of ISPConfig on Server¶

Prerequisites and Basic Requirements¶

To deploy the ISPConfig panel on the server, the following environment and configuration requirements must be met:

• Operating System: Ubuntu (specifically jammy or compatible codenames as determined by ansible_lsb.codename).

• Privileges: Root access or sudo privileges are required for package installation, file system modifications, and service management.

• Domain and DNS: The Fully Qualified Domain Name (FQDN) must be configured to resolve to the server's IP address. The format is ispconfig<Server ID>.hostkey.in.

• Ports: The following TCP ports must be available and open in the firewall:

  • 22 (SSH)

  • 80 (HTTP)

  • 443 (HTTPS)

  • 8080 (Internal ISPConfig interface)

• Software Dependencies: The installation process installs the following packages if not present: php-cli, php-mbstring, curl, nginx, bind9, ufw, wget, tar, unzip, gnupg, and ca-certificates.

FQDN of the Final Panel¶

The fully qualified domain name for accessing the ISPConfig panel on the hostkey.in domain follows this pattern:

ispconfig<Server ID>.hostkey.in:443

The hostname is configured via the ispconfig_fqdn variable and mapped in the /etc/hosts file to the server's default IPv4 address.

File and Directory Structure¶

The application, configuration files, and data are organized in the following locations:

• Installation Root: /usr/local/ispconfig

• Web Interface: /usr/local/ispconfig/interface

• Web Root: /usr/local/ispconfig/interface/web

• Main Configuration File: /usr/local/ispconfig/interface/lib/config.inc.php

• Temporary Files:

  • ISPConfig Temp: /usr/local/ispconfig/interface/temp

  • PHPIDS Temp: /usr/local/ispconfig/interface/lib/classes/IDS/tmp

• Nginx Configuration:

  • Virtual Host: /etc/nginx/sites-available/ispconfig.vhost

  • Enabled Symlink: /etc/nginx/sites-enabled/000-ispconfig.vhost

• Docker Proxy Configuration:

  • Docker Compose File: /root/nginx/compose.yml

  • User Configuration Directory: /data/nginx/user_conf.d

• Logs: Installation logs are stored in /root/ispconfig-ai-run.log.

Application Installation Process¶

The deployment utilizes the ISPConfig Autoinstall script (ispconfig.ai.php) executed with specific flags to configure the environment non-interactively.

1. Script Acquisition: The installer script is downloaded from https://www.ispconfig.org/downloads/ispconfig-ai.tar.gz to /tmp/ispconfig-ai.

2. Execution Flags: The installer runs with the following configuration:

   • --use-nginx: Enables Nginx as the web server.

   • --no-roundcube: Disables the Roundcube webmail installation.

   • --no-mail, --no-dns, --no-ftp: Disables configuration for mail, DNS, and FTP services.

   • --unattended-upgrades: Enables automatic security updates.

   • --i-know-what-i-am-doing: Confirms the installer to proceed without interactive prompts.

3. Command:

   php -q /tmp/ispconfig-ai/ispconfig.ai.php --use-nginx --no-roundcube --no-mail --no-dns --no-ftp --unattended-upgrades --i-know-what-i-am-doing
   

4. Versioning: The installer attempts to fetch the latest stable version. A script patch is applied to /tmp/ispconfig-ai/lib/os/class.ISPConfigDebianOS.inc.php to handle version detection logic.

5. Database Image: A specific corporate MariaDB image is pulled and used: docker-srv.hostkey.com/docker-anonymous/bitnami/mariadb:latest.

Access Rights and Security¶

The server employs strict firewall rules and user permissions to secure the environment.

• Firewall: The ufw (Uncomplicated Firewall) service is installed and enabled.

  • Allowed TCP ports: 22, 80, 443, 8080.

• SSH: Access on port 22 is explicitly allowed before enabling the firewall.

• Service Isolation:

  • Default Nginx sites (default, 999-acme.vhost) are removed.

  • Any existing containers binding to ports 80 or 443 are stopped and disabled from auto-restart to prevent conflicts with the proxy setup.

• Web User: The web server processes run as the www-data user.

Databases¶

The ISPConfig panel utilizes a local MySQL/MariaDB database for its configuration storage.

• Database Name: dbispconfig

• Database Host: localhost

• Database Port: 3306

• Connection Method: Local socket connection via Nginx/PHP-FPM.

• User Credentials:

  • Root User: root

  • ISPConfig User: ispconfig

  • Passwords: Defined in the configuration variables (default in source is admin123, but should be changed in production).

• Character Set: utf8

Docker Containers and Their Deployment¶

A Docker Compose setup is deployed to manage the reverse proxy and SSL certificate handling.

• Container Name: nginx (part of the jonasal/nginx-certbot stack).

• Image: jonasal/nginx-certbot:latest

• Deployment Location: /root/nginx

• Configuration: Defined in /root/nginx/compose.yml.

• Volumes:

  • nginx_secrets: Mounted to /etc/letsencrypt (external volume).

  • Host Config: /data/nginx/user_conf.d mounted to /etc/nginx/user_conf.d.

• Network Mode: host

• Startup Command:

  docker compose up -d
  

  executed in the /root/nginx directory.

Proxy Servers¶

The system uses a Dockerized Nginx container with Certbot integration to handle SSL termination and routing.

• Proxy Type: Nginx via jonasal/nginx-certbot image.

• SSL Configuration: Managed automatically by Certbot using Let's Encrypt.

• Routing Configuration:

  • The proxy passes traffic from hostkey.in domains to the internal ISPConfig service running on port 8080.

  • Configuration file: /data/nginx/user_conf.d/ispconfig<Server ID>.hostkey.in.conf.

  • Proxy rule: proxy_pass http://127.0.0.1:8080;

• Host Nginx:

  • The host's native Nginx instance listens only on port 8080 for the ISPConfig interface without SSL.

  • SSL/TLS handling is delegated entirely to the Docker proxy.

• Certbot Email: [email protected] (configured via environment variable CERTBOT_EMAIL).

Permission Settings¶

File and directory permissions are set to ensure the web server can execute scripts while maintaining security.

Location of Configuration Files and Data¶

Key configuration and data files reside in specific directories:

• Nginx Virtual Host: /etc/nginx/sites-available/ispconfig.vhost

• Docker Compose: /root/nginx/compose.yml

• Environment Variables for Proxy: /data/nginx/nginx-certbot.env

• User Proxy Configs: /data/nginx/user_conf.d/ispconfig<Server ID>.hostkey.in.conf

• Installation Flag: /usr/local/ispconfig/interface/lib/config.inc.php

• Database: Local dbispconfig database on localhost.

Available Ports for Connection¶

The following ports are configured and open for external access:

Starting, Stopping, and Updating¶

The services are managed via systemd for the host and Docker for the proxy.

• Nginx Host Service:

  • Reload configuration:

    systemctl reload nginx
    

  • Check configuration validity:

    nginx -t
    

• Docker Proxy Stack:

  • Start/Restart:

    cd /root/nginx && docker compose up -d
    

  • Stop:

    cd /root/nginx && docker compose stop
    

• Unattended Upgrades:

  • The system is configured with unattended-upgrades enabled to automatically install security updates.

• Package Management:

  • Update APT cache:

    apt update
    

  • Fix package states:

    dpkg --configure -a