====== DokuWiki (Ubuntu 24 Server) ======
Operational notes, install steps, required PHP modules, and recovery procedures.

Server OS: Ubuntu 24  
Web server: nginx  
PHP: php-fpm (8.3)  
Wiki path: /var/www/html/amigaz/wiki

----

===== Install / Initial Setup =====

==== Required Packages ====
<code bash>
sudo apt update
sudo apt install -y \
  nginx \
  php8.3-fpm \
  php8.3-cli \
  php8.3-common \
  php8.3-curl \
  php8.3-gd \
  php8.3-mbstring \
  php8.3-xml \
  php8.3-zip \
  php8.3-intl \
  php8.3-sqlite3
</code>

Restart PHP after install:
<code bash>
sudo systemctl restart php8.3-fpm
</code>

----

===== Required PHP Modules =====

DokuWiki core and common plugins require:

| Module | Purpose |
|--------|--------|
| mbstring | Text handling |
| xml | Parser |
| gd | Image handling |
| curl | External fetch |
| intl | Unicode support |
| zip | Plugin/theme installs |
| sqlite3 | Tagging, search, plugins |
| pdo_sqlite | SQLite database access |

Check installed modules:
<code bash>
php -m | egrep -i 'sqlite|mbstring|xml|gd|curl|intl|zip'
</code>

Verify PDO drivers:
<code bash>
php -i | grep "PDO drivers"
</code>

Expected output:
<code>
PDO drivers => sqlite
</code>

----

===== File Permissions =====

DokuWiki must be writable by the web user.

<code bash>
sudo chown -R www-data:www-data /var/www/html/amigaz/wiki
sudo find /var/www/html/amigaz/wiki -type d -exec chmod 755 {} \;
sudo find /var/www/html/amigaz/wiki -type f -exec chmod 644 {} \;
</code>

Writable directories:
<code>
data/
conf/
lib/plugins/
</code>


If plugin errors occur:
<code bash>
sudo chown -R www-data:www-data data conf lib/plugins
</code>

----

===== nginx Notes =====

Typical PHP handler block:

<code nginx>
location ~ \.php$ {
    include snippets/fastcgi-php.conf;
    fastcgi_pass unix:/run/php/php8.3-fpm.sock;
}
</code>


After changes:
<code bash>
sudo nginx -t
sudo systemctl reload nginx
</code>

----

===== Common Problems =====

==== SQLite PDO driver not available ====
Error:
<code>
Exception: SQLite PDO driver not available
</code>


Fix:
<code bash>
sudo apt install php8.3-sqlite3
sudo systemctl restart php8.3-fpm
</code>

Verify:
<code bash>
php -m | grep sqlite
</code>

----

==== Blank page or plugin crashes ====

Check logs:
<code bash>
tail -f /var/log/nginx/error.log
tail -f /var/www/html/amigaz/wiki/data/log/error.log
</code>

Restart PHP:
<code bash>
sudo systemctl restart php8.3-fpm
</code>

----

==== After PHP upgrade, wiki breaks ====

Symptoms:
  * Tag search stops working
  * Plugins fail
  * White pages

Cause:
PHP modules for the new version are missing.

Fix example (after upgrade to 8.4):
<code bash>
sudo apt install php8.4-fpm php8.4-sqlite3 php8.4-xml php8.4-mbstring php8.4-gd php8.4-curl php8.4-intl php8.4-zip
sudo systemctl restart php8.4-fpm
</code>

----

===== Upgrade Checklist =====

Before upgrade:
<code bash>
cd /var/www/html/amigaz
tar -czf wiki-backup.tar.gz wiki
</code>

After PHP or system upgrade:

1. Verify PHP version
<code bash>
php -v
</code>

2. Reinstall modules for that version
<code bash>
sudo apt install phpX.Y-sqlite3 phpX.Y-xml phpX.Y-mbstring phpX.Y-gd phpX.Y-curl phpX.Y-intl phpX.Y-zip
</code>

3. Restart PHP
<code bash>
sudo systemctl restart phpX.Y-fpm
</code>

4. Test wiki search and plugins

----

===== Quick Recovery Steps =====

If the wiki is broken:

1. Check PHP-FPM status
<code bash>
systemctl status php8.3-fpm
</code>

2. Restart services
<code bash>
systemctl restart php8.3-fpm
systemctl reload nginx
</code>

3. Check error logs
<code bash>
tail -n 50 /var/log/nginx/error.log
tail -n 50 /var/www/html/amigaz/wiki/data/log/error.log
</code>

4. Verify SQLite module
<code bash>
php -m | grep sqlite
</code>

----

===== Useful Commands =====

<code bash>
nginx -T
systemctl restart php8.3-fpm
systemctl reload nginx
php -v
php -m
df -h
</code>