/docker-ispconfig

ISPConfig hosting control panel, packaged as a Docker container (with caveats)

Primary LanguageShell

Archived! I've now moved to Proxmox, meaning I'm using ISPConfig in a VM with a standard install. This now makes this project redundant

ispconfig-docker

This is a fork of Unimock's excellent work on implementing a containerized version of the ISPConfig web-hosting suite.

Caveats

  • This project is suitable for single-site usage, only! Chiefly, this is because of the lack of support for the quota tool
  • Installation requires considerable user input, and is not recommended for anyone not comfortable with Linux
  • Getting this running will probably be challenging! However, once up and running it functions excellently
  • This project is unsupported!
    • That said, contributions towards making this project more user-friendly are welcomed! Issues, Pull Requests
    • Improvements to this document are particularly welcomed!

Changes from the base project

  • Updated to Debian 11 (Bullseye)
  • Support for a non-local MYSQL server
  • Out-of-the-box support for a custom SSL certificate
  • Integration tests running on Docker Cloud
  • More build options, such as optional install of PHPMyAdmin
  • Some improvements to email security
  • Extra Apache options such as enabling modules and including supplementary vhosts
  • (Hopefully) numerous bug fixes and tweaks
  • This version currently makes no changes to Unimock's helper do script. In this version it's currently out-of-use; this may change in the future however!

How to install (rough guide)

  • Fork this repository
  • Customize the build options in your docker-compose.yml
  • Or, rename the file to something like docker-compose.build.yml, and then create a separate docker-compose.yml, using the extends functionality to create your configuration:
version: '3.9'

services:

  ispconfig:
    extends:
      file: docker-compose.build.yml
      service: ispconfig
    build:
      args:
        BUILD_CERTBOT: "no"
        BUILD_HOSTNAME: "ispconfig"
        BUILD_ISPCONFIG_USE_SSL: "no"
        ... etc
  • Run the build
    • docker compose build .
    • If using extends: docker compose -f docker-compose.build.yml build
  • Start the container: docker compose up -d
  • Initally test the build by connecting to the ispconfig control panel: http://<localhost>:8080
  • Do addition verification!
  • Ideally, push your image to Docker Cloud
  • Mount persistant volumes and judiciously copy configuration files from the container (see below)

Persistent data

  • Unlike Unimock's original, I've taken a more standard approach based around normal volume mounting. With some careful and judicious use of mounts, you can hopefully get a simpler setup. Here is an example of my full list of mounts:
volumes:
  - /docker/appdata/ispconfig/etc:/etc
  - /docker/appdata/ispconfig/ftp:/var/ftp
  - /docker/appdata/ispconfig/lib:/var/lib
  - /docker/appdata/ispconfig/log:/var/log
  - /docker/appdata/ispconfig/log/roundcube:/opt/roundcube/logs
  - /docker/appdata/ispconfig/mail:/var/mail
  - /docker/appdata/ispconfig/spool:/var/spool
  - /docker/appdata/ispconfig/supplementary:/etc/apache2/supplementary:ro
  - /docker/appdata/ispconfig/vmail:/var/vmail
  - /docker/appdata/ispconfig/www:/var/www
  # Roundcube
  - /docker/appdata/ispconfig/roundcube/config.inc.php:/opt/roundcube/config/config.inc.php
  - /docker/appdata/ispconfig/roundcube/plugins:/opt/roundcube/plugins
  # Overlays
  - /docker/services/ISPConfig/build/supervisor:/etc/supervisor
  - /docker/appdata/ispconfig/config/database.config.inc.php:/usr/local/ispconfig/server/lib/mysql_clientdb.conf
  - /docker/appdata/ispconfig/config/interface.config.inc.php:/usr/local/ispconfig/interface/lib/config.inc.php
  - /docker/appdata/ispconfig/config/server.config.inc.php:/usr/local/ispconfig/server/lib/config.inc.php
  # System
  - /etc/letsencrypt:/etc/letsencrypt:ro
  - /etc/localtime:/etc/localtime:ro

Build Options

The following are particular important for your customization

Argument Default Comments
BUILD_HOSTNAME myhost.test.com The hostname to use for the build, including ISPConfig
BUILD_ISPCONFIG_USE_SSL yes Should ISPConfig use SSL? Note: this will be a self-signed certificate. See Reverse Proxy section
BUILD_PHPMYADMIN yes Include PHPMyAdmin
BUILD_CERTBOT yes Include/exclude Let's Encrypt
BUILD_REDIS yes Install Redis? Required for Rspamd, but can be configured to another host with REDIS_HOST environmental variable
BUILD_TZ Europe/London Timezone for the container
BUILD_LOCALE en_GB POSIX (ISO 15897) locale code for the container. UTF-8 is required and will automatically be appended

Less-essential options

