MyShaarli/doc/Server-configuration.md
VirtualTam 992af0b9d7 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 - <Page Name>

Signed-off-by: VirtualTam <virtualtam@flibidi.net>
2015-08-04 16:02:21 +02:00

8.9 KiB

#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:

  • Apache/PHP - error log per VirtualHost (StackOverflow)
  • [PHP: php_value vs php_admin_value and the use of php_flag explained](PHP: php_value vs php_admin_value and the use of php_flag explained)
<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;
    }
}