The pursuit of a self-hosted, database-less documentation system often leads technical enthusiasts and enterprise architects to DokuWiki. Developed in 2004, DokuWiki represents a paradigm shift from modern wiki software by eschewing the requirement for a relational database management system (RDBMS). Instead, it utilizes a flat-file system where data is stored in plain text files on the local filesystem, utilizing a Markdown-like syntax for formatting. This architectural decision makes it exceptionally portable and resilient, yet it introduces unique challenges when transitioning the software into a containerized environment.
Dockerizing DokuWiki is not as straightforward as deploying a standard microservice. Because the application was conceived in an era preceding containerization, its original design did not account for the ephemeral nature of container filesystems. For years, the ecosystem was fragmented, with nearly 400 unofficial images appearing on Docker Hub, creating a landscape of "snowflakes"—configurations that are unique, difficult to reproduce, and hard to maintain. However, the evolution of official images and the refinement of community-driven distributions, such as those from LinuxServer.io and CrazyMax, have provided multiple pathways for deployment.
Whether an administrator is migrating from a legacy Virtual Machine (VM) or Linux Container (LXC) setup to reduce server overhead via Ansible, or a novice is looking for a simple home lab project, understanding the nuances of volume mapping, PHP configuration, and reverse proxy integration is critical. The goal is to move away from fragile installations toward a robust, version-controlled infrastructure where the wiki's state is decoupled from the application runtime.
The DokuWiki Containerization Dilemma
DokuWiki is fundamentally a collection of PHP files served by a web server, such as Apache or Nginx. In a traditional installation, these files and the resulting data reside on a persistent disk. In a Docker environment, any data written to the container's writable layer is lost upon container deletion. Therefore, the core challenge of running DokuWiki in Docker is ensuring that the /storage or /var/www/html directories are mapped to persistent volumes.
The "DokuWiki in Docker problem" stems from the fact that the software predates the industry's shift toward immutable infrastructure. Early attempts to containerize the software resulted in a flood of unofficial images that often lacked proper security patching or optimized PHP configurations. Andreas Gohr, the creator of DokuWiki, has historically suggested that the most reliable method for deployment is to utilize a generic PHP and web server container and then install the DokuWiki source into a persistent volume. This approach ensures that the user maintains full control over the installation process and that the data remains independent of the specific image version.
Comprehensive Analysis of Available Docker Images
Depending on the requirements for security, architecture, and ease of maintenance, users can choose from several distinct images.
The Official DokuWiki Image
The official image is based on the PHP Apache foundation and is designed specifically for integration within a larger infrastructure. It is not intended for standalone use on a public IP without a protective layer.
| Feature | Specification |
|---|---|
| Base Image | Official PHP Apache |
| Default Port | 8080 |
| Primary Volume | /storage |
| Health Check | Runs basic checks every 30 seconds (3 retries) |
| PHP Config | Standard production php.ini |
| Supported Tags | stable, oldstable, master, latest |
This image is engineered to work behind a reverse proxy. The reverse proxy is responsible for SSL termination and authentication, which protects the container from direct internet exposure. It includes several pre-configured optimizations, such as xsendfile for efficient file delivery, ImageMagick for image processing, and rewriting rules to enable "nice URLs." Additionally, it incorporates the Farmer plugin to provide farming support.
The LinuxServer.io Distribution
LinuxServer.io provides a highly optimized image that focuses on permission management and multi-architecture support.
| Architecture | Tag Prefix | Availability |
|---|---|---|
| x86-64 | amd64- |
Available |
| ARM64 | arm64v8- |
Available |
This image is particularly useful for those running diverse hardware, such as Raspberry Pis or ARM-based cloud instances. It utilizes specific environment variables to handle user permissions, which prevents the common "permission denied" errors associated with Docker volumes on Linux hosts.
The CrazyMax Distribution
For those prioritizing a minimal footprint, the CrazyMax image provides an alternative based on Alpine Linux.
| Attribute | Detail |
|---|---|
| Base OS | Alpine Linux |
| Image Size | 34.2 MB |
| Target Tag | edge |
The use of Alpine Linux significantly reduces the attack surface and the memory overhead of the container, making it an ideal choice for resource-constrained environments.
Deployment Methodology: The Official Image Path
Deploying the official dokuwiki/dokuwiki:stable image requires a focus on volume persistence and user identification. The image allows the container to run as a non-root user, which is a security best practice.
To launch the container via the CLI, the following command is utilized:
bash
docker run -p 8080:8080 --user 1000:1000 -v /path/to/storage:/storage dokuwiki/dokuwiki:stable
In this command, the --user 1000:1000 flag ensures that the process inside the container maps to a specific user on the host system. It is imperative that the host directory mapped to /storage is writable by the UID 1000 to avoid application crashes during the installation phase.
The official image also allows for the tuning of PHP settings through environment variables, removing the need to manually edit php.ini inside the container:
PHP_UPLOADLIMIT: Controls the maximum size of uploaded files (Default: 128M).PHP_MEMORYLIMIT: Sets the memory limit for PHP processes (Default: 256M).PHP_TIMEZONE: Defines the timezone for the application.
Deployment Methodology: The LinuxServer.io Path
The LinuxServer.io image is designed for ease of integration via docker-compose. It leverages PUID and PGID variables to ensure that the files created on the host are owned by the correct user.
The following docker-compose.yml configuration is recommended:
yaml
services:
dokuwiki:
image: lscr.io/linuxserver/dokuwiki:latest
container_name: dokuwiki
environment:
- PUID=1000
- PGID=1000
- TZ=Etc/UTC
volumes:
- /path/to/dokuwiki/config:/config
ports:
- 80:80
- 443:443 #optional
restart: unless-stopped
After the initial deployment, the administrator must navigate to http://$IP:$PORT/install.php to complete the setup. Once the installation is finished, the container should be restarted. To enable "nice URLs," the admin must log in and change the "Use nice URLs" setting in the Configuration Settings panel to .htaccess and enable the "Use slash as namespace separator in URLs" option.
Deployment Methodology: The Manual "Deep-Dive" Path
For users who prefer the method recommended by the creator of DokuWiki, the process involves deploying a generic PHP-Apache environment and manually injecting the software. This method eliminates dependence on pre-baked images that may contain unnecessary bloat.
The docker-compose.yml for this method uses the Debian-based Bullseye image:
```yaml
version: '3'
services:
dokuwiki:
containername: dokuwiki
image: php:7-apache-bullseye
restart: unless-stopped
networks:
- dokuwiki
ports:
- '8888:80'
volumes:
- 'dokuwikiconfig:/var/www/html'
networks:
dokuwiki:
volumes:
dokuwiki_config:
driver: local
```
Once the container is running, the administrator must perform a series of manual steps inside the container's shell to install the software.
First, access the container:
bash
docker exec -it dokuwiki /bin/bash
Next, execute the installation sequence:
bash
cd /var/www/html
curl --remote-name https://download.dokuwiki.org/src/dokuwiki/dokuwiki-stable.tgz
tar -xzvf dokuwiki-stable.tgz --strip-components=1
rm dokuwiki-stable.tgz
chown -R www-data:www-data /var/www/
Finally, the installation is completed by visiting http://your_docker_server_IP:8888/install.php.
Technical Operational Considerations
Running DokuWiki in a container introduces specific operational requirements regarding networking and maintenance.
Mail Server Integration
None of the analyzed Docker images include a built-in mail server. Because containers are designed to run a single process, adding a full Mail Transfer Agent (MTA) like Postfix or Exim would violate the microservices principle and increase image size. To enable email notifications and password resets, users must configure DokuWiki to use an external SMTP server. This is most effectively achieved by installing the SMTP plugin within the DokuWiki admin panel.
Update and Upgrade Strategies
Updating a containerized DokuWiki differs from updating a traditional installation. While the standard method involves downloading a new .tgz file and overwriting the current installation, doing so inside a container is cumbersome.
The recommended approach for Docker users is to install the official Upgrade plugin. This allows updates to be managed directly from the web interface, ensuring that the underlying filesystem remains consistent without requiring the administrator to manually enter the container and run tar commands.
Resource Management and Performance
DokuWiki's lack of a database makes it exceptionally fast for reads, as it leverages the OS filesystem cache. However, PHP memory limits can become a bottleneck when dealing with very large pages or complex plugins. By using the PHP_MEMORYLIMIT environment variable in the official image, administrators can scale the memory allocation to match their specific workload.
Comparison of Deployment Strategies
| Strategy | Best For | Pros | Cons |
|---|---|---|---|
| Official Image | Enterprise/Proxy setups | High stability, optimized PHP | Requires reverse proxy for security |
| LinuxServer.io | Home Lab/ARM users | Easy permission handling, multi-arch | Larger image size |
| Manual Install | Advanced Users/Purists | Full control, minimal bloat | Manual setup steps required |
| CrazyMax/Alpine | Resource-constrained hosts | Extremely small footprint | Less common, specific Alpine quirks |
Conclusion
The transition of DokuWiki into the Docker ecosystem illustrates the tension between legacy software design and modern infrastructure requirements. While the application's flat-file architecture was originally a hurdle for containerization, it has ultimately become its greatest strength, allowing for effortless backups and migrations via simple volume mapping.
The most robust deployment path currently available is the use of the official image paired with a reverse proxy, as it balances security with the performance optimizations of xsendfile and .htaccess rewriting. For those operating on ARM hardware or requiring simplified permission management, the LinuxServer.io image provides a seamless experience. Meanwhile, the manual installation method remains the gold standard for those who wish to follow the creator's original advice and maintain a lean, transparent stack.
Ultimately, the success of a DokuWiki Docker deployment hinges on the correct implementation of persistent volumes. Without a dedicated volume for /storage or /var/www/html, the wiki is merely a temporary instance. When configured correctly, DokuWiki in Docker provides a powerful, database-free knowledge management system that is easy to back up, scale, and maintain across any environment.