Argument Default Comments
BUILD_ROUNDCUBE_DB roundcube Roundcube database name
BUILD_ROUNDCUBE_USER roundcube Roundcube database username
BUILD_ROUNDCUBE_PW secretpassword Roundcube database password
BUILD_PHPMYADMIN_USER phpmyadmin PHPMyAdmin database username
BUILD_PHPMYADMIN_PW phpmyadmin PHPMyAdmin database password
BUILD_PHPMYADMIN_VERSION 4.9.0.1 Version of PHPMyAdmin to install
BUILD_MYSQL_PW pass Root password for MariaDB local server, if installed
BUILD_ISPCONFIG_MYSQL_DATABASE dbispconfig ISPConfig database name
BUILD_ISPCONFIG_PORT 8080 ISPConfig web app port number (control panel, PHPMyAdmin, Roundcube)

Using a remote SQL server

It is possible to connect to a remote SQL server during the build. This would require using the compose file extra_hosts option. However, this is problematic; in particular ISPConfig expects its database not to exist at installation. For myself, I followed the following manual strategy:

  • Build the container with the Mariadb server
    • BUILD_MYSQL_HOST="localhost"
  • Dump databases and users from the container
  • Import into shared SQL server
  • Use the MYSQL_HOST environmental var to repoint the container to your shared server at runtime
  • Disable the container's MariaDB server using the DISABLED_SERVICES environmental variable
Argument Default Comments
BUILD_MYSQL_HOST localhost Hostname of the SQL server. When localhost, this will build MariaDB Server
BUILD_MYSQL_REMOTE_ACCESS_HOST 172.%.%.% When BUILD_MYSQL_HOST != localhost, this will configure database users to allow connections from this host pattern.
BUILD_ISPCONFIG_DROP_EXISTING no DANGER: If existing ISPConfig tables are found in the database, they will be dropped before installation! Without this, the installation fails. Of course data will be lost!

Options not recommended for individual customization

Argument Default Comments
BUILD_ISPCONFIG_VERSION Dockerfile Version of ISPConfig to install
BUILD_ROUNDCUBE_VERSION Dockerfile Version of Roundcube to install
BUILD_ROUNDCUBE_DIR /opt/roundcube Path where Roundcube will be installed. Don't change!

Currently non-functional

Argument Default Comments
BUILD_PRINTING no Install print support

Environmental Variables (runtime options)

Argument Default / Example Comments
SSL_CERT none Path to a custom SSL certificate (must be mounted to the container)
SSL_CHAIN none Path to a custom SSL certificate chain (must be mounted to the container)
SSL_KEY none Path to a custom SSL private key (must be mounted to the container)
APACHE_SUPPLEMENTARY_VHOSTS /etc/apache2/supplementary/*.vhost Adds an include statement to the Apache config to add supplementary vhosts
APACHE_ENABLE_MODS macro,proxy_balancer,proxy_http Apache standard modules to enable. Note this won't install any non-standard mods
MYSQL_HOST host Reconfigure services to point to this SQL server
HOSTNAME myhost.test.com Runtime hostname
HOSTNAME_EMAIL mail.myhost.test.com Runtime hostname for email
DISABLED_SERVICES unbound Space-separated list of installed services to disable at runtime. Complete list in the Dockerfile
POSTGREY_DELAY 300 Postgrey delay time
POSTGREY_MAX_AGE 35 Postgrey maximum age
POSTGREY_TEXT "Delayed by postgrey" Postgrey delay message
REDIS_HOST localhost Hostname for Redis. If localhost, requires BUILD_REDIS = "yes"
APACHE_DISABLE_DEFAULT_SITE no If yes, disables Apache's default site

Non-functional

Argument Default Comments
MAILMAN_EMAIL_HOST test.com Mailman host
MAILMAN_EMAIL email@test.com Mailman address
MAILMAN_PASS pass Mailman password
LANGUAGE en Mailman language

Recommendations

Use installed Apache as a reverse proxy

Disable SSL for ISPConfig and use Apache as a reverse proxy to access ISPConfig and associated installed apps (Roundcube, PHPMyAdmin)

  • BUILD_ISPCONFIG_USE_SSL=no
  • APACHE_SUPPLEMENTARY_VHOSTS=/etc/apache2/supplementary/*.vhost (pointing to a mounted volume with the vhosts)
<Macro Subdomain $host $target>
  <VirtualHost *:443>
    ServerName $host.myhostname.blah
    ProxyPass "/" "$target"
    ProxyPassReverse "/" "$target"
  </VirtualHost>
</Macro>

Use Subdomain ispconfig https://localhost:8080/
Use Subdomain webmail http://localhost:8080/webmail/
Use Subdomain phpmyadmin http://localhost:8080/phpmyadmin/

UndefMacro Subdomain