From 992af0b9d77cb4fbac2c37ef8d5896042d67a2a3 Mon Sep 17 00:00:00 2001 From: VirtualTam Date: Wed, 22 Jul 2015 05:02:10 +0200 Subject: Doc: sync from Wiki, generate HTML Closes #291 Fixes #227 Modifications - HTML content: match the new Wiki structure - Makefile - generate a custom HTML sidebar - include the sidebar on all pages - infer and prepend page titles - handle relative links - add title metadata, e.g. Shaarli - Signed-off-by: VirtualTam --- doc/Server-configuration.html | 371 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 371 insertions(+) create mode 100644 doc/Server-configuration.html (limited to 'doc/Server-configuration.html') diff --git a/doc/Server-configuration.html b/doc/Server-configuration.html new file mode 100644 index 00000000..de6bf488 --- /dev/null +++ b/doc/Server-configuration.html @@ -0,0 +1,371 @@ + + + + + + + Shaarli - Server configuration + + + + + + + +

Server configuration

+

Example virtual host configurations for popular web servers

+ +

Prerequisites

+
    +
  • Shaarli is installed in a directory readable/writeable by the user
    • +
  • the correct read/write permissions have been granted to the web server user and/or group
    • +
  • for HTTPS / SSL:
    • +
  • a key pair (public, private) and a certificate have been generated
    • +
  • the appropriate server SSL extension is installed and active
    • +
+

Related guides:

+ +

Apache

+

Minimal

+
<VirtualHost *:80>
+    ServerName   shaarli.my-domain.org
+    DocumentRoot /absolute/path/to/shaarli/
+</VirtualHost>
+

Debug - Log all the things!

+

This configuration will log both Apache and PHP errors, which may prove useful to identify server configuration errors.

+

See:

+ +
<VirtualHost *:80>
+    ServerName   shaarli.my-domain.org
+    DocumentRoot /absolute/path/to/shaarli/
+
+    LogLevel  warn
+    ErrorLog  /var/log/apache2/shaarli-error.log
+    CustomLog /var/log/apache2/shaarli-access.log combined
+
+    php_flag  log_errors on
+    php_flag  display_errors on
+    php_value error_reporting 2147483647
+    php_value error_log /var/log/apache2/shaarli-php-error.log
+</VirtualHost>
+

Standard - Keep access and error logs

+
<VirtualHost *:80>
+    ServerName   shaarli.my-domain.org
+    DocumentRoot /absolute/path/to/shaarli/
+
+    LogLevel  warn
+    ErrorLog  /var/log/apache2/shaarli-error.log
+    CustomLog /var/log/apache2/shaarli-access.log combined
+</VirtualHost>
+

Paranoid - Redirect HTTP (:80) to HTTPS (:443)

+

See Server-side TLS (Mozilla).

+
<VirtualHost *:443>
+    ServerName   shaarli.my-domain.org
+    DocumentRoot /absolute/path/to/shaarli/
+
+    SSLEngine             on
+    SSLCertificateFile    /absolute/path/to/the/website/certificate.crt
+    SSLCertificateKeyFile /absolute/path/to/the/website/key.key
+
+    <Directory /absolute/path/to/shaarli/>
+        AllowOverride All
+        Options Indexes FollowSymLinks MultiViews
+        Order allow,deny
+        allow from all
+    </Directory>
+
+    LogLevel  warn
+    ErrorLog  /var/log/apache2/shaarli-error.log
+    CustomLog /var/log/apache2/shaarli-access.log combined
+</VirtualHost>
+<VirtualHost *:80>
+    ServerName   shaarli.my-domain.org
+    Redirect 301 / https://shaarli.my-domain.org
+
+    LogLevel  warn
+    ErrorLog  /var/log/apache2/shaarli-error.log
+    CustomLog /var/log/apache2/shaarli-access.log combined
+</VirtualHost>
+

LightHttpd

+

Nginx

+

Foreword

+

Nginx does not natively interpret PHP scripts; to this effect, we will run a FastCGI service, to which Nginx's FastCGI module will proxy all requests to PHP resources.

+

Required packages:

+ +

Official documentation:

+ +

Community resources:

+ +

Common setup

+

Once Nginx and PHP-FPM are installed, we need to ensure:

+
    +
  • Nginx and PHP-FPM are running using the same user and group
    • +
  • both these user and group have +
      +
    • read permissions for Shaarli resources
      • +
    • execute permissions for Shaarli directories AND their parent directories
      • +
    • +
+

On a production server:

+
    +
  • user:group will likely be http:http, www:www or www-data:www-data
    • +
  • files will be located under /var/www, /var/http or /usr/share/nginx
    • +
+

On a development server:

+
    +
  • files may be located in a user's home directory
    • +
  • in this case, make sure both Nginx and PHP-FPM are running as the local user/group!
    • +
+

For all following examples, a development configuration will be used:

