The management of IP address space in modern network infrastructure represents a critical challenge for systems administrators, network engineers, and DevOps practitioners. As networks expand in complexity, involving dozens or hundreds of VLANs, subnets, and diverse host types, manual tracking becomes not only inefficient but prone to catastrophic errors such as IP address conflicts. phpIPAM, an open-source web-based IP Address Management (IPAM) application, addresses this need by providing a lightweight, simple, and robust interface for planning and tracking IP address space, subnets, and VLANs across a network. Developed and maintained by Miha Petkovsek and released under the GNU General Public License v3 (GPL v3), phpIPAM has become a standard tool for network administration. However, the traditional installation of phpIPAM requires a LAMP stack (Linux, Apache, MySQL, PHP), which presents a significant barrier to entry for many network administrators who possess limited experience with complex server configuration. To mitigate this friction, the phpIPAM project provides officially maintained Docker images that simplify the creation and maintenance of a working phpIPAM environment. This guide provides an exhaustive analysis of deploying phpIPAM using Docker and Docker Compose, covering single-host setups, multi-host architectures, security hardening with Docker Secrets, reverse proxy configurations, and the specific technical requirements for containerized operation.
The Role and Architecture of IP Address Management
IP Address Management (IPAM) is a discipline within network administration that involves the planning, tracking, and automation of IP address space and other network resources. For system administrators and network engineers, the primary objective of an IPAM solution is to maintain accurate visibility into network resources. This includes allocating address space, preventing IP address conflicts, and managing the lifecycle of IP assignments. In large-scale environments, managing VLANs can become a logistical nightmare; with hundreds of virtual local area networks spread across multiple physical locations, the risk of misconfiguration increases exponentially. phpIPAM provides a centralized interface that aggregates this data, allowing administrators to see exactly what IP addresses are assigned, which are available, and where resources are located within the network topology.
The application itself is designed to be light and simple, focusing on usability for its primary audience: network administrators. This design philosophy extends to its distribution model. Recognizing that typical users may lack deep expertise in LAMP stack configuration, the phpIPAM project offers Docker images that abstract away the complexity of installing and configuring Apache, PHP, and MySQL separately. This approach prioritizes simplicity over complexity, meaning that while the Docker images cover the vast majority of standard use cases, some advanced, non-standard use cases may not be supported directly by these containers. For those requiring highly customized environments, the project directs users to install phpIPAM on a virtual machine using the traditional instructions found on the official phpIPAM homepage.
Containerized Deployment: The phpipam-www Image
The primary entry point for deploying phpIPAM in a containerized environment is the phpipam/phpipam-www image, available on Docker Hub. This image serves as the frontend, containing the Apache web server and the PHP application code. It is crucial to understand that this image does not contain the database; it must be linked to a separate MySQL or MariaDB container to function. The Docker Hub repository for phpipam/phpipam-www indicates that the image has been pulled over 10 million times, reflecting its widespread adoption in the industry. The image is updated frequently, with recent pushes occurring approximately every 15 hours, ensuring that security patches and application updates are integrated promptly.
The architecture of the Dockerized solution typically involves two distinct components: the frontend web container (phpipam-www) and the backend database container (mysql). In some advanced configurations, a third component, phpipam-cron, is introduced. This cron container is responsible for scheduled network discovery jobs, such as pinging hosts to verify their status or running SNMP queries to gather device information. It is imperative to note that while multiple replicas of the phpipam-www container can be deployed and load-balanced to handle high traffic, only a single running replica of the phpipam-cron container should be deployed. Running multiple cron instances simultaneously can lead to race conditions, duplicate database entries, and excessive network load during discovery scans.
Prerequisites and Security Considerations for Container Execution
Before deploying the containers, it is essential to understand the specific technical requirements and security implications of running phpIPAM in a Docker environment. One of the most critical constraints is that rootless Docker is not supported by the official phpIPAM images. The application requires certain capabilities that are typically only available to the root user within the container. Specifically, when running under Docker, the NET_ADMIN and NET_RAW container capabilities are required. These capabilities are necessary for the application to perform ping operations and SNMP functionality, which are core features for network discovery and host status verification. Without these capabilities, the IPAM tool cannot accurately reflect the real-time status of network devices, rendering the discovery features ineffective.
For those deploying phpIPAM in Kubernetes environments, the security configuration differs slightly from standard Docker. In Kubernetes, the pod specification must include allowPrivilegeEscalation=true to enable the necessary network capabilities. This setting allows the container processes to gain more privileges than their parent process, which is required for the low-level network operations that phpIPAM performs. However, administrators should be aware that enabling privilege escalation introduces security risks and should be done with caution, ensuring that the namespace and network policies are strictly enforced.
Single-Host Deployment Using Docker CLI
The most straightforward method for deploying phpIPAM is using the Docker command-line interface (CLI) to run two separate containers: one for the MySQL database and one for the phpIPAM web frontend. This method is suitable for small deployments, testing, or environments where Docker Compose is not available. The first step is to deploy the MySQL database. It is recommended to use MySQL version 5.6, as indicated in the legacy documentation and common deployment patterns, although newer versions may be compatible depending on the phpIPAM version. The data must be persisted on the host system to prevent loss in case of container recreation.
To run the MySQL database container, the following command is used:
bash
docker run --name phpipam-mysql -e MYSQL_ROOT_PASSWORD=my-secret-pw -v /my_dir/phpipam:/var/lib/mysql -d mysql:5.6
In this command, the --name flag assigns a recognizable name to the container, which is crucial for linking. The -e flag sets the environment variable MYSQL_ROOT_PASSWORD, which must be replaced with a strong, secure password. The -v flag mounts a volume from the host system (/my_dir/phpipam) to the container's data directory (/var/lib/mysql), ensuring that the database files are stored persistently on the host. The -d flag runs the container in detached mode.
Once the database container is running, the phpIPAM frontend container can be deployed. This container must be linked to the MySQL container to resolve the hostname and establish connectivity. The command for this step is:
bash
docker run -ti -d -p 80:80 -e MYSQL_ENV_MYSQL_ROOT_PASSWORD=my-secret-pw --name ipam --link phpipam-mysql:mysql pierrecdn/phpipam
This command exposes port 80 on the host to port 80 in the container, allowing web access. The -e flag again sets the root password, which must match the one used in the MySQL container. The --link flag connects the ipam container to the phpipam-mysql container, mapping the host alias mysql to the database container. The image used here is pierrecdn/phpipam, which is the older community-maintained image, but the official phpipam/phpipam-www image can also be used with similar parameters.
After the containers are running, the user must browse to http://<ip>[:<specific_port>]/install/ to begin the web-based installation. The installation process consists of several steps. Step 1 involves choosing "Automatic database installation." Step 2 requires re-entering the connection information, specifically the root password. It is worth noting that these first two steps could potentially be swapped or automated by patching the phpIPAM source code, as referenced in issue #25 on the phpipam/phpipam GitHub repository. Step 3 involves configuring the admin user password for the phpIPAM application itself. Once these steps are completed, the system is ready for use.
Automated Deployment Using Docker Compose
For more robust and reproducible deployments, Docker Compose is the preferred method. Docker Compose allows the definition of the multi-container application in a single YAML file, making it easy to deploy, update, and manage the environment. This approach is particularly beneficial for ensuring consistency across development, testing, and production environments. A typical Docker Compose configuration for phpIPAM includes two services: mysql and ipam.
The following is an example of an all-in-one YAML deployment descriptor:
yaml
version: '2'
services:
mysql:
image: mysql:5.6
environment:
- MYSQL_ROOT_PASSWORD=my-secret-pw
restart: always
volumes:
- db_data:/var/lib/mysql
ipam:
depends_on:
- mysql
image: pierrecdn/phpipam
environment:
- MYSQL_ENV_MYSQL_USER=root
- MYSQL_ENV_MYSQL_ROOT_PASSWORD=my-secret-pw
- MYSQL_ENV_MYSQL_HOST=mysql
ports:
- "80:80"
volumes:
db_data:
In this configuration, the mysql service uses the mysql:5.6 image and sets the root password via an environment variable. The restart: always policy ensures that the database container restarts automatically if it crashes or if the host reboots. The volume db_data is defined at the end of the file and mounted to /var/lib/mysql within the container, ensuring data persistence.
The ipam service depends on the mysql service, ensuring that the database is started before the web application. The environment variables MYSQL_ENV_MYSQL_USER, MYSQL_ENV_MYSQL_ROOT_PASSWORD, and MYSQL_ENV_MYSQL_HOST are passed to the phpIPAM container to facilitate the automatic database connection. The MYSQL_ENV_MYSQL_HOST is set to mysql, which corresponds to the service name of the database container, allowing Docker's internal DNS to resolve the hostname. The port mapping "80:80" exposes the web interface on port 80 of the host.
To deploy this configuration, the user simply runs:
bash
docker-compose up -d
This command starts the containers in detached mode, bringing up both the database and the web interface. After the containers are up, the installation process is the same as with the CLI method: browse to the /install/ endpoint and follow the three-step wizard.
Advanced Configuration: Multi-Host and Reverse Proxy
As network environments grow, a single-host Docker deployment may not suffice. Administrators may wish to distribute the phpIPAM components across multiple Docker hosts for redundancy or performance reasons. This is known as a multi-host container configuration. In this setup, the frontend web container and the backend database container can reside on different physical or virtual machines. The primary configuration requirement here is to ensure that the phpIPAM container can reach the MySQL database. This involves telling phpIPAM the IP address or hostname of the database container's host and configuring the firewall rules to allow traffic on the MySQL port (typically 3306) between the hosts.
For production environments, exposing the phpIPAM web interface directly on port 80 is often insufficient due to security and SSL/TLS requirements. Native SSL support is not built into the basic phpIPAM Docker images to maintain simplicity. Instead, native SSL support can be achieved by using reverse proxy Docker images available on Docker Hub, such as HAProxy, Nginx Proxy Manager, or Traefik. These reverse proxies terminate the SSL connection and forward the traffic to the phpIPAM container on port 80.
When using a reverse proxy, additional configuration is required within phpIPAM. The base URI may need to be adjusted to reflect the proxy's domain name. Additionally, URL rewrites might be necessary to ensure that internal links and assets are resolved correctly. Environment variables in the Docker Compose file or the container runtime can be used to pass these configuration details to the phpIPAM application. For example, if using Traefik, labels in the Docker Compose file can define the router, service, and entry points for the phpIPAM container.
Securing phpIPAM with Docker Secrets
Security is a paramount concern when managing network infrastructure data. Storing sensitive information such as database passwords, API keys, and other credentials in plain text within Docker Compose files or environment variables is a significant security risk. Docker provides a feature called Docker Secrets, which allows for the secure storage and management of sensitive data. Docker secrets are stored in the swarm manager's overlay2 filesystem and are passed to containers via a tmpfs mount, ensuring they are not written to disk in the container's filesystem.
To use Docker Secrets with phpIPAM, the secret must first be created. This is done by writing the sensitive data to a file and then creating a secret from that file. For example, to create a secret for the MySQL root password:
bash
echo -n "your_password" > db_password.txt
docker secret create db_password db_password.txt
In this command, db_password.txt contains the password, and db_password is the name of the secret. Once the secret is created, it can be referenced in the Docker Compose file. However, it is important to note that Docker Secrets are only available in Docker Swarm mode. For standard Docker Compose deployments without Swarm, secrets are not directly supported in the same way, and alternative methods such as encrypted environment variable files or external secret management systems (like HashiCorp Vault) may be required.
In a Swarm deployment, the Docker Compose file would reference the secret as follows:
yaml
secrets:
db_password:
external: true
services:
mysql:
image: mysql:5.6
environment:
MYSQL_ROOT_PASSWORD_FILE: /run/secrets/db_password
secrets:
- db_password
This approach ensures that the password is never exposed in plain text in the configuration files or environment variables, significantly enhancing the security posture of the phpIPAM deployment.
Image Versions and Maintenance Branches
The phpIPAM Docker image is available in several versions, each corresponding to a specific maintenance branch of the application. Understanding these versions is crucial for choosing the right balance between stability and new features. The latest tag tracks the latest stable release along with Alpine Linux security updates. This is the recommended tag for most production deployments, as it provides the most recent features while maintaining stability.
The 1.8x tag tracks the 1.8 git maintenance branch, also including Alpine Linux security updates. This is useful for users who want to stay on a specific major version while receiving security patches. Older tags such as 1.7x, 1.6x, 1.5x, and 1.4x track their respective git maintenance branches but are considered obsolete. These tags are retained for legacy support but are not recommended for new deployments due to lack of recent security updates and feature improvements.
The nightly tag represents a nightly git development snapshot. This is intended for testing and development purposes only and is not suitable for production environments, as it may contain unstable or broken code. The image sizes for these tags vary, with the latest image being approximately 58-60 MB for both amd64 and arm64 architectures. This small footprint is one of the advantages of using Alpine Linux as the base image, reducing the attack surface and resource consumption.
Troubleshooting and Common Issues
Despite the simplicity of the Docker deployment, users may encounter issues. One common problem is the inability to connect to the database. This is often due to incorrect environment variables or firewall rules. It is essential to verify that the MYSQL_ENV_MYSQL_ROOT_PASSWORD in the phpIPAM container matches the MYSQL_ROOT_PASSWORD in the MySQL container. Additionally, the MYSQL_ENV_MYSQL_HOST must resolve to the correct IP address or hostname. In Docker Compose, this is usually the service name of the database container.
Another issue is the lack of network connectivity for ping and SNMP checks. As mentioned earlier, the NET_ADMIN and NET_RAW capabilities are required. If these are not enabled, the host status indicators in phpIPAM will not update correctly. Users can verify that these capabilities are enabled by inspecting the container configuration. In Docker Compose, this can be done by adding the cap_add directive:
yaml
ipam:
cap_add:
- NET_ADMIN
- NET_RAW
For users deploying on Kubernetes, the securityContext must include allowPrivilegeEscalation: true. If these settings are not present, the container will not have the necessary permissions to perform raw socket operations, resulting in failed discovery scans.
Conclusion
The deployment of phpIPAM using Docker and Docker Compose offers a streamlined, efficient, and secure method for implementing IP Address Management in modern network environments. By abstracting the complexity of LAMP stack configuration, the official Docker images allow network administrators to focus on network optimization rather than server maintenance. The ability to deploy using simple CLI commands or comprehensive Docker Compose files provides flexibility for various deployment scenarios, from small home labs to large enterprise networks. The inclusion of features such as Docker Secrets for secure credential management, support for multi-host architectures, and compatibility with reverse proxies for SSL termination ensures that the solution can scale and adapt to the evolving needs of the network. While certain advanced use cases may require traditional VM-based installations, the Dockerized solution covers the vast majority of requirements with a high degree of reliability and ease of use. As the network landscape continues to grow in complexity, tools like phpIPAM, when deployed correctly in containerized environments, provide the visibility and control necessary to maintain a stable and conflict-free IP address space.