From ec457491879893c8cfcc9dd6542d1593aa5c91f5 Mon Sep 17 00:00:00 2001 From: ArthurHoaro Date: Thu, 15 Oct 2020 08:59:51 +0200 Subject: Doc: add PHP 7.4 and 8.0 as supported version --- doc/md/Server-configuration.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'doc') diff --git a/doc/md/Server-configuration.md b/doc/md/Server-configuration.md index 297d7c29..14070c8a 100644 --- a/doc/md/Server-configuration.md +++ b/doc/md/Server-configuration.md @@ -40,6 +40,8 @@ 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 @@ -53,7 +55,7 @@ Required PHP extensions: 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 @@ -421,7 +423,7 @@ By default Shaarli already disallows indexing of your local copy of the document before = common.conf [Definition] failregex = \s-\s\s-\sLogin failed for user.*$ -ignoreregex = +ignoreregex = ``` ```ini -- cgit v1.2.3 From 4cf3564d28dc8e4d08a3e64f09ad045ffbde97ae Mon Sep 17 00:00:00 2001 From: ArthurHoaro Date: Fri, 25 Sep 2020 13:29:36 +0200 Subject: Add a setting to retrieve bookmark metadata asynchrounously - There is a new standalone script (metadata.js) which requests a new controller to get bookmark metadata and fill the form async - This feature is enabled with the new setting: general.enable_async_metadata (enabled by default) - general.retrieve_description is now enabled by default - A small rotating loader animation has a been added to bookmark inputs when metadata is being retrieved (default template) - Custom JS htmlentities has been removed and mathiasbynens/he library is used instead Fixes #1563 --- doc/md/Shaarli-configuration.md | 1 + 1 file changed, 1 insertion(+) (limited to 'doc') diff --git a/doc/md/Shaarli-configuration.md b/doc/md/Shaarli-configuration.md index 263fb761..dbfc3da9 100644 --- a/doc/md/Shaarli-configuration.md +++ b/doc/md/Shaarli-configuration.md @@ -150,6 +150,7 @@ _These settings should not be edited_ - **timezone**: See [the list of supported timezones](http://php.net/manual/en/timezones.php). - **enabled_plugins**: List of enabled plugins. - **default_note_title**: Default title of a new note. +- **enable_async_metadata** (boolean): Retrieve external bookmark metadata asynchronously to prevent bookmark creation slowdown. - **retrieve_description** (boolean): If set to true, for every new Shaare Shaarli will try to retrieve the description and keywords from the HTML meta tags. - **root_url**: Overrides automatic discovery of Shaarli instance's URL (e.g.) `https://sub.domain.tld/shaarli-folder/`. -- cgit v1.2.3 From 7f5250421be4832b9679d8140bc4a71c8005dfa3 Mon Sep 17 00:00:00 2001 From: ArthurHoaro Date: Fri, 16 Oct 2020 12:47:11 +0200 Subject: Support using Shaarli without URL rewriting MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Shaarli can be fully used by prefixing any URL with /index.php/ - {$base_path} used in templates already works with this configuration - Assets path (outside of theme's assets) must be prefixed with {$root_url}/ - Documentation section in « Server configuration » Fixes #1590 --- doc/md/Server-configuration.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) (limited to 'doc') diff --git a/doc/md/Server-configuration.md b/doc/md/Server-configuration.md index 14070c8a..73302bc6 100644 --- a/doc/md/Server-configuration.md +++ b/doc/md/Server-configuration.md @@ -362,7 +362,23 @@ sudo systemctl reload nginx 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 you `config.json.php` set `general.root_url` to + `https://shaarli.mydomain.org/index.php/`. ## Allow import of large browser bookmarks export -- cgit v1.2.3 From 3adbdc2a83e6b77a4ca62094c5d857524e39d211 Mon Sep 17 00:00:00 2001 From: ArthurHoaro Date: Fri, 16 Oct 2020 13:06:06 +0200 Subject: Inject ROOT_PATH in plugin instead of regenerating it everywhere --- doc/md/dev/Plugin-system.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) (limited to 'doc') diff --git a/doc/md/dev/Plugin-system.md b/doc/md/dev/Plugin-system.md index c29774de..f09fadc2 100644 --- a/doc/md/dev/Plugin-system.md +++ b/doc/md/dev/Plugin-system.md @@ -148,11 +148,16 @@ If a file needs to be included in server end, use simple relative path: `PluginManager::$PLUGINS_PATH . '/mything/template.html'`. If it needs to be included in front end side (e.g. an image), -the relative path must be prefixed with special data `_BASE_PATH_`: -`($data['_BASE_PATH_'] ?? '') . '/' . PluginManager::$PLUGINS_PATH . '/mything/picture.png`. +the relative path must be prefixed with special data: + + * if it's a link that will need to be processed by Shaarli, use `_BASE_PATH_`: + for e.g. `$data['_BASE_PATH_'] . '/admin/tools`. + * if you want to include an asset, you need to add the root URL (base path without `/index.php`, for people using Shaarli without URL rewriting), then use `_ROOT_PATH_`: + for e.g +`$['_ROOT_PATH_'] . '/' . PluginManager::$PLUGINS_PATH . '/mything/picture.png`. Note that special placeholders for CSS and JS files (respectively `css_files` and `js_files`) are already prefixed -with the base path in template files. +with the root path in template files. ### It's not working! -- cgit v1.2.3 From 7836ed9b2e98e2c6898f011e431d3a58ebcfa3e5 Mon Sep 17 00:00:00 2001 From: ArthurHoaro Date: Fri, 16 Oct 2020 19:20:45 +0200 Subject: Doc: typo --- doc/md/Server-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/md/Server-configuration.md b/doc/md/Server-configuration.md index 73302bc6..8cb39934 100644 --- a/doc/md/Server-configuration.md +++ b/doc/md/Server-configuration.md @@ -377,7 +377,7 @@ use `https://shaarli.mydomain.org/index.php/`. **Recommended:** * after installation, in the configuration page, set your header link to `/index.php/`. - * in you `config.json.php` set `general.root_url` to + * 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 -- cgit v1.2.3 From 2f87bfdc69052cd64e84b1d2b97a0af14991a385 Mon Sep 17 00:00:00 2001 From: ArthurHoaro Date: Wed, 21 Oct 2020 15:23:30 +0200 Subject: Fix: nginx - add rule to disable url-rewriting for the docs Related to #1603 --- doc/md/Server-configuration.md | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'doc') diff --git a/doc/md/Server-configuration.md b/doc/md/Server-configuration.md index 8cb39934..4e74d80b 100644 --- a/doc/md/Server-configuration.md +++ b/doc/md/Server-configuration.md @@ -325,6 +325,11 @@ server { deny all; } + location ~ /doc/ { + default_type "text/html"; + try_files $uri $uri/ $uri.html =404; + } + location = /favicon.ico { # serve the Shaarli favicon from its custom location alias /var/www/shaarli/images/favicon.ico; -- cgit v1.2.3 From 740b32b520e6b1723512c6f9b78cef6575b1725b Mon Sep 17 00:00:00 2001 From: ArthurHoaro Date: Tue, 3 Nov 2020 12:38:38 +0100 Subject: Default formatter: add a setting to disable auto-linkification + update documentation + single parameter for both URL and hashtags Fixes #1094 --- doc/md/Shaarli-configuration.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) (limited to 'doc') diff --git a/doc/md/Shaarli-configuration.md b/doc/md/Shaarli-configuration.md index dbfc3da9..99084728 100644 --- a/doc/md/Shaarli-configuration.md +++ b/doc/md/Shaarli-configuration.md @@ -164,6 +164,22 @@ _These settings should not be edited_ - **trusted_proxies**: List of trusted IP which won't be banned after failed login attemps. Useful if Shaarli is behind a reverse proxy. - **allowed_protocols**: List of allowed protocols in shaare URLs or markdown-rendered descriptions. Useful if you want to store `javascript:` links (bookmarklets) in Shaarli (default: `["ftp", "ftps", "magnet"]`). +### Formatter + +Single string value. Default available: + + - `default`: supports line breaks, URL and hashtag auto-links. + - `markdown`: supports [Markdown](https://daringfireball.net/projects/markdown/syntax). + - `markdownExtra`: adds [extra](https://michelf.ca/projects/php-markdown/extra/) flavor to Markdown. + +### Formatter Settings + +Additional settings applied to formatters. + +#### default + + - **autolink**: boolean to enable or disable automatic linkification of URL and hashtags. + ### Resources - **data_dir**: Data directory. -- cgit v1.2.3 From b3bd8c3e8d367975980043e772f7cd78b7f96bc6 Mon Sep 17 00:00:00 2001 From: ArthurHoaro Date: Thu, 22 Oct 2020 16:21:03 +0200 Subject: Feature: support any tag separator So it allows to have multiple words tags. Breaking change: commas ',' are no longer a default separator. Fixes #594 --- doc/md/Shaarli-configuration.md | 2 ++ 1 file changed, 2 insertions(+) (limited to 'doc') diff --git a/doc/md/Shaarli-configuration.md b/doc/md/Shaarli-configuration.md index 99084728..b1326cce 100644 --- a/doc/md/Shaarli-configuration.md +++ b/doc/md/Shaarli-configuration.md @@ -74,6 +74,7 @@ Some settings can be configured directly from a web browser by accesing the `Too "timezone": "Europe\/Paris", "title": "My Shaarli", "header_link": "?" + "tags_separator": " " }, "dev": { "debug": false, @@ -153,6 +154,7 @@ _These settings should not be edited_ - **enable_async_metadata** (boolean): Retrieve external bookmark metadata asynchronously to prevent bookmark creation slowdown. - **retrieve_description** (boolean): If set to true, for every new Shaare Shaarli will try to retrieve the description and keywords from the HTML meta tags. - **root_url**: Overrides automatic discovery of Shaarli instance's URL (e.g.) `https://sub.domain.tld/shaarli-folder/`. +- **tags_separator**: Defines your tags separator (default: whitespace). ### Security -- cgit v1.2.3 From ce901a58289c72bf7f4dc3515a2be70562cd618b Mon Sep 17 00:00:00 2001 From: ArthurHoaro Date: Sat, 7 Nov 2020 14:27:49 +0100 Subject: Reviewed nginx configuration Both in documentation and Docker image. For security purpose, it no longer allow to access static files through the main nginx *location*. Static files are served if their extension matches the whitelist. As a side effect, we no longer need specific restrictions, and therefore it fixes the nginx part of #1608. --- doc/md/Server-configuration.md | 23 +++-------------------- 1 file changed, 3 insertions(+), 20 deletions(-) (limited to 'doc') diff --git a/doc/md/Server-configuration.md b/doc/md/Server-configuration.md index 4e74d80b..5b8aff53 100644 --- a/doc/md/Server-configuration.md +++ b/doc/md/Server-configuration.md @@ -296,7 +296,7 @@ server { 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$ { @@ -309,23 +309,7 @@ server { 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/ { + location ~ /doc/html/ { default_type "text/html"; try_files $uri $uri/ $uri.html =404; } @@ -336,13 +320,12 @@ server { } # 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; } - } ``` -- cgit v1.2.3 From 8a9796014ce6c842095a9d031c8cbf40da761e0f Mon Sep 17 00:00:00 2001 From: ArthurHoaro Date: Sun, 8 Nov 2020 13:13:13 +0100 Subject: Reviewed Apache configuration (in documentation) For security purpose, block access to any static file not matching the list of allowed extensions. It allows us to remove the specific retriction on dotfiles, and fix Apache part of #1608. --- doc/md/Server-configuration.md | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) (limited to 'doc') diff --git a/doc/md/Server-configuration.md b/doc/md/Server-configuration.md index 4e74d80b..66db8c57 100644 --- a/doc/md/Server-configuration.md +++ b/doc/md/Server-configuration.md @@ -193,19 +193,24 @@ sudo nano /etc/apache2/sites-available/shaarli.mydomain.org.conf Require all granted - - # Prevent accessing dotfiles - RedirectMatch 404 ".*" - + # BE CAREFUL: directives order matter! - + + Require all denied + + + + Require all granted + + + # allow client-side caching of static files Header set Cache-Control "max-age=2628000, public, must-revalidate, proxy-revalidate" - + + # serve the Shaarli favicon from its custom location Alias favicon.ico /var/www/shaarli.mydomain.org/images/favicon.ico - ``` -- cgit v1.2.3 From b7c50a58dedc00a6d34793fc3393aaabf808ab94 Mon Sep 17 00:00:00 2001 From: ArthurHoaro Date: Mon, 9 Nov 2020 10:36:13 +0100 Subject: Docker-compose: fix SSL certificate + add parameter for Docker tag Use envvar SHAARLI_VIRTUAL_HOST for Traefik's docker.domain parameter instead of localhost (I'm not sure if did work at some point). Add an environment variable to choose which Docker tag to use instead of using master by default. Fixes #1632 --- doc/md/Docker.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) (limited to 'doc') diff --git a/doc/md/Docker.md b/doc/md/Docker.md index c152fe92..fc406c00 100644 --- a/doc/md/Docker.md +++ b/doc/md/Docker.md @@ -1,3 +1,4 @@ + # Docker [Docker](https://docs.docker.com/get-started/overview/) is an open platform for developing, shipping, and running applications @@ -113,9 +114,11 @@ $ mkdir shaarli && cd shaarli # Download the latest version of Shaarli's docker-compose.yml $ curl -L https://raw.githubusercontent.com/shaarli/Shaarli/latest/docker-compose.yml -o docker-compose.yml # Create the .env file and fill in your VPS and domain information -# (replace and with your actual information) +# (replace , and with your actual information) $ echo 'SHAARLI_VIRTUAL_HOST=shaarli.mydomain.org' > .env $ echo 'SHAARLI_LETSENCRYPT_EMAIL=admin@mydomain.org' >> .env +# Available Docker tags can be found at https://hub.docker.com/r/shaarli/shaarli/tags +$ echo 'SHAARLI_DOCKER_TAG=latest' >> .env # Pull the Docker images $ docker-compose pull # Run! @@ -224,4 +227,4 @@ $ docker system prune - [docker pull](https://docs.docker.com/engine/reference/commandline/pull/) - [docker run](https://docs.docker.com/engine/reference/commandline/run/) - [docker-compose logs](https://docs.docker.com/compose/reference/logs/) -- Træfik: [Getting Started](https://docs.traefik.io/), [Docker backend](https://docs.traefik.io/configuration/backends/docker/), [Let's Encrypt](https://docs.traefik.io/user-guide/docker-and-lets-encrypt/), [Docker image](https://hub.docker.com/_/traefik/) \ No newline at end of file +- Træfik: [Getting Started](https://docs.traefik.io/), [Docker backend](https://docs.traefik.io/configuration/backends/docker/), [Let's Encrypt](https://docs.traefik.io/user-guide/docker-and-lets-encrypt/), [Docker image](https://hub.docker.com/_/traefik/) -- cgit v1.2.3 From 2f4df753041088d788d1923692a7d530167a6840 Mon Sep 17 00:00:00 2001 From: ArthurHoaro Date: Mon, 9 Nov 2020 12:17:40 +0100 Subject: Update Static Analysis documentation --- doc/md/dev/Development.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) (limited to 'doc') diff --git a/doc/md/dev/Development.md b/doc/md/dev/Development.md index 5c085e03..c42e8ffe 100644 --- a/doc/md/dev/Development.md +++ b/doc/md/dev/Development.md @@ -6,7 +6,7 @@ Please read [Contributing to Shaarli](https://github.com/shaarli/Shaarli/tree/ma - [Unit tests](Unit-tests) -- Javascript linting - Shaarli uses [Airbnb JavaScript Style Guide](https://github.com/airbnb/javascript). +- Javascript linting - Shaarli uses [Airbnb JavaScript Style Guide](https://github.com/airbnb/javascript). Run `make eslint` to check JS style. - [GnuPG signature](GnuPG-signature) for tags/releases @@ -51,12 +51,12 @@ PHP (managed through [`composer.json`](https://github.com/shaarli/Shaarli/blob/m ## Link structure -Every link available through the `LinkDB` object is represented as an array +Every link available through the `LinkDB` object is represented as an array containing the following fields: * `id` (integer): Unique identifier. * `title` (string): Title of the link. - * `url` (string): URL of the link. Used for displayable links (without redirector, url encoding, etc.). + * `url` (string): URL of the link. Used for displayable links (without redirector, url encoding, etc.). Can be absolute or relative for Notes. * `real_url` (string): Real destination URL, can be redirected, encoded, etc. * `shorturl` (string): Permalink small hash. @@ -66,7 +66,7 @@ containing the following fields: * `thumbnail` (string|boolean): relative path of the thumbnail cache file, or false if there isn't any. * `created` (DateTime): link creation date time. * `updated` (DateTime): last modification date time. - + Small hashes are used to make a link to an entry in Shaarli. They are unique: the date of the item (eg. `20110923_150523`) is hashed with CRC32, then converted to base64 and some characters are replaced. They are always 6 characters longs and use only `A-Z a-z 0-9 - _` and `@`. @@ -163,11 +163,13 @@ See [`.travis.yml`](https://github.com/shaarli/Shaarli/blob/master/.travis.yml). ## Static analysis -Patches should try to stick to the [PHP Standard Recommendations](http://www.php-fig.org/psr/) (PSR), especially: +Patches should try to stick to the [PHP Standard Recommendations](http://www.php-fig.org/psr/) (PSR), and must follow: - [PSR-1](http://www.php-fig.org/psr/psr-1/) - Basic Coding Standard - [PSR-2](http://www.php-fig.org/psr/psr-2/) - Coding Style Guide +- [PSR-12](http://www.php-fig.org/psr/psr-12/) - Extended Coding Style Guide +These are enforced on pull requests using our Continuous Integration tools. **Work in progress:** Static analysis is currently being discussed here: in [#95 - Fix coding style (static analysis)](https://github.com/shaarli/Shaarli/issues/95), [#130 - Continuous Integration tools & features](https://github.com/shaarli/Shaarli/issues/130) -- cgit v1.2.3