+
    +
  • user:group = john:users,
    • +
+

which corresponds to the following service configuration:

+
; /etc/php/php-fpm.conf
+user = john
+group = users
+
+[...][](.html)
+listen.owner = john
+listen.group = users
+
# /etc/nginx/nginx.conf
+user john users;
+
+http {
+    [...][](.html)
+}
+

Minimal

+

WARNING: Use for development only!

+
user john users;
+worker_processes  1;
+events {
+    worker_connections  1024;
+}
+
+http {
+    include            mime.types;
+    default_type       application/octet-stream;
+    keepalive_timeout  20;
+
+    index index.html index.php;
+
+    server {
+        listen       80;
+        server_name  localhost;
+        root         /home/john/web;
+
+        access_log  /var/log/nginx/access.log;
+        error_log   /var/log/nginx/error.log;
+
+        location /shaarli/ {
+            access_log  /var/log/nginx/shaarli.access.log;
+            error_log   /var/log/nginx/shaarli.error.log;
+        }
+
+        location ~ (index)\.php$ {
+            fastcgi_pass   unix:/var/run/php-fpm/php-fpm.sock;
+            fastcgi_index  index.php;
+            include        fastcgi.conf;
+        }
+    }
+}
+

Modular

+

The previous setup is sufficient for development purposes, but has several major caveats:

+
    +
  • every content that does not match the PHP rule will be sent to client browsers: +
      +
    • dotfiles - in our case, .htaccess
      • +
    • temporary files, e.g. Vim or Emacs files: index.php~
      • +
    • +
  • asset / static resource caching is not optimized
    • +
  • if serving several PHP sites, there will be a lot of duplication: location /shaarli/, location /mysite/, etc.
    • +
+

To solve this, we will split Nginx configuration in several parts, that will be included when needed:

+
# /etc/nginx/deny.conf
+location ~ /\. {
+    # deny access to dotfiles
+    access_log off;
+    log_not_found off;
+    deny all;
+}
+
+location ~ ~$ {
+    # deny access to temp editor files, e.g. "script.php~"
+    access_log off;
+    log_not_found off;
+    deny all;
+}
+
# /etc/nginx/php.conf
+location ~ (index)\.php$ {
+    # proxy PHP requests to PHP-FPM
+    fastcgi_pass   unix:/var/run/php-fpm/php-fpm.sock;
+    fastcgi_index  index.php;
+    include        fastcgi.conf;
+}
+
# /etc/nginx/static_assets.conf
+location ~* \.(?:ico|css|js|gif|jpe?g|png)$ {
+    expires    max;
+    add_header Pragma public;
+    add_header Cache-Control "public, must-revalidate, proxy-revalidate";
+}
+
# /etc/nginx/nginx.conf
+[...][](.html)
+
+http {
+    [...][](.html)
+
+    root        /home/john/web;
+    access_log  /var/log/nginx/access.log;
+    error_log   /var/log/nginx/error.log;
+
+    server {
+        # virtual host for a first domain
+        listen       80;
+        server_name  my.first.domain.org;
+
+        location /shaarli/ {
+            access_log  /var/log/nginx/shaarli.access.log;
+            error_log   /var/log/nginx/shaarli.error.log;
+        }
+
+        include deny.conf;
+        include static_assets.conf;
+        include php.conf;
+    }
+
+    server {
+        # virtual host for a second domain
+        listen       80;
+        server_name  second.domain.com;
+
+        location /minigal/ {
+            access_log  /var/log/nginx/minigal.access.log;
+            error_log   /var/log/nginx/minigal.error.log;
+        }
+
+        include deny.conf;
+        include static_assets.conf;
+        include php.conf;
+    }
+}
+

Redirect HTTP to HTTPS

+

Assuming you have generated a (self-signed) key and certificate, and they are located under /home/john/ssl/localhost.{key,crt}, it is pretty straightforward to set an HTTP (:80) to HTTPS (:443) redirection to force SSL/TLS usage.

+
# /etc/nginx/nginx.conf
+[...][](.html)
+
+http {
+    [...][](.html)
+
+    index index.html index.php;
+
+    root        /home/john/web;
+    access_log  /var/log/nginx/access.log;
+    error_log   /var/log/nginx/error.log;
+
+    server {
+        listen       80;
+        server_name  localhost;
+
+        return 301 https://localhost$request_uri;
+    }
+
+    server {
+        listen       443 ssl;
+        server_name  localhost;
+
+        ssl_certificate      /home/john/ssl/localhost.crt;
+        ssl_certificate_key  /home/john/ssl/localhost.key;
+
+        location /shaarli/ {
+            access_log  /var/log/nginx/shaarli.access.log;
+            error_log   /var/log/nginx/shaarli.error.log;
+        }
+
+        include deny.conf;
+        include static_assets.conf;
+        include php.conf;
+    }
+}
+ + -- cgit v1.2.3