DokuWiki Production Deployment — Nginx Config, Monitoring, Scaling, and CI/CD

In this tutorial, you'll learn how to deploy DokuWiki in production, including Nginx configuration, monitoring and alerting, scaling strategies for high traffic, CI/CD pipeline integration for automated deployments, and a complete go-live checklist.

What You'll Learn

• Production Nginx configuration
• Monitoring and alerting setup
• Scaling strategies (horizontal and vertical)
• CI/CD pipeline integration
• Deployment automation
• Go-live checklist
• Production troubleshooting

Why It Matters

Moving from a development setup to production requires more than just copying files. Production wikis need proper web server configuration, monitoring, backups, and a deployment process. A well-architected production deployment ensures your wiki is fast, available, and maintainable for years.

Real-World Use

A company launches their public documentation wiki on DokuWiki. They configure Nginx with caching, set up Uptime Robot monitoring (5-minute checks), configure automated backups via cron, and create a CI/CD pipeline that deploys template and plugin updates from a Git Repository. The wiki serves 10,000 daily visitors with 99.9% uptime.

Learning Path

flowchart LR
  A[Security] --> B[Production]
  B --> C[Conclusion]
  C --> D[Next Steps]

Production Nginx Configuration

Complete Nginx Site Configuration

# /etc/nginx/sites-available/wiki.example.com

server {
    listen 443 ssl http2;
    server_name wiki.example.com;

    # SSL configuration
    ssl_certificate /etc/letsencrypt/live/wiki.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/wiki.example.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    ssl_prefer_server_ciphers on;

    # Security headers
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;
    add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'" always;

    # Root directory
    root /var/www/html/wiki;
    index index.php;

    # Deny access to sensitive directories
    location ~ /(data|conf|bin|inc|vendor)/ {
        deny all;
        return 403;
    }

    # Deny access to .htaccess files
    location ~ /\.ht {
        deny all;
    }

    # DokuWiki rewrite rules
    location / {
        try_files $uri $uri/ @dokuwiki;
    }

    location @dokuwiki {
        rewrite ^/_media/(.*) /lib/exe/fetch.php?media=$1 last;
        rewrite ^/_detail/(.*) /lib/exe/detail.php?media=$1 last;
        rewrite ^/_export/([^/]+)/(.*) /doku.php?do=export_$1&id=$2 last;
        rewrite ^/(.*) /doku.php?id=$1 last;
    }

    # PHP processing
    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param PHP_VALUE "upload_max_filesize = 64M \n post_max_size = 64M";
        include fastcgi_params;
    }

    # Cache static assets
    location ~* \.(jpg|jpeg|png|gif|ico|css|js|svg|woff|woff2)$ {
        expires 30d;
        add_header Cache-Control "public, immutable";
        access_log off;
    }

    # Gzip compression
    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml;
    gzip_min_length 1000;
    gzip_vary on;
}

# HTTP redirect to HTTPS
server {
    listen 80;
    server_name wiki.example.com;
    return 301 https://$server_name$request_uri;
}

Monitoring Setup

Uptime Monitoring

Configure HTTP(S) monitoring to check:

• Wiki home page returns 200
• Login page loads
• API endpoint responds

Server Monitoring

Monitor these metrics:

CPU usage (alert at >80% for 5 min)
Memory usage (alert at >85%)
Disk usage (alert at >80%)
PHP-FPM pool status (alert on max children reached)
Load average (alert when > number of CPU cores)

Log Monitoring

# Monitor PHP error log for critical errors
tail -f /var/log/php8.1-fpm.log | grep -i error

