# Server configuration
-
-
## Requirements
### Operating system and web server
-Shaarli can be hosted on dedicated/virtual servers, or shared hosting. The smallest DigitalOcean VPS (Droplet with 1 CPU, 1 GiB RAM and 25 GiB SSD) costs about $5/month and will run any Shaarli installation without problems.
+Shaarli can be hosted on dedicated/virtual servers, or shared hosting.
You need write access to the Shaarli installation directory - you should have received instructions from your hosting provider on how to connect to the server using SSH (or FTP for shared hosts).
Examples in this documentation are given for [Debian](https://www.debian.org/), a GNU/Linux distribution widely used in server environments. Please adapt them to your specific Linux distribution.
+A $5/month VPS (1 CPU, 1 GiB RAM and 25 GiB SSD) will run any Shaarli installation without problems. Some hosting providers: [DigitalOcean](https://www.digitalocean.com/) ([1](https://www.digitalocean.com/docs/droplets/overview/), [2](https://www.digitalocean.com/pricing/), [3](https://www.digitalocean.com/docs/droplets/how-to/create/), [4](https://www.digitalocean.com/docs/droplets/how-to/add-ssh-keys/), [5](https://www.digitalocean.com/community/tutorials/initial-server-setup-with-debian-8), [6](https://www.digitalocean.com/community/tutorials/an-introduction-to-securing-your-linux-vps)), [Gandi](https://www.gandi.net/en), [OVH](https://www.ovh.co.uk/), [RackSpace](https://www.rackspace.com/), etc.
+
+
### Network and domain name
Try to host the server in a region that is geographically close to your users.
Shaarli makes outbound HTTP/HTTPS connections to websites you bookmark to fetch page information (title, thumbnails), the server must then have access to the Internet as well, and a working DNS resolver.
+### Screencast
+
+Here is a screencast of the installation procedure
+
+[](https://asciinema.org/a/z3RXxcJIRgWk0jM2ws6EnUFgO)
+
+--------------------------------------------------------------------------------
+
### PHP
Supported PHP versions:
Version | Status | Shaarli compatibility
:---:|:---:|:---:
+8.0 | Supported | Yes
+7.4 | Supported | Yes
7.3 | Supported | Yes
7.2 | Supported | Yes
7.1 | Supported | Yes
Extension | Required? | Usage
---|:---:|---
-[`openssl`](http://php.net/manual/en/book.openssl.php) | requires | OpenSSL, HTTPS
+[`openssl`](http://php.net/manual/en/book.openssl.php) | required | OpenSSL, HTTPS
[`php-json`](http://php.net/manual/en/book.json.php) | required | configuration parsing
[`php-simplexml`](https://www.php.net/manual/en/book.simplexml.php) | required | REST API (Slim framework)
[`php-mbstring`](http://php.net/manual/en/book.mbstring.php) | CentOS, Fedora, RHEL, Windows, some hosting providers | multibyte (Unicode) string support
Some [plugins](Plugins.md) may require additional configuration.
+- [PHP: Supported versions](http://php.net/supported-versions.php)
+- [PHP: Unsupported versions (EOL/End-of-life)](http://php.net/eol.php)
+- [PHP 7 Changelog](http://php.net/ChangeLog-7.php)
+- [PHP 5 Changelog](http://php.net/ChangeLog-5.php)
+- [PHP: Bugs](https://bugs.php.net/)
+
## SSL/TLS (HTTPS)
-We recommend setting up [HTTPS](https://en.wikipedia.org/wiki/HTTPS) on your webserver for secure communication between clients and the server.
+We recommend setting up [HTTPS](https://en.wikipedia.org/wiki/HTTPS) (SSL/[TLS](https://en.wikipedia.org/wiki/Transport_Layer_Security)) on your webserver for secure communication between clients and the server.
### Let's Encrypt
- [How To Create a Self-Signed SSL Certificate for Apache](https://www.digitalocean.com/community/tutorials/how-to-create-a-self-signed-ssl-certificate-for-apache-on-debian-10)
- [How To Create a Self-Signed SSL Certificate for Nginx](https://www.digitalocean.com/community/tutorials/how-to-create-a-self-signed-ssl-certificate-for-nginx-on-debian-10)
+- [How to Create Self-Signed SSL Certificates with OpenSSL](http://www.xenocafe.com/tutorials/linux/centos/openssl/self_signed_certificates/index.php)
+- [How do I create my own Certificate Authority?](https://workaround.org/certificate-authority)
--------------------------------------------------------------------------------
The following examples assume a Debian-based operating system is installed. On other distributions you may have to adapt details such as package installation procedures, configuration file locations, and webserver username/group (`www-data` or `httpd` are common values). In these examples we assume the document root for your web server/virtualhost is at `/var/www/shaarli.mydomain.org/`:
```bash
-# create the document root
+# create the document root (replace with your own domain name)
sudo mkdir -p /var/www/shaarli.mydomain.org/
```
sudo apt update
sudo apt install apache2 libapache2-mod-php php-json php-mbstring php-gd php-intl php-curl php-gettext
-# Edit the virtualhost configuration file with your favorite editor
+# Edit the virtualhost configuration file with your favorite editor (replace the example domain name)
sudo nano /etc/apache2/sites-available/shaarli.mydomain.org.conf
```
ServerName shaarli.mydomain.org
DocumentRoot /var/www/shaarli.mydomain.org/
- # Redirect HTTP requests to HTTPS
+ # For SSL/TLS certificates acquired with certbot or self-signed certificates
+ # Redirect HTTP requests to HTTPS, except Let's Encrypt ACME challenge requests
RewriteEngine on
RewriteRule ^.well-known/acme-challenge/ - [L]
- # except for Let's Encrypt ACME challenge requests
RewriteCond %{HTTP_HOST} =shaarli.mydomain.org
RewriteRule ^ https://shaarli.mydomain.org%{REQUEST_URI} [END,NE,R=permanent]
</VirtualHost>
+# SSL/TLS configuration for Let's Encrypt certificates managed with mod_md
+#MDomain shaarli.mydomain.org
+#MDCertificateAgreement accepted
+#MDContactEmail admin@shaarli.mydomain.org
+#MDPrivateKeys RSA 4096
+
<VirtualHost *:443>
ServerName shaarli.mydomain.org
DocumentRoot /var/www/shaarli.mydomain.org/
- # SSL/TLS configuration (for Let's Encrypt certificates)
- # If certificates were acquired from certbot standalone
+ # SSL/TLS configuration for Let's Encrypt certificates acquired with certbot standalone
SSLEngine on
SSLCertificateFile /etc/letsencrypt/live/shaarli.mydomain.org/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/shaarli.mydomain.org/privkey.pem
SSLSessionTickets off
SSLOptions +StrictRequire
- # SSL/TLS configuration (for self-signed certificates)
+ # SSL/TLS configuration for self-signed certificates
#SSLEngine on
#SSLCertificateFile /etc/ssl/certs/ssl-cert-snakeoil.pem
#SSLCertificateKeyFile /etc/ssl/private/ssl-cert-snakeoil.key
```bash
# Enable the virtualhost
-sudo a2ensite shaarli
+sudo a2ensite shaarli.mydomain.org
# mod_ssl must be enabled to use TLS/SSL certificates
# https://httpd.apache.org/docs/current/mod/mod_ssl.html
# https://httpd.apache.org/docs/current/mod/mod_rewrite.html
sudo a2enmod rewrite
+# mod_headers must be enabled to set custom headers from the server config
+sudo a2enmod headers
+
# mod_version must only be enabled if you use Apache 2.2 or lower
# https://httpd.apache.org/docs/current/mod/mod_version.html
# sudo a2enmod version
# restart the apache service
-systemctl restart apache
+sudo systemctl restart apache2
```
-See [How to install the Apache web server](https://www.digitalocean.com/community/tutorials/how-to-install-the-apache-web-server-on-debian-10) for a complete guide.
+- [How to install the Apache web server](https://www.digitalocean.com/community/tutorials/how-to-install-the-apache-web-server-on-debian-10)
+- [Apache/PHP - error log per VirtualHost - StackOverflow](http://stackoverflow.com/q/176)
+- [Apache - PHP: php_value vs php_admin_value and the use of php_flag explained](https://ma.ttias.be/php-php_value-vs-php_admin_value-and-the-use-of-php_flag-explained/)
+- [Server-side TLS (Apache) - Mozilla](https://wiki.mozilla.org/Security/Server_Side_TLS#Apache)
+- [Apache 2.4 documentation](https://httpd.apache.org/docs/2.4/)
+- [Apache mod_proxy](https://httpd.apache.org/docs/2.4/mod/mod_proxy.html)
+- [Apache Reverse Proxy Request Headers](https://httpd.apache.org/docs/2.4/mod/mod_proxy.html#x-headers)
### Nginx
}
server {
- listen 443 ssl;
+ # ipv4 listening port/protocol
+ listen 443 ssl http2;
+ # ipv6 listening port/protocol
+ listen [::]:443 ssl http2;
server_name shaarli.mydomain.org;
root /var/www/shaarli.mydomain.org;
location / {
# default index file when no file URI is requested
index index.php;
- try_files $uri /index.php$is_args$args;
+ try_files _ /index.php$is_args$args;
}
location ~ (index)\.php$ {
include fastcgi.conf;
}
- location ~ \.php$ {
- # deny access to all other PHP scripts
- # disable this if you host other PHP applications on the same virtualhost
- deny all;
- }
-
- location ~ /\. {
- # deny access to dotfiles
- deny all;
- }
-
- location ~ ~$ {
- # deny access to temp editor files, e.g. "script.php~"
- deny all;
+ location ~ /doc/html/ {
+ default_type "text/html";
+ try_files $uri $uri/ $uri.html =404;
}
location = /favicon.ico {
}
# allow client-side caching of static files
- location ~* \.(?:ico|css|js|gif|jpe?g|png)$ {
+ location ~* \.(?:ico|css|js|gif|jpe?g|png|ttf|oet|woff2?)$ {
expires max;
add_header Cache-Control "public, must-revalidate, proxy-revalidate";
# HTTP 1.0 compatibility
add_header Pragma public;
}
-
}
```
sudo systemctl reload nginx
```
-See [How to install the Nginx web server](https://www.digitalocean.com/community/tutorials/how-to-install-nginx-on-debian-10) for a complete guide.
+- [How to install the Nginx web server](https://www.digitalocean.com/community/tutorials/how-to-install-nginx-on-debian-10)
+- [Nginx Beginner's guide](http://nginx.org/en/docs/beginners_guide.html)
+- [Nginx documentation](https://nginx.org/en/docs/)
+- [Nginx ngx_http_fastcgi_module](http://nginx.org/en/docs/http/ngx_http_fastcgi_module.html)
+- [Nginx Pitfalls](http://wiki.nginx.org/Pitfalls)
+- [Nginx PHP configuration examples - Karl Blessing](http://kbeezie.com/nginx-configuration-examples/)
+- [Server-side TLS (Nginx) - Mozilla](https://wiki.mozilla.org/Security/Server_Side_TLS#Nginx)
+
## Reverse proxies
If Shaarli is hosted on a server behind a [reverse proxy](https://en.wikipedia.org/wiki/Reverse_proxy) (i.e. there is a proxy server between clients and the web server hosting Shaarli), configure it accordingly. See [Reverse proxy](Reverse-proxy.md) configuration.
+## Using Shaarli without URL rewriting
+By default, Shaarli uses Slim framework's URL, which requires
+URL rewriting.
+
+If you can't use URL rewriting for any reason (not supported by
+your web server, shared hosting, etc.), you *can* use Shaarli
+without URL rewriting.
+
+You just need to prefix your URL by `/index.php/`.
+Example: instead of accessing `https://shaarli.mydomain.org/`,
+use `https://shaarli.mydomain.org/index.php/`.
+
+**Recommended:**
+ * after installation, in the configuration page, set your header link to `/index.php/`.
+ * in your configuration file `config.json.php` set `general.root_url` to
+ `https://shaarli.mydomain.org/index.php/`.
## Allow import of large browser bookmarks export
before = common.conf
[Definition]
failregex = \s-\s<HOST>\s-\sLogin failed for user.*$
-ignoreregex =
+ignoreregex =
```
```ini
bantime = -1
```
-#### References
+Then restart the service: `sudo systemctl restart fail2ban`
-- [Apache/PHP - error log per VirtualHost - StackOverflow](http://stackoverflow.com/q/176)
-- [Apache - PHP: php_value vs php_admin_value and the use of php_flag explained](https://ma.ttias.be/php-php_value-vs-php_admin_value-and-the-use-of-php_flag-explained/)
-- [Server-side TLS (Apache) - Mozilla](https://wiki.mozilla.org/Security/Server_Side_TLS#Apache)
-- [Nginx Beginner's guide](http://nginx.org/en/docs/beginners_guide.html)
-- [Nginx ngx_http_fastcgi_module](http://nginx.org/en/docs/http/ngx_http_fastcgi_module.html)
-- [Nginx Pitfalls](http://wiki.nginx.org/Pitfalls)
-- [Nginx PHP configuration examples - Karl Blessing](http://kbeezie.com/nginx-configuration-examples/)
-- [Apache 2.4 documentation](https://httpd.apache.org/docs/2.4/)
-- [Apache mod_proxy](https://httpd.apache.org/docs/2.4/mod/mod_proxy.html)
-- [Apache Reverse Proxy Request Headers](https://httpd.apache.org/docs/2.4/mod/mod_proxy.html#x-headers)
-- [HAProxy documentation](https://cbonte.github.io/haproxy-dconv/)
-- [Nginx documentation](https://nginx.org/en/docs/)
-- [`X-Forwarded-Proto`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Proto)
-- [`X-Forwarded-Host`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Host)
-- [`X-Forwarded-For`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For)
-- [Server-side TLS (Nginx) - Mozilla](https://wiki.mozilla.org/Security/Server_Side_TLS#Nginx)
-- [How to Create Self-Signed SSL Certificates with OpenSSL](http://www.xenocafe.com/tutorials/linux/centos/openssl/self_signed_certificates/index.php)
-- [How do I create my own Certificate Authority?](https://workaround.org/certificate-authority)
-- [Travis configuration](https://github.com/shaarli/Shaarli/blob/master/.travis.yml)
-- [PHP: Supported versions](http://php.net/supported-versions.php)
-- [PHP: Unsupported versions (EOL/End-of-life)](http://php.net/eol.php)
-- [PHP 7 Changelog](http://php.net/ChangeLog-7.php)
-- [PHP 5 Changelog](http://php.net/ChangeLog-5.php)
-- [PHP: Bugs](https://bugs.php.net/)
-- [Transport Layer Security](https://en.wikipedia.org/wiki/Transport_Layer_Security)
-- Hosting providers: [DigitalOcean](https://www.digitalocean.com/) ([1](https://www.digitalocean.com/docs/droplets/overview/), [2](https://www.digitalocean.com/pricing/), [3](https://www.digitalocean.com/docs/droplets/how-to/create/), [How to Add SSH Keys to Droplets](https://www.digitalocean.com/docs/droplets/how-to/add-ssh-keys/), [4](https://www.digitalocean.com/community/tutorials/initial-server-setup-with-debian-8), [5](https://www.digitalocean.com/community/tutorials/an-introduction-to-securing-your-linux-vps)), [Gandi](https://www.gandi.net/en), [OVH](https://www.ovh.co.uk/), [RackSpace](https://www.rackspace.com/), etc.
+## What next?
+[Shaarli installation](Installation.md)
projects / github / shaarli / Shaarli.git / blobdiff