====== Nginx ======
Nginx here is used as a webserver for serving static (html, jpg) and dynamic content (php).


> FIXME
> Windows part is untested - remove or add information?
> ADD Content for PHP/PHP-FPM
> Recipe needs some testing, optimization and documentation
> Compare recipe to [[https://web.archive.org/web/20240214213649/https://www.nginx.com/resources/wiki/start/topics/recipes/dokuwiki/|nginx.com/.../dokuwiki]]
>  * URL rewriting for mode ".htaccess"
>  * X-Accel handling - further research
> WIP - feel free to change


===== Basic knowledge =====
How to install Nginx and where to find configuration files.


==== Nginx ====
<code bash>
# Installation of Nginx

$ apk add nginx               # Alpine Linux
$ sudo apt-get install nginx  # Debian / Ubuntu

</code>

**Configuration**\\

In most Linux distributions the base configuration takes place in the file ''/etc/nginx/nginx.conf'', but the further configuration is located in subdirectories.


So **we focus on putting the "recipe" - configuration file in a subdirectory** under ''./http.d/'' (Alpine Linux) or ''./sites-enabled/'' (Ubuntu, Debian). The configuration file should be named like ''filename.conf''.

<code bash>
# Create / edit configuration file

# Alpine Linux
nano /etc/nginx/http.d/dokuwiki.conf
vi   /etc/nginx/http.d/dokuwiki.conf  # [ESC] :q

# Debian / Ubuntu
nano  /etc/nginx/sites-available/dokuwiki.conf
ln -s /etc/nginx/sites-available/dokuwiki.conf /etc/nginx/sites-enabled/
</code>

If we change the configuration, it is necessary to reload it or to restart the nginx - server.

<code bash>
# Reload configuration

systemctl reload nginx    # systemd (Debian, Ubuntu)

service nginx reload      # some other (Alpine Linux)
lbu commit                # Alpine Linux specific
</code>


==== PHP-FPM ====
PHP-FPM needs to be installed to run dokuwiki. It might be a good idea to [[:install:php|install and configure]] it first. Nginx uses php-fpm to serve dynamic content.

  * TODO Explanation fo difference between (F)CGI and FPM.
  * No need to explain how to set up FPM


==== Distribution specifics ====

**Windows** \\
If dokuwiki is extracted to the directory ''E:\www\dokuwiki'' the root directive in the server part of the nginx-configuration has to be ''root E:\www\dokuwiki;''.

<code bash>
# Start PHP FastCGI
RunHiddenConsole.exe E:\appl\php-5.2.9-2-Win32\php-cgi.exe -b 127.0.0.1:9000

# Start NginX
cd /d D:\nginx-0.8.39 && start nginx.exe

</code>

==== Troubleshooting ====

  * If you encounter a 502 Gateway issue, the socket configuration might be incorrect
  * Reload or restart Nginx to apply the new configuration
  * On the initial setup you won't be able to start unless you comment the deny to the "install.php" file.




===== Recipe / Example =====
This is an example with a full configuration for Dokuwiki under Nginx. You can simply copy paste and change the parts to your liking.

:!: On the initial setup you won't be able to start unless you comment the deny to the "install.php" file. 


<code nginx dokuwiki.conf>
# Example Nginx - configuration file for Dokuwiki from 
# https://www.dokuwiki.org/install:nginx


# PHP Handler
upstream php-handler {
    server unix:/run/php-fpm82/fastcgi.sock;    # Alpine Linux (socket)
    # server unix:/var/run/php/php-fpm.sock;    # Debian/Ubuntu (socket)
    # server unix:/var/run/php/php8.1-fpm.sock; # Debian/Ubuntu (socket) (PHP-specific)
    # server 127.0.0.1:9000;                    # Distro independent

}

# Redirect SSL/443 (optional - recommended)
#server {
#    server_name default_server;
#    listen           80;            # IPv4
#    listen      [::]:80;            # IPv6
#    return      301 https://$server_name$request_uri;
#}



# Actual configuration
server {

# BASICS ######### ######### ######### ######### ######### ######### ####### ###
    server_name default_server;     # optional: your domain name
    root        /var/www/dokuwiki;
    index       doku.php;

# NoSSL version (not recommended)
    listen           80;            # IPv4
    listen      [::]:80;            # IPv6

# SSL version (recommended)
    # listen           443 ssl;     # IPv4
    # listen      [::]:443 ssl;     # IPv6
    # http2       on;               # if supported, optional

    # ssl_certificate     /etc/ssl/certs/***.crt;
    # ssl_certificate_key /etc/ssl/private/***.key;

    # Optional - further research recommended
    # ssl_seesion_timeout 5m;
    # ssl_ciphers "HIGH:!aNULL:!MD5 or HIGH:!aNULL:!MD5:!3DES";
    # ssl_dhparam /etc/ssl/private/dhparam2048.pem;
    # openssl dhparam -outform pem -out /etc/nginx/ssl/dhparam2048.pem 2048

# HEADERS ######### ######### ######### ######### ######### ######### ##########
    # Information "leaks"
    server_tokens       off;
    fastcgi_hide_header X-Powered_by;

# TWEAKS ######### ######### ######### ######### ######### ######### #######  ##

    client_max_body_size 4M;          # Maximum file upload size
    client_body_buffer_size 128k;
    
    location ~ ^/lib.*\.(js|css|gif|png|ico|jpg|jpeg|svg)$ {
        expires 365d;   # browser caching
    }
   
    
# RESTRICT ACCESS ######### ######### ######### ######### ######### ######### ##
    # Reference: https://www.dokuwiki.org/security#deny_directory_access_in_nginx
                 # TODO: Compare with this
    
    
    # Comment out while installing, then uncomment
    location ~ /(install.php) { deny all; }
 

    # .ht             - .htaccess, .htpasswd, .htdigest, .htanything
    # .git, .hg, .svn - Git, Mercurial, Subversion.
    # .vs             - Visual Studio (Code)
    # All directories except lib.
    # All "other" files that you don't want to delete, but don't want public.

    location ~ /(\.ht|\.git|\.hg|\.svn|\.vs|data|conf|bin|inc|vendor|README|VERSION|SECURITY.md|COPYING|composer.json|composer.lock) {
        #return 404; # https://www.dokuwiki.org/install:nginx?rev=1734102057#nginx_particulars
        deny all;    # Returns 403
    }
 
######################
    # (2024-08): Is this actually a default feature or does
    # this belong in a seperate section? Disable by default?
    
    # Support for X-Accel-Redirect
    location ~ ^/data/ {
       internal;
    }
########################
    
# REDIRECT & PHP ### ######### ######### ######### ######### ######### #########     
    
    location / {
        try_files $uri $uri/ @dokuwiki;
        
        # This means; where $uri is 'path', if 'GET /path' doesnt exist, redirect
        # client to 'GET /path/' directory. If neither, goto @dokuwiki rules.
    }
 
    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 ^/tag/(.*) /doku.php?id=tag:$1&do=showtag&tag=tag:$1 last;  #untested
        rewrite ^/(.*) /doku.php?id=$1&$args last;
        
        # rewrites "doku.php/" out of the URLs if you set the userewrite
        # setting to .htaccess in dokuwiki config page
    }
 
    location ~ \.php$ {
        try_files $uri $uri/ /doku.php;
        
        include       fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param REDIRECT_STATUS 200;
        # fastcgi_param HTTPS on;     # optional ?! TODO
        
        fastcgi_pass php-handler;
    }
}



# Credits
# https://www.nginx.com/resources/wiki/start/topics/recipes/dokuwiki/
# https://wiki.boetes.org/dokuwiki_on_nginx
# http://blog.slucas.fr/blog/nginx-gzip-css-js


</code>