# Monitor DokuWiki's own logs if configured
tail -f /var/www/html/wiki/data/log/*.log

Performance Monitoring

# Install and configure New Relic or similar APM
# Or use basic timing logs

# Add to DokuWiki to log slow pages:
# See Lesson 38 for performance logging code

Scaling Strategies

Vertical Scaling (Larger Server)

DokuWiki is I/O-bound. Upgrade:

• CPU: More cores help with concurrent requests
• RAM: 2-4 GB for medium wikis
• Storage: SSD (NVMe for best performance)

Horizontal Scaling (Multiple Servers)

For high-traffic wikis, scale across multiple servers:

Load Balancer
    |
    +-- Web Server 1 (PHP + DokuWiki files)
    |
    +-- Web Server 2 (PHP + DokuWiki files)
    |
    +-- Web Server N (PHP + DokuWiki files)
    |
    +-- NFS / GlusterFS (shared data/ directory)

Shared Filesystem for Multi-Server

# Mount shared storage on all web servers
# /etc/fstab on each web server
nfs-server:/data/wiki-data /var/www/html/wiki/data nfs defaults,noatime 0 0
nfs-server:/data/wiki-conf /var/www/html/wiki/conf nfs defaults,noatime 0 0

Caching Layer

Add a reverse proxy (Varnish) in front of web servers:

User -> CDN -> Varnish -> Web Server

Varnish caches rendered pages and reduces load on PHP.

CI/CD Pipeline Integration

Git-Based Deployment

# .github/workflows/deploy-wiki.yml

name: Deploy DokuWiki

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Deploy to Production
        uses: appleboy/scp-action@v0.1.4
        with:
          host: ${{ secrets.DEPLOY_HOST }}
          username: ${{ secrets.DEPLOY_USER }}
          key: ${{ secrets.DEPLOY_KEY }}
          source: "data/pages/*,conf/local.php,lib/tpl/*,lib/plugins/*"
          target: "/var/www/html/wiki"
          strip_components: 0

      - name: Post-deploy tasks
        uses: appleboy/ssh-action@v0.1.5
        with:
          host: ${{ secrets.DEPLOY_HOST }}
          username: ${{ secrets.DEPLOY_USER }}
          key: ${{ secrets.DEPLOY_KEY }}
          script: |
            cd /var/www/html/wiki
            php bin/indexer.php -f
            php bin/cleanup.php --cache
            sudo systemctl reload php8.1-fpm

Deployment Script

#!/bin/bash
# deploy.sh - Automated deployment script

set -e

WIKI_DIR="/var/www/html/wiki"
BACKUP_DIR="/var/backups/wiki/pre-deploy"

echo "=== DokuWiki Deployment ==="
echo "Date: $(date)"

# Step 1: Backup
echo "Backing up current state..."
mkdir -p "$BACKUP_DIR"
tar -czf "$BACKUP_DIR/pre-deploy-$(date +%Y%m%d_%H%M%S).tar.gz" \
    -C "$WIKI_DIR" data/ conf/

# Step 2: Maintenance mode
echo "Enabling maintenance mode..."
# Create a maintenance notice if your template supports it

# Step 3: Pull latest code
echo "Pulling latest changes..."
cd "$WIKI_DIR"
git pull origin main

# Step 4: Update plugins
echo "Checking plugin updates..."
php bin/plugin.php checkupdates || true

# Step 5: Clear caches
echo "Clearing caches..."
php bin/cleanup.php --cache
php bin/indexer.php -f

# Step 6: Disable maintenance mode
echo "Deployment complete."

Go-Live Checklist

Before Launch

[ ] DokuWiki is up to date (latest stable version)
[ ] PHP version is 8.1 or later
[ ] HTTPS is configured (Let's Encrypt or commercial SSL)
[ ] Security headers are configured
[ ] .htaccess files protect conf/, data/, inc/
[ ] install.php has been deleted
[ ] admin password is strong (generated by password manager)
[ ] ACL is configured (not open to everyone)
[ ] File permissions are set correctly
[ ] Backups are configured and tested
[ ] Monitoring is set up (uptime, server, logs)
[ ] Performance has been tested (target <500ms)
[ ] Caching is enabled and configured
[ ] Search index has been built
[ ] Sitemap has been generated
[ ] robots.txt is configured

Post-Launch (First Hour)

[ ] Wiki loads correctly on desktop and mobile
[ ] Login works
[ ] Page editing and saving works
[ ] Media upload works
[ ] Search returns results
[ ] All plugins function correctly
[ ] No PHP errors in logs
[ ] Server resources are within normal range
[ ] SSL certificate is valid (no mixed content warnings)
[ ] Monitoring alerts are working

Post-Launch (First Week)

[ ] Review server resource usage trends
[ ] Check for 404 errors in access logs
[ ] Verify backup cron jobs are running
[ ] Confirm monitoring alerts trigger correctly
[ ] Review performance metrics (page load times)
[ ] Check search console for indexing status

Production Troubleshooting

High CPU Usage

# Find which PHP processes are consuming CPU
top -b -n 1 | grep php

# Check if the indexer is running
ps aux | grep indexer

# Review access logs for unusual traffic patterns
tail -f /var/log/nginx/access.log | awk '{print $1}' | sort | uniq -c | sort -n

Out of Memory

# Check memory usage
free -m

# Review PHP-FPM pool settings
grep -r "pm\." /etc/php/8.1/fpm/pool.d/

# Adjust PHP-FPM children
pm.max_children = 50
pm.start_servers = 5
pm.min_spare_servers = 5
pm.max_spare_servers = 35

Slow Page Loads

# Enable DokuWiki's built-in performance log
# Add to local.php:
# $conf['debug'] = 1;

# Check for slow queries (not applicable to DokuWiki, but check PHP execution)
# Enable slow PHP-FPM log:
php_admin_value[request_slowlog_timeout] = 5s

Common Mistakes

1. Not testing the deployment pipeline on staging: A broken deployment script can take the wiki offline. Always test on staging first.
2. Skipping load testing before launch: 10 users and 10,000 users behave differently. Run load tests matching expected traffic.
3. Not having a rollback plan: If the deployment fails, you need to restore the previous version quickly. Have a tested rollback script.
4. Forgetting to monitor after launch: The launch is the start, not the end. Monitor uptime, performance, and errors for at least a week.
5. Scaling too early: Most wikis never need multiple servers. Vertical scaling (bigger single server) is simpler and sufficient for most cases.

Practice Questions

1. What are the key components of a production Nginx configuration for DokuWiki?
2. What monitoring should be set up for a production DokuWiki, and what thresholds should trigger alerts?
3. How would you design a CI/CD pipeline for automated DokuWiki deployments?
4. Challenge: Create a complete production deployment plan for a DokuWiki wiki expected to serve 50,000 monthly visitors. The plan should include: server specifications (CPU, RAM, storage type), web server configuration (Nginx with full config), CDN Strategy, monitoring setup (uptime, server, performance, logs), backup strategy (frequency, retention, off-site storage), CI/CD pipeline (GitHub Actions or similar), deployment script with rollback procedure, scaling plan (when and how to scale), and a go-live checklist. Implement a test deployment on a cloud server and verify the setup with a load test.

FAQ

Mini Project

Goal: Deploy DokuWiki to a production environment.

1. Provision a cloud server (or set up a production-like environment locally)
2. Install PHP 8.1+, Nginx, and other dependencies
3. Install DokuWiki with the production Nginx configuration provided above
4. Configure HTTPS with Let's Encrypt
5. Set up monitoring (Uptime Robot or similar)
6. Configure automated daily backups
7. Set up a Git repository for the wiki content
8. Create a deployment script
9. Perform a load test with 100 concurrent users
10. Run through the go-live checklist
11. Document the entire deployment architecture

Congratulations on completing the DokuWiki tutorial series. You have learned everything from DokuWiki basics and installation to security hardening, performance optimization, and production deployment. To continue your learning, explore PHP for deeper backend development, CSS for advanced template customization, and MediaWiki for understanding alternative wiki platforms. Visit DokuWiki.org for official documentation and the DokuWiki community for support.