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>
8.9 KiB
#Server configuration Example virtual host configurations for popular web servers
- Apache
- LightHttpd (empty)
- Nginx
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:
- How to Create Self-Signed SSL Certificates with OpenSSL
- How do I create my own Certificate Authority?
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:
- Server-side TLS (Nginx) (Mozilla)
- PHP configuration examples (Karl Blessing)
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 resourcesexecute
permissions for Shaarli directories AND their parent directories
On a production server:
user:group
will likely behttp:http
,www:www
orwww-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~
- dotfiles - in our case,
- 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;
}
}