Merge pull request #917 from virtualtam/documentation/fixes+improvements
Documentation fixes, improvements and additions
This commit is contained in:
VirtualTam
GitHub
commit
c7fcea1347
30 changed files with 445 additions and 378 deletions
|
|
@ -1,11 +1,3 @@
|
|||
|
||||
* [Backup and restore the datastore file](#backup-and-restore-the-datastore-file)
|
||||
* [Export links as...](#export-links-as)
|
||||
* [Import links from...](#import-links-from)
|
||||
* [Import Shaarli links to Firefox](#import-shaarli-links-to-firefox)
|
||||
|
||||
----------------------
|
||||
|
||||
## Backup and restore the datastore file
|
||||
|
||||
Backup the file `data/datastore.php` (by FTP or SSH). Restore by putting the file back in place.
|
||||
|
|
@ -18,12 +10,14 @@ rsync -avzP my.server.com:/var/www/shaarli/data/datastore.php datastore-$(date +
|
|||
## Export links as...
|
||||
|
||||
To export links as an HTML file, under _Tools > Export_, choose:
|
||||
|
||||
- _Export all_ to export both public and private links
|
||||
- _Export public_ to export public links only
|
||||
- _Export private_ to export private links only
|
||||
|
||||
Restore by using the `Import` feature.
|
||||
* This can be done using the [shaarchiver](https://github.com/nodiscc/shaarchiver) tool.
|
||||
|
||||
- This can be done using the [shaarchiver](https://github.com/nodiscc/shaarchiver) tool.
|
||||
|
||||
Example command:
|
||||
```bash
|
||||
|
|
@ -46,18 +40,21 @@ To correctly import the tags from a [SemanticScuttle](http://semanticscuttle.sou
|
|||
|
||||
### Scuttle
|
||||
|
||||
Shaarli cannot import data directly from [Scuttle](https://github.com/scronide/scuttle). However, you can use this third party tool: https://github.com/q2apro/scuttle-to-shaarli to export the Scuttle database to the Netscape HTML format compatible with the Shaarli importer.
|
||||
Shaarli cannot import data directly from [Scuttle](https://github.com/scronide/scuttle).
|
||||
|
||||
However, you can use the third-party [scuttle-to-shaarli](https://github.com/q2apro/scuttle-to-shaarli)
|
||||
tool to export the Scuttle database to the Netscape HTML format compatible with the Shaarli importer.
|
||||
|
||||
## Import Shaarli links to Firefox
|
||||
|
||||
* Export your Shaarli links as described above.
|
||||
* For compatibility reasons, check `Prepend note permalinks with this Shaarli instance's URL (useful to import bookmarks in a web browser)`
|
||||
* In Firefox, open the bookmark manager (not the sidebar! `Bookmarks menu > Show all bookmarks` or `Ctrl+Shift+B`)
|
||||
* Select `Import and Backup > Import bookmarks in HTML format`
|
||||
- Export your Shaarli links as described above.
|
||||
- For compatibility reasons, check `Prepend note permalinks with this Shaarli instance's URL (useful to import bookmarks in a web browser)`
|
||||
- In Firefox, open the bookmark manager (not the sidebar! `Bookmarks menu > Show all bookmarks` or `Ctrl+Shift+B`)
|
||||
- Select `Import and Backup > Import bookmarks in HTML format`
|
||||
|
||||
Your bookmarks will be imported in Firefox, ready to use, with tags and descriptions retained. "Self" (notes) shaares will still point to the Shaarli instance you exported them from, but the note text can be viewed directly in the bookmark properties inside your browser. Depending on the number of bookmarks, the import can take some time.
|
||||
|
||||
You may be interested in these Firefox addons to manage links imported from Shaarli
|
||||
|
||||
* [Bookmark Deduplicator](https://addons.mozilla.org/en-US/firefox/addon/bookmark-deduplicator/) - provides an easy way to deduplicate your bookmarks
|
||||
* [TagSieve](https://addons.mozilla.org/en-US/firefox/addon/tagsieve/) - browse your bookmarks by their tags
|
||||
- [Bookmark Deduplicator](https://addons.mozilla.org/en-US/firefox/addon/bookmark-deduplicator/) - provides an easy way to deduplicate your bookmarks
|
||||
- [TagSieve](https://addons.mozilla.org/en-US/firefox/addon/tagsieve/) - browse your bookmarks by their tags
|
||||
|
|
|
|||
|
|
@ -1,23 +1,23 @@
|
|||
### Add the sharing button (_bookmarklet_) to your browser
|
||||
## Add the sharing button (_bookmarklet_) to your browser
|
||||
|
||||
* Open your Shaarli and `Login`
|
||||
* Click the `Tools` button in the top bar
|
||||
* Drag the **`✚Shaare link` button**, and drop it to your browser's bookmarks bar.
|
||||
- Open your Shaarli and `Login`
|
||||
- Click the `Tools` button in the top bar
|
||||
- Drag the **`✚Shaare link` button**, and drop it to your browser's bookmarks bar.
|
||||
|
||||
_This bookmarklet button is compatible with Firefox, Opera, Chrome and Safari. Under Opera, you can't drag'n drop the button: You have to right-click on it and add a bookmark to your personal toolbar._
|
||||
|
||||
|
||||
|
||||
### Share links using the _bookmarklet_
|
||||
## Share links using the _bookmarklet_
|
||||
|
||||
* When you are visiting a webpage you would like to share with Shaarli, click the _bookmarklet_ you just added.
|
||||
* A window opens.
|
||||
* You can freely edit title, description, tags... to find it later using the text search or tag filtering.
|
||||
* You will be able to edit this link later using the  edit button.
|
||||
* You can also check the “Private” box so that the link is saved but only visible to you.
|
||||
* Click `Save`.**Voilà! Your link is now shared.**
|
||||
- When you are visiting a webpage you would like to share with Shaarli, click the _bookmarklet_ you just added.
|
||||
- A window opens.
|
||||
- You can freely edit title, description, tags... to find it later using the text search or tag filtering.
|
||||
- You will be able to edit this link later using the  edit button.
|
||||
- You can also check the “Private” box so that the link is saved but only visible to you.
|
||||
- Click `Save`.**Voilà! Your link is now shared.**
|
||||
|
||||
### Troubleshooting: The bookmarklet doesn't work with a few website (e.g. Github.com)
|
||||
## Troubleshooting: The bookmarklet doesn't work with a few websites (e.g. Github.com)
|
||||
|
||||
Websites which enforce Content Security Policy (CSP), such as github.com, disallow usage of bookmarklets. Unfortunatly, there is nothing Shaarli can do about it.
|
||||
|
||||
|
|
@ -25,6 +25,5 @@ See [#196](https://github.com/shaarli/Shaarli#196).
|
|||
|
||||
There is an open bug for both Firefox and Chromium:
|
||||
|
||||
* https://bugzilla.mozilla.org/show_bug.cgi?id=866522
|
||||
* https://code.google.com/p/chromium/issues/detail?id=233903
|
||||
|
||||
- https://bugzilla.mozilla.org/show_bug.cgi?id=866522
|
||||
- https://code.google.com/p/chromium/issues/detail?id=233903
|
||||
|
|
|
|||
|
|
@ -1,5 +0,0 @@
|
|||
## WIP
|
||||
|
||||
This topic is currently being discussed here:
|
||||
- [Fix coding style (static analysis)](https://github.com/shaarli/Shaarli/issues/95) (#95)
|
||||
- [Continuous Integration tools & features](https://github.com/shaarli/Shaarli/issues/130) (#130)
|
||||
|
|
@ -22,15 +22,15 @@ _TODO: contact repos owners to see if they'd like to standardize their work with
|
|||
### Third party plugins
|
||||
|
||||
|
||||
* [autosave](https://github.com/kalvn/shaarli-plugin-autosave) by [@kalvn](https://github.com/kalvn): Automatically saves data when editing a link to avoid any loss in case of crash or unexpected shutdown.
|
||||
* [Code Coloration](https://github.com/ArthurHoaro/code-coloration) by [@ArthurHoaro](https://github.com/ArthurHoaro): client side code syntax highlighter.
|
||||
* [Disqus](https://github.com/kalvn/shaarli-plugin-disqus) by [@kalvn](https://github.com/kalvn): Adds Disqus comment system to your Shaarli.
|
||||
* [emojione](https://github.com/NerosTie/emojione) by [@NerosTie](https://github.com/NerosTie): Add colorful emojis to your Shaarli.
|
||||
* [google analytics](https://github.com/ericjuden/Shaarli-Google-Analytics-Plugin) by [@ericjuden](http://github.com/ericjuden): Adds Google Analytics tracking support
|
||||
* [launch](https://github.com/ArthurHoaro/launch-plugin) - Launch Plugin is a plugin designed to enhance and customize Launch Theme for Shaarli.
|
||||
* [related](https://github.com/ilesinge/shaarli-related) by [@ilesinge](https://github.com/ilesinge) - Show related links based on the number of identical tags.
|
||||
* [social](https://github.com/alexisju/social) by [@alexisju](https://github.com/alexisju): share links to social networks.
|
||||
* [shaarli2twitter](https://github.com/ArthurHoaro/shaarli2twitter) by [@ArthurHoaro](https://github.com/ArthurHoaro) - Automatically tweet your shared links from Shaarli
|
||||
- [autosave](https://github.com/kalvn/shaarli-plugin-autosave) by [@kalvn](https://github.com/kalvn): Automatically saves data when editing a link to avoid any loss in case of crash or unexpected shutdown.
|
||||
- [Code Coloration](https://github.com/ArthurHoaro/code-coloration) by [@ArthurHoaro](https://github.com/ArthurHoaro): client side code syntax highlighter.
|
||||
- [Disqus](https://github.com/kalvn/shaarli-plugin-disqus) by [@kalvn](https://github.com/kalvn): Adds Disqus comment system to your Shaarli.
|
||||
- [emojione](https://github.com/NerosTie/emojione) by [@NerosTie](https://github.com/NerosTie): Add colorful emojis to your Shaarli.
|
||||
- [google analytics](https://github.com/ericjuden/Shaarli-Google-Analytics-Plugin) by [@ericjuden](http://github.com/ericjuden): Adds Google Analytics tracking support
|
||||
- [launch](https://github.com/ArthurHoaro/launch-plugin) - Launch Plugin is a plugin designed to enhance and customize Launch Theme for Shaarli.
|
||||
- [related](https://github.com/ilesinge/shaarli-related) by [@ilesinge](https://github.com/ilesinge) - Show related links based on the number of identical tags.
|
||||
- [social](https://github.com/alexisju/social) by [@alexisju](https://github.com/alexisju): share links to social networks.
|
||||
- [shaarli2twitter](https://github.com/ArthurHoaro/shaarli2twitter) by [@ArthurHoaro](https://github.com/ArthurHoaro) - Automatically tweet your shared links from Shaarli
|
||||
|
||||
|
||||
### Themes
|
||||
|
|
|
|||
|
|
@ -1,22 +1,26 @@
|
|||
## Local development
|
||||
A [`Makefile`](https://github.com/shaarli/Shaarli/blob/master/Makefile) is available to perform project-related operations:
|
||||
|
||||
- Documentation - generate a local HTML copy of the GitHub wiki
|
||||
- [Static analysis](Static analysis) - check that the code is compliant to PHP conventions
|
||||
- [Unit tests](Unit tests) - ensure there are no regressions introduced by new commits
|
||||
|
||||
## Automatic builds
|
||||
[Travis CI](http://docs.travis-ci.com/) is a Continuous Integration build server, that runs a build:
|
||||
|
||||
- each time a commit is merged to the mainline (`master` branch)
|
||||
- each time a Pull Request is submitted or updated
|
||||
|
||||
A build is composed of several jobs: one for each supported PHP version (see [Server requirements](Server requirements)).
|
||||
|
||||
Each build job:
|
||||
|
||||
- updates Composer
|
||||
- installs 3rd-party test dependencies with Composer
|
||||
- runs [Unit tests](Unit tests)
|
||||
|
||||
After all jobs have finished, Travis returns the results to GitHub:
|
||||
|
||||
- a status icon represents the result for the `master` branch: [](https://travis-ci.org/shaarli/Shaarli)
|
||||
- Pull Requests are updated with the Travis result
|
||||
- Green: all tests have passed
|
||||
|
|
|
|||
|
|
@ -1,6 +1,7 @@
|
|||
## Development guidelines
|
||||
|
||||
Please have a look at the following pages:
|
||||
|
||||
- [Contributing to Shaarli](https://github.com/shaarli/Shaarli/tree/master/CONTRIBUTING.md)
|
||||
- [Static analysis](Static analysis) - patches should try to stick to the [PHP Standard Recommendations](http://www.php-fig.org/psr/) (PSR), especially:
|
||||
- [PSR-1](http://www.php-fig.org/psr/psr-1/) - Basic Coding Standard
|
||||
|
|
|
|||
|
|
@ -1,8 +1,16 @@
|
|||
To install Shaarli, simply place the files in a directory under your webserver's Document Root (or directly at the document root). Make sure your [server](Server-requirements) is properly [configured](Server-configuration).
|
||||
To install Shaarli, simply place the files in a directory under your webserver's
|
||||
Document Root (or directly at the document root).
|
||||
|
||||
Also, please make sure your server meets the [requirements](Server-requirements)
|
||||
and is properly [configured](Server-configuration).
|
||||
|
||||
Several releases are available:
|
||||
|
||||
--------------------------------------------------------
|
||||
- by downloading full release archives including all dependencies
|
||||
- by downloading Github archives
|
||||
- by cloning the Git repository
|
||||
|
||||
---
|
||||
|
||||
## Latest release (recommended)
|
||||
### Download as an archive
|
||||
|
|
@ -10,29 +18,26 @@ Get the latest released version from the [releases](https://github.com/shaarli/S
|
|||
|
||||
**Download our *shaarli-full* archive** to include dependencies.
|
||||
|
||||
The current latest released version is `v0.8.4`
|
||||
The current latest released version is `v0.9.0`
|
||||
|
||||
Or in command lines:
|
||||
|
||||
```bash
|
||||
$ wget https://github.com/shaarli/Shaarli/releases/download/v0.8.4/shaarli-v0.8.4-full.zip
|
||||
$ unzip shaarli-v0.8.4-full.zip
|
||||
$ wget https://github.com/shaarli/Shaarli/releases/download/v0.9.0/shaarli-v0.9.0-full.zip
|
||||
$ unzip shaarli-v0.9.0-full.zip
|
||||
$ mv Shaarli /path/to/shaarli/
|
||||
```
|
||||
|
||||
| ! |In most cases, download Shaarli from the [releases](https://github.com/shaarli/Shaarli/releases) page. Cloning using `git` or downloading Github branches as zip files requires additional steps (see below).|
|
||||
|-----|--------------------------|
|
||||
In most cases, download Shaarli from the [releases](https://github.com/shaarli/Shaarli/releases) page. Cloning using `git` or downloading Github branches as zip files requires additional steps (see below).|
|
||||
|
||||
### Using git
|
||||
|
||||
```
|
||||
mkdir -p /path/to/shaarli && cd /path/to/shaarli/
|
||||
git clone -b v0.8 https://github.com/shaarli/Shaarli.git .
|
||||
composer install --no-dev
|
||||
$ mkdir -p /path/to/shaarli && cd /path/to/shaarli/
|
||||
$ git clone -b v0.9 https://github.com/shaarli/Shaarli.git .
|
||||
$ composer install --no-dev --prefer-dist
|
||||
```
|
||||
|
||||
--------------------------------------------------------
|
||||
|
||||
## Stable version
|
||||
|
||||
The stable version has been experienced by Shaarli users, and will receive security updates.
|
||||
|
|
@ -63,11 +68,9 @@ $ mv Shaarli-stable /path/to/shaarli/
|
|||
$ git clone https://github.com/shaarli/Shaarli.git -b stable /path/to/shaarli/
|
||||
# install/update third-party dependencies
|
||||
$ cd /path/to/shaarli/
|
||||
$ composer install --no-dev
|
||||
$ composer install --no-dev --prefer-dist
|
||||
```
|
||||
|
||||
--------------------------------------------------------
|
||||
|
||||
## Development version (mainline)
|
||||
|
||||
_Use at your own risk!_
|
||||
|
|
@ -79,11 +82,9 @@ To get the latest changes from the `master` branch:
|
|||
$ git clone https://github.com/shaarli/Shaarli.git -b master /path/to/shaarli/
|
||||
# install/update third-party dependencies
|
||||
$ cd /path/to/shaarli
|
||||
$ composer install --no-dev
|
||||
$ composer install --no-dev --prefer-dist
|
||||
```
|
||||
|
||||
--------------------------------------------------------
|
||||
|
||||
## Finish Installation
|
||||
|
||||
Once Shaarli is downloaded and files have been placed at the correct location, open it this location your favorite browser.
|
||||
|
|
@ -92,8 +93,6 @@ Once Shaarli is downloaded and files have been placed at the correct location, o
|
|||
|
||||
Setup your Shaarli installation, and it's ready to use!
|
||||
|
||||
--------------------------------------------------------
|
||||
|
||||
## Updating Shaarli
|
||||
|
||||
See [Upgrade and Migration](Upgrade-and-migration)
|
||||
|
|
|
|||
|
|
@ -8,23 +8,24 @@ Enough is enough. Saving simple links should not be a complicated heavy thing. I
|
|||
|
||||
With Shaarli:
|
||||
|
||||
* The data is yours: It's hosted on your server.
|
||||
* Never fear of having your data locked-in.
|
||||
* Never fear to have your data sold to third party.
|
||||
* Your private links are not hosted on a third party server.
|
||||
* You are not tracked by browser addons (like Diigo does)
|
||||
* You can change the look and feel of the pages if you want.
|
||||
* You can change the behaviour of the program.
|
||||
* It's magnitude faster than most bookmarking services.
|
||||
- The data is yours: It's hosted on your server.
|
||||
- Never fear of having your data locked-in.
|
||||
- Never fear to have your data sold to third party.
|
||||
- Your private links are not hosted on a third party server.
|
||||
- You are not tracked by browser addons (like Diigo does)
|
||||
- You can change the look and feel of the pages if you want.
|
||||
- You can change the behaviour of the program.
|
||||
- It's magnitude faster than most bookmarking services.
|
||||
|
||||
### What does Shaarli mean?
|
||||
|
||||
Shaarli is for shaaring your links.
|
||||
Shaarli stands for _shaaring_ your _links_.
|
||||
|
||||
### My Shaarli is broken!
|
||||
First of all, ensure that both the [web server](Server-configuration) and [Shaarli](Shaarli-configuration) are correctly configured, and that your installation is [supported](Server-requirements).
|
||||
|
||||
If everything looks right but the issue(s) remain(s), please:
|
||||
|
||||
- take a look at the [troubleshooting](Troubleshooting) section
|
||||
- come [chat with us](https://gitter.im/shaarli/Shaarli) on Gitter, we'll be happy to help ;-)
|
||||
- browse active [issues](https://github.com/shaarli/Shaarli/issues) and [Pull Requests](https://github.com/shaarli/Shaarli/pulls)
|
||||
|
|
|
|||
|
|
@ -1,24 +1,25 @@
|
|||
### Main features
|
||||
Shaarli is intended:
|
||||
* to share, comment and save interesting links and news
|
||||
* to bookmark useful/frequent personal links (as private links) and share them between computers
|
||||
* as a minimal blog/microblog/writing platform (no character limit)
|
||||
* as a read-it-later list (for example items tagged `readlater`)
|
||||
* to draft and save articles/ideas
|
||||
* to keep code snippets
|
||||
* to keep notes and documentation
|
||||
* as a shared clipboard between machines
|
||||
* as a todo list
|
||||
* to store playlists (e.g. with the `music` or `video` tags)
|
||||
* to keep extracts/comments from webpages that may disappear
|
||||
* to keep track of ongoing discussions (for example items tagged `discussion`)
|
||||
* [to feed RSS aggregators](http://shaarli.chassegnouf.net/?9Efeiw) (planets) with specific tags
|
||||
* to feed other social networks, blogs... using RSS feeds and external services (dlvr.it, ifttt.com ...)
|
||||
|
||||
- to share, comment and save interesting links and news
|
||||
- to bookmark useful/frequent personal links (as private links) and share them between computers
|
||||
- as a minimal blog/microblog/writing platform (no character limit)
|
||||
- as a read-it-later list (for example items tagged `readlater`)
|
||||
- to draft and save articles/ideas
|
||||
- to keep code snippets
|
||||
- to keep notes and documentation
|
||||
- as a shared clipboard between machines
|
||||
- as a todo list
|
||||
- to store playlists (e.g. with the `music` or `video` tags)
|
||||
- to keep extracts/comments from webpages that may disappear
|
||||
- to keep track of ongoing discussions (for example items tagged `discussion`)
|
||||
- [to feed RSS aggregators](http://shaarli.chassegnouf.net/?9Efeiw) (planets) with specific tags
|
||||
- to feed other social networks, blogs... using RSS feeds and external services (dlvr.it, ifttt.com ...)
|
||||
|
||||
### Using Shaarli as a blog, notepad, pastebin...
|
||||
|
||||
* Go to your Shaarli setup and log in
|
||||
* Click the `Add Link` button
|
||||
* To share text only, do not enter any URL in the corresponding input field and click `Add Link`
|
||||
* Pick a title and enter your article, or note, in the description field; add a few tags; optionally check `Private` then click `Save`
|
||||
* Voilà! Your article is now published (privately if you selected that option) and accessible using its permalink.
|
||||
- Go to your Shaarli setup and log in
|
||||
- Click the `Add Link` button
|
||||
- To share text only, do not enter any URL in the corresponding input field and click `Add Link`
|
||||
- Pick a title and enter your article, or note, in the description field; add a few tags; optionally check `Private` then click `Save`
|
||||
- Voilà! Your article is now published (privately if you selected that option) and accessible using its permalink.
|
||||
|
|
|
|||
|
|
@ -1,15 +1,17 @@
|
|||
### Add Shaarli as a sharing service to Firefox
|
||||
|
||||
* Open your Shaarli and `Login`
|
||||
* Click the `Tools` button in the top bar
|
||||
* Click the `✚Add to Firefox social` button and accept the activation.
|
||||
- Open your Shaarli and `Login`
|
||||
- Click the `Tools` button in the top bar
|
||||
- Click the `✚Add to Firefox social` button and accept the activation.
|
||||
|
||||
|
||||
### Sharing links using Firefox share
|
||||
|
||||
* Add the sharing service as described above
|
||||
* When you are visiting a webpage you would like to share with Shaarli, click the Firefox _Share_ button [images/firefoxshare.png](images/firefoxshare.png)
|
||||
* You can edit your link before and after saving, just like the bookmarklet above.
|
||||
- Add the sharing service as described above
|
||||
- When you are visiting a webpage you would like to share with Shaarli,
|
||||
click the Firefox _Share_ button [images/firefoxshare.png](images/firefoxshare.png)
|
||||
- You can edit your link before and after saving, just like the bookmarklet above.
|
||||
|
||||
| | Your Shaarli instance must be hosted on an HTTPS (SSL/TLS secure connection) enabled server for Firefox Share to work. Firefox Share will not work over plain HTTP connections. |
|
||||
|------|-------------------------------------------------------------------------------|
|
||||
_Your Shaarli instance must be hosted on an HTTPS (SSL/TLS secure connection)
|
||||
enabled server for Firefox Share to work. Firefox Share will not work over
|
||||
plain HTTP connections._
|
||||
|
|
|
|||
|
|
@ -1,10 +1,11 @@
|
|||
## Introduction
|
||||
### PGP and GPG
|
||||
[Gnu Privacy Guard](https://gnupg.org/) (GnuPG) is an Open Source implementation of the [Pretty Good
|
||||
Privacy](https://en.wikipedia.org/wiki/Pretty_Good_Privacy#OpenPGP) (OpenPGP) specification. Its main purposes are digital authentication,
|
||||
signature and encryption.
|
||||
[Gnu Privacy Guard](https://gnupg.org/) (GnuPG) is an Open Source implementation of the
|
||||
[Pretty Good Privacy](https://en.wikipedia.org/wiki/Pretty_Good_Privacy#OpenPGP)
|
||||
(OpenPGP) specification. Its main purposes are digital authentication, signature and encryption.
|
||||
|
||||
It is often used by the [FLOSS](https://en.wikipedia.org/wiki/Free_and_open-source_software) community to verify:
|
||||
|
||||
- Linux package signatures: Debian [SecureApt](https://wiki.debian.org/SecureApt), ArchLinux [Master
|
||||
Keys](https://www.archlinux.org/master-keys/)
|
||||
- [SCM](https://en.wikipedia.org/wiki/Revision_control) releases & maintainer identity
|
||||
|
|
@ -15,6 +16,7 @@ To quote Phil Pennock (the author of the [SKS](https://bitbucket.org/skskeyserve
|
|||
> You MUST understand that presence of data in the keyserver (pools) in no way connotes trust. Anyone can generate a key, with any name or email address, and upload it. All security and trust comes from evaluating security at the “object level”, via PGP Web-Of-Trust signatures. This keyserver makes it possible to retrieve keys, looking them up via various indices, but the collection of keys in this public pool is KNOWN to contain malicious and fraudulent keys. It is the common expectation of server operators that users understand this and use software which, like all known common OpenPGP implementations, evaluates trust accordingly. This expectation is so common that it is not normally explicitly stated.
|
||||
|
||||
Trust can be gained by having your key signed by other people (and signing their key back, too :) ), for instance during [key signing parties](https://en.wikipedia.org/wiki/Key_signing_party), see:
|
||||
|
||||
- [The Keysigning party HOWTO](http://www.cryptnet.net/fdp/crypto/keysigning_party/en/keysigning_party.html)
|
||||
- [Web of trust](https://en.wikipedia.org/wiki/Web_of_trust)
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,8 @@
|
|||
[**I am a developer.** Developer API.](#developer-api)
|
||||
[**I am a developer: ** Developer API](#developer-api)
|
||||
|
||||
[**I am a template designer.** Guide for template designer.](#guide-for-template-designer)
|
||||
[**I am a template designer: ** Guide for template designers](#guide-for-template-designer)
|
||||
|
||||
---
|
||||
|
||||
## Developer API
|
||||
|
||||
|
|
@ -8,9 +10,9 @@
|
|||
|
||||
The plugin system let you:
|
||||
|
||||
* insert content into specific places across templates.
|
||||
* alter data before templates rendering.
|
||||
* alter data before saving new links.
|
||||
- insert content into specific places across templates.
|
||||
- alter data before templates rendering.
|
||||
- alter data before saving new links.
|
||||
|
||||
### How can I create a plugin for Shaarli?
|
||||
|
||||
|
|
@ -106,9 +108,9 @@ Every plugin needs a `<plugin_name>.meta` file, which is in fact an `.ini` file
|
|||
|
||||
Each file contain two keys:
|
||||
|
||||
* `description`: plugin description
|
||||
* `parameters`: user parameter names, separated by a `;`.
|
||||
* `parameter.<PARAMETER_NAME>`: add a text description the specified parameter.
|
||||
- `description`: plugin description
|
||||
- `parameters`: user parameter names, separated by a `;`.
|
||||
- `parameter.<PARAMETER_NAME>`: add a text description the specified parameter.
|
||||
|
||||
> Note: In PHP, `parse_ini_file()` seems to want strings to be between by quotes `"` in the ini file.
|
||||
|
||||
|
|
@ -148,8 +150,8 @@ Allow plugin to add content in page headers.
|
|||
|
||||
`$data` is an array containing:
|
||||
|
||||
* `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.).
|
||||
* `_LOGGEDIN_`: true if user is logged in, false otherwise.
|
||||
- `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.).
|
||||
- `_LOGGEDIN_`: true if user is logged in, false otherwise.
|
||||
|
||||
##### Template placeholders
|
||||
|
||||
|
|
@ -157,11 +159,11 @@ Items can be displayed in templates by adding an entry in `$data['<placeholder>'
|
|||
|
||||
List of placeholders:
|
||||
|
||||
* `buttons_toolbar`: after the list of buttons in the header.
|
||||
- `buttons_toolbar`: after the list of buttons in the header.
|
||||
|
||||
|
||||
|
||||
* `fields_toolbar`: after search fields in the header.
|
||||
- `fields_toolbar`: after search fields in the header.
|
||||
|
||||
> Note: This will only be called in linklist.
|
||||
|
||||
|
|
@ -177,8 +179,8 @@ Allow plugin to include their own CSS files.
|
|||
|
||||
`$data` is an array containing:
|
||||
|
||||
* `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.).
|
||||
* `_LOGGEDIN_`: true if user is logged in, false otherwise.
|
||||
- `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.).
|
||||
- `_LOGGEDIN_`: true if user is logged in, false otherwise.
|
||||
|
||||
##### Template placeholders
|
||||
|
||||
|
|
@ -186,7 +188,7 @@ Items can be displayed in templates by adding an entry in `$data['<placeholder>'
|
|||
|
||||
List of placeholders:
|
||||
|
||||
* `css_files`: called after loading default CSS.
|
||||
- `css_files`: called after loading default CSS.
|
||||
|
||||
> Note: only add the path of the CSS file. E.g: `plugins/demo_plugin/custom_demo.css`.
|
||||
|
||||
|
|
@ -200,8 +202,8 @@ Allow plugin to add content in page footer and include their own JS files.
|
|||
|
||||
`$data` is an array containing:
|
||||
|
||||
* `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.).
|
||||
* `_LOGGEDIN_`: true if user is logged in, false otherwise.
|
||||
- `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.).
|
||||
- `_LOGGEDIN_`: true if user is logged in, false otherwise.
|
||||
|
||||
##### Template placeholders
|
||||
|
||||
|
|
@ -209,12 +211,12 @@ Items can be displayed in templates by adding an entry in `$data['<placeholder>'
|
|||
|
||||
List of placeholders:
|
||||
|
||||
* `text`: called after the end of the footer text.
|
||||
* `endofpage`: called at the end of the page.
|
||||
- `text`: called after the end of the footer text.
|
||||
- `endofpage`: called at the end of the page.
|
||||
|
||||
|
||||
|
||||
* `js_files`: called at the end of the page, to include custom JS scripts.
|
||||
- `js_files`: called at the end of the page, to include custom JS scripts.
|
||||
|
||||
> Note: only add the path of the JS file. E.g: `plugins/demo_plugin/custom_demo.js`.
|
||||
|
||||
|
|
@ -228,8 +230,8 @@ It allows to add content at the begining and end of the page, after every link d
|
|||
|
||||
`$data` is an array containing:
|
||||
|
||||
* `_LOGGEDIN_`: true if user is logged in, false otherwise.
|
||||
* All templates data, including links.
|
||||
- `_LOGGEDIN_`: true if user is logged in, false otherwise.
|
||||
- All templates data, including links.
|
||||
|
||||
##### Template placeholders
|
||||
|
||||
|
|
@ -237,19 +239,19 @@ Items can be displayed in templates by adding an entry in `$data['<placeholder>'
|
|||
|
||||
List of placeholders:
|
||||
|
||||
* `action_plugin`: next to the button "private only" at the top and bottom of the page.
|
||||
- `action_plugin`: next to the button "private only" at the top and bottom of the page.
|
||||
|
||||
|
||||
|
||||
* `link_plugin`: for every link, between permalink and link URL.
|
||||
- `link_plugin`: for every link, between permalink and link URL.
|
||||
|
||||
|
||||
|
||||
* `plugin_start_zone`: before displaying the template content.
|
||||
- `plugin_start_zone`: before displaying the template content.
|
||||
|
||||
|
||||
|
||||
* `plugin_end_zone`: after displaying the template content.
|
||||
- `plugin_end_zone`: after displaying the template content.
|
||||
|
||||
|
||||
|
||||
|
|
@ -263,7 +265,7 @@ Allow to add fields in the form, or display elements.
|
|||
|
||||
`$data` is an array containing:
|
||||
|
||||
* All templates data.
|
||||
- All templates data.
|
||||
|
||||
##### Template placeholders
|
||||
|
||||
|
|
@ -271,7 +273,7 @@ Items can be displayed in templates by adding an entry in `$data['<placeholder>'
|
|||
|
||||
List of placeholders:
|
||||
|
||||
* `edit_link_plugin`: after tags field.
|
||||
- `edit_link_plugin`: after tags field.
|
||||
|
||||
|
||||
|
||||
|
|
@ -285,7 +287,7 @@ Allow to add content at the end of the page.
|
|||
|
||||
`$data` is an array containing:
|
||||
|
||||
* All templates data.
|
||||
- All templates data.
|
||||
|
||||
##### Template placeholders
|
||||
|
||||
|
|
@ -293,7 +295,7 @@ Items can be displayed in templates by adding an entry in `$data['<placeholder>'
|
|||
|
||||
List of placeholders:
|
||||
|
||||
* `tools_plugin`: at the end of the page.
|
||||
- `tools_plugin`: at the end of the page.
|
||||
|
||||
|
||||
|
||||
|
|
@ -307,8 +309,8 @@ Allow to add content at the top and bottom of the page.
|
|||
|
||||
`$data` is an array containing:
|
||||
|
||||
* `_LOGGEDIN_`: true if user is logged in, false otherwise.
|
||||
* All templates data.
|
||||
- `_LOGGEDIN_`: true if user is logged in, false otherwise.
|
||||
- All templates data.
|
||||
|
||||
##### Template placeholders
|
||||
|
||||
|
|
@ -316,9 +318,8 @@ Items can be displayed in templates by adding an entry in `$data['<placeholder>'
|
|||
|
||||
List of placeholders:
|
||||
|
||||
* `plugin_start_zone`: before displaying the template content.
|
||||
|
||||
* `plugin_end_zone`: after displaying the template content.
|
||||
- `plugin_start_zone`: before displaying the template content.
|
||||
- `plugin_end_zone`: after displaying the template content.
|
||||
|
||||
|
||||
|
||||
|
|
@ -332,8 +333,8 @@ Allow to add content at the top and bottom of the page.
|
|||
|
||||
`$data` is an array containing:
|
||||
|
||||
* `_LOGGEDIN_`: true if user is logged in, false otherwise.
|
||||
* All templates data.
|
||||
- `_LOGGEDIN_`: true if user is logged in, false otherwise.
|
||||
- All templates data.
|
||||
|
||||
##### Template placeholders
|
||||
|
||||
|
|
@ -341,13 +342,12 @@ Items can be displayed in templates by adding an entry in `$data['<placeholder>'
|
|||
|
||||
List of placeholders:
|
||||
|
||||
* `plugin_start_zone`: before displaying the template content.
|
||||
|
||||
* `plugin_end_zone`: after displaying the template content.
|
||||
- `plugin_start_zone`: before displaying the template content.
|
||||
- `plugin_end_zone`: after displaying the template content.
|
||||
|
||||
For each tag, the following placeholder can be used:
|
||||
|
||||
* `tag_plugin`: after each tag
|
||||
- `tag_plugin`: after each tag
|
||||
|
||||
|
||||
|
||||
|
|
@ -362,8 +362,8 @@ Allow to add content at the top and bottom of the page.
|
|||
|
||||
`$data` is an array containing:
|
||||
|
||||
* `_LOGGEDIN_`: true if user is logged in, false otherwise.
|
||||
* All templates data.
|
||||
- `_LOGGEDIN_`: true if user is logged in, false otherwise.
|
||||
- All templates data.
|
||||
|
||||
##### Template placeholders
|
||||
|
||||
|
|
@ -371,13 +371,12 @@ Items can be displayed in templates by adding an entry in `$data['<placeholder>'
|
|||
|
||||
List of placeholders:
|
||||
|
||||
* `plugin_start_zone`: before displaying the template content.
|
||||
|
||||
* `plugin_end_zone`: after displaying the template content.
|
||||
- `plugin_start_zone`: before displaying the template content.
|
||||
- `plugin_end_zone`: after displaying the template content.
|
||||
|
||||
For each tag, the following placeholder can be used:
|
||||
|
||||
* `tag_plugin`: after each tag
|
||||
- `tag_plugin`: after each tag
|
||||
|
||||
#### render_daily
|
||||
|
||||
|
|
@ -389,8 +388,8 @@ Allow to add content at the top and bottom of the page, the bottom of each link
|
|||
|
||||
`$data` is an array containing:
|
||||
|
||||
* `_LOGGEDIN_`: true if user is logged in, false otherwise.
|
||||
* All templates data, including links.
|
||||
- `_LOGGEDIN_`: true if user is logged in, false otherwise.
|
||||
- All templates data, including links.
|
||||
|
||||
##### Template placeholders
|
||||
|
||||
|
|
@ -398,13 +397,12 @@ Items can be displayed in templates by adding an entry in `$data['<placeholder>'
|
|||
|
||||
List of placeholders:
|
||||
|
||||
* `link_plugin`: used at bottom of each link.
|
||||
- `link_plugin`: used at bottom of each link.
|
||||
|
||||
|
||||
|
||||
* `plugin_start_zone`: before displaying the template content.
|
||||
|
||||
* `plugin_end_zone`: after displaying the template content.
|
||||
- `plugin_start_zone`: before displaying the template content.
|
||||
- `plugin_end_zone`: after displaying the template content.
|
||||
|
||||
#### render_feed
|
||||
|
||||
|
|
@ -416,9 +414,9 @@ Allow to add tags in the feed, either in the header or for each items. Items (li
|
|||
|
||||
`$data` is an array containing:
|
||||
|
||||
* `_LOGGEDIN_`: true if user is logged in, false otherwise.
|
||||
* `_PAGE_`: containing either `rss` or `atom`.
|
||||
* All templates data, including links.
|
||||
- `_LOGGEDIN_`: true if user is logged in, false otherwise.
|
||||
- `_PAGE_`: containing either `rss` or `atom`.
|
||||
- All templates data, including links.
|
||||
|
||||
##### Template placeholders
|
||||
|
||||
|
|
@ -426,11 +424,11 @@ Tags can be added in feeds by adding an entry in `$data['<placeholder>']` array.
|
|||
|
||||
List of placeholders:
|
||||
|
||||
* `feed_plugins_header`: used as a header tag in the feed.
|
||||
- `feed_plugins_header`: used as a header tag in the feed.
|
||||
|
||||
For each links:
|
||||
|
||||
* `feed_plugins`: additional tag for every link entry.
|
||||
- `feed_plugins`: additional tag for every link entry.
|
||||
|
||||
#### save_link
|
||||
|
||||
|
|
@ -442,15 +440,15 @@ Allow to alter the link being saved in the datastore.
|
|||
|
||||
`$data` is an array containing the link being saved:
|
||||
|
||||
* id
|
||||
* title
|
||||
* url
|
||||
* shorturl
|
||||
* description
|
||||
* private
|
||||
* tags
|
||||
* created
|
||||
* updated
|
||||
- id
|
||||
- title
|
||||
- url
|
||||
- shorturl
|
||||
- description
|
||||
- private
|
||||
- tags
|
||||
- created
|
||||
- updated
|
||||
|
||||
|
||||
#### delete_link
|
||||
|
|
@ -463,15 +461,15 @@ Allow to execute any action before the link is actually removed from the datasto
|
|||
|
||||
`$data` is an array containing the link being saved:
|
||||
|
||||
* id
|
||||
* title
|
||||
* url
|
||||
* shorturl
|
||||
* description
|
||||
* private
|
||||
* tags
|
||||
* created
|
||||
* updated
|
||||
- id
|
||||
- title
|
||||
- url
|
||||
- shorturl
|
||||
- description
|
||||
- private
|
||||
- tags
|
||||
- created
|
||||
- updated
|
||||
|
||||
## Guide for template designer
|
||||
|
||||
|
|
@ -485,9 +483,9 @@ Use the default one as an example.
|
|||
|
||||
Aside from classic RainTPL loops, plugins order is handle by JavaScript. You can just include `plugin_admin.js`, only if:
|
||||
|
||||
* you're using a table.
|
||||
* you call orderUp() and orderUp() onclick on arrows.
|
||||
* you add data-line and data-order to your rows.
|
||||
- you're using a table.
|
||||
- you call orderUp() and orderUp() onclick on arrows.
|
||||
- you add data-line and data-order to your rows.
|
||||
|
||||
Otherwise, you can use your own JS as long as this field is send by the form:
|
||||
|
||||
|
|
|
|||
|
|
@ -4,9 +4,9 @@ There is a bunch of plugins shipped with Shaarli, where there is nothing to do t
|
|||
|
||||
If you want to install a third party plugin:
|
||||
|
||||
* Download it.
|
||||
* Put it in the `plugins` directory in Shaarli's installation folder.
|
||||
* Make sure you put it correctly:
|
||||
- Download it.
|
||||
- Put it in the `plugins` directory in Shaarli's installation folder.
|
||||
- Make sure you put it correctly:
|
||||
|
||||
```
|
||||
| index.php
|
||||
|
|
|
|||
|
|
@ -1,6 +1,18 @@
|
|||
## Usage
|
||||
## Usage and Prerequisites
|
||||
|
||||
See the [REST API documentation](http://shaarli.github.io/api-documentation/).
|
||||
See the [REST API documentation](http://shaarli.github.io/api-documentation/)
|
||||
for a list of available endpoints and parameters.
|
||||
|
||||
Please ensure that your server meets the [requirements](Server-requirements)
|
||||
and is properly [configured](Server-configuration):
|
||||
|
||||
- URL rewriting is enabled (see specific Apache and Nginx sections)
|
||||
- the server's timezone is properly defined
|
||||
- the server's clock is synchronized with
|
||||
[NTP](https://en.wikipedia.org/wiki/Network_Time_Protocol)
|
||||
|
||||
The host where the API client is invoked should also be synchronized with NTP,
|
||||
see [token expiration](#payload).
|
||||
|
||||
## Authentication
|
||||
|
||||
|
|
@ -10,10 +22,10 @@ This token has to be included as an HTTP header called `Authentication: Bearer <
|
|||
|
||||
JWT resources :
|
||||
|
||||
* [jwt.io](https://jwt.io) (including a list of client per language).
|
||||
* RFC : https://tools.ietf.org/html/rfc7519
|
||||
* https://float-middle.com/json-web-tokens-jwt-vs-sessions/
|
||||
* HackerNews thread: https://news.ycombinator.com/item?id=11929267
|
||||
- [jwt.io](https://jwt.io) (including a list of client per language).
|
||||
- RFC : https://tools.ietf.org/html/rfc7519
|
||||
- https://float-middle.com/json-web-tokens-jwt-vs-sessions/
|
||||
- HackerNews thread: https://news.ycombinator.com/item?id=11929267
|
||||
|
||||
|
||||
### Shaarli JWT Token
|
||||
|
|
@ -43,9 +55,11 @@ ewogICAgICAgICJ0eXAiOiAiSldUIiwKICAgICAgICAiYWxnIjogIkhTNTEyIgogICAgfQ==
|
|||
|
||||
#### Payload
|
||||
|
||||
**Validity duration**
|
||||
**Token expiration**
|
||||
|
||||
To avoid infinite token validity, JWT tokens must include their creation date in UNIX timestamp format (timezone independant - UTC) under the key `iat` (issued at). This token will be accepted during 9 minutes.
|
||||
To avoid infinite token validity, JWT tokens must include their creation date
|
||||
in UNIX timestamp format (timezone independent - UTC) under the key `iat` (issued at).
|
||||
This token will be valid during **9 minutes**.
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -68,37 +82,67 @@ $signature = hash_hmac('sha512', $content, $secret);
|
|||
```
|
||||
|
||||
|
||||
### Complete example
|
||||
## Clients and examples
|
||||
### Android, Java, Kotlin
|
||||
|
||||
#### PHP
|
||||
- [Android client example with Kotlin](https://gitlab.com/snippets/1665808)
|
||||
by [Braincoke](https://github.com/Braincoke)
|
||||
|
||||
|
||||
### PHP
|
||||
|
||||
This example uses the [PHP cURL](http://php.net/manual/en/book.curl.php) library.
|
||||
|
||||
```php
|
||||
<?php
|
||||
$baseUrl = 'https://shaarli.mydomain.net';
|
||||
$secret = 'thats_my_api_secret';
|
||||
|
||||
function base64url_encode($data) {
|
||||
return rtrim(strtr(base64_encode($data), '+/', '-_'), '=');
|
||||
}
|
||||
|
||||
function generateToken($secret) {
|
||||
$header = base64_encode('{
|
||||
$header = base64url_encode('{
|
||||
"typ": "JWT",
|
||||
"alg": "HS512"
|
||||
}');
|
||||
$payload = base64_encode('{
|
||||
$payload = base64url_encode('{
|
||||
"iat": '. time() .'
|
||||
}');
|
||||
$signature = hash_hmac('sha512', $header .'.'. $payload , $secret);
|
||||
$signature = base64url_encode(hash_hmac('sha512', $header .'.'. $payload , $secret, true));
|
||||
return $header . '.' . $payload . '.' . $signature;
|
||||
}
|
||||
|
||||
$secret = 'mysecret';
|
||||
|
||||
function getInfo($baseUrl, $secret) {
|
||||
$token = generateToken($secret);
|
||||
echo $token;
|
||||
```
|
||||
$endpoint = rtrim($baseUrl, '/') . '/api/v1/info';
|
||||
|
||||
> `ewogICAgICAgICJ0eXAiOiAiSldUIiwKICAgICAgICAiYWxnIjogIkhTNTEyIgogICAgfQ==.ewogICAgICAgICJpYXQiOiAxNDY4NjY3MDQ3CiAgICB9.1d2c54fa947daf594fdbf7591796195652c8bc63bffad7f6a6db2a41c313f495a542cbfb595acade79e83f3810d709b4251d7b940bbc10b531a6e6134af63a68`
|
||||
|
||||
```php
|
||||
$options = [
|
||||
'http' => [
|
||||
'method' => 'GET',
|
||||
'jwt' => $token,
|
||||
],
|
||||
$headers = [
|
||||
'Content-Type: text/plain; charset=UTF-8',
|
||||
'Authorization: Bearer ' . $token,
|
||||
];
|
||||
$context = stream_context_create($options);
|
||||
file_get_contents($apiEndpoint, false, $context);
|
||||
|
||||
$ch = curl_init($endpoint);
|
||||
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
|
||||
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
|
||||
curl_setopt($ch, CURLOPT_AUTOREFERER, 1);
|
||||
curl_setopt($ch, CURLOPT_FRESH_CONNECT, 1);
|
||||
|
||||
$result = curl_exec($ch);
|
||||
curl_close($ch);
|
||||
|
||||
return $result;
|
||||
}
|
||||
|
||||
var_dump(getInfo($baseUrl, $secret));
|
||||
```
|
||||
|
||||
|
||||
### Python
|
||||
|
||||
See the reference API client:
|
||||
|
||||
- [Documentation](http://python-shaarli-client.readthedocs.io/en/latest/) on ReadTheDocs
|
||||
- [python-shaarli-client](https://github.com/shaarli/python-shaarli-client) on Github
|
||||
|
|
|
|||
|
|
@ -3,6 +3,7 @@
|
|||
Feeds are available in ATOM with `?do=atom` and RSS with `do=RSS`.
|
||||
|
||||
Options:
|
||||
|
||||
- You can use `permalinks` in the feed URL to get permalink to Shaares instead of direct link to shaared URL.
|
||||
- E.G. `https://my.shaarli.domain/?do=atom&permalinks`.
|
||||
- You can use `nb` parameter in the feed URL to specify the number of Shaares you want in a feed (default if not specified: `50`). The keyword `all` is available if you want everything.
|
||||
|
|
@ -14,6 +15,7 @@ Options:
|
|||
It is possible to filter RSS/ATOM feeds and Picture Wall on a Shaarli to **only display results of a specific search, or for a specific tag**.
|
||||
|
||||
For example, if you want to subscribe only to links tagged `photography`:
|
||||
|
||||
- Go to the desired Shaarli instance.
|
||||
- Search for the `photography` tag in the _Filter by tag_ box. Links tagged `photography` are displayed.
|
||||
- Click on the `RSS Feed` button.
|
||||
|
|
|
|||
|
|
@ -3,6 +3,7 @@ releases](http://git-scm.com/book/en/v2/Distributed-Git-Maintaining-a-Project#Ta
|
|||
|
||||
## Prerequisites
|
||||
This guide assumes that you have:
|
||||
|
||||
- a GPG key matching your GitHub authentication credentials
|
||||
- i.e., the email address identified by the GPG key is the same as the one in your `~/.gitconfig`
|
||||
- a GitHub fork of Shaarli
|
||||
|
|
@ -43,32 +44,13 @@ TBA
|
|||
```
|
||||
|
||||
|
||||
## Increment the version code, updated docs, create and push a signed tag
|
||||
### Generate documentation
|
||||
```bash
|
||||
$ cd /path/to/shaarli
|
||||
|
||||
# create a new branch
|
||||
$ git fetch upstream
|
||||
$ git checkout upstream/master -b v0.5.0
|
||||
|
||||
# rebuild the HTML documentation from Markdown
|
||||
$ make htmlpages
|
||||
|
||||
# commit the changes
|
||||
$ git add doc
|
||||
$ git commit -s -m "Generate documentation for v0.5.0"
|
||||
|
||||
# push the commit on your GitHub fork
|
||||
$ git push origin v0.5.0
|
||||
```
|
||||
|
||||
## Increment the version code, update docs, create and push a signed tag
|
||||
### Create and merge a Pull Request
|
||||
This one is pretty straightforward ;-)
|
||||
|
||||
### Bump Shaarli version to v0.x branch
|
||||
|
||||
```
|
||||
```bash
|
||||
$ git checkout master
|
||||
$ git fetch upstream
|
||||
$ git pull upstream master
|
||||
|
|
@ -125,6 +107,7 @@ Update `README.md` so version badges display and point to the newly released Sha
|
|||
|
||||
### Create a GitHub release from a Git tag
|
||||
From the previously drafted release:
|
||||
|
||||
- edit the release notes (if needed)
|
||||
- specify the appropriate Git tag
|
||||
- publish the release
|
||||
|
|
@ -132,6 +115,7 @@ From the previously drafted release:
|
|||
|
||||
### Generate and upload all-in-one release archives
|
||||
Users with a shared hosting may have:
|
||||
|
||||
- no SSH access
|
||||
- no possibility to install PHP packages or server extensions
|
||||
- no possibility to run scripts
|
||||
|
|
@ -146,6 +130,7 @@ $ make release_archive
|
|||
```
|
||||
|
||||
This will create the following archives:
|
||||
|
||||
- `shaarli-vX.Y.Z-full.tar`
|
||||
- `shaarli-vX.Y.Z-full.zip`
|
||||
|
||||
|
|
|
|||
|
|
@ -1,27 +1,28 @@
|
|||
## Client browser
|
||||
* Shaarli relies on `HTTP_REFERER` for some functions (like redirects and clicking on tags). If you have disabled or masqueraded `HTTP_REFERER` in your browser, some features of Shaarli may not work
|
||||
- Shaarli relies on `HTTP_REFERER` for some functions (like redirects and clicking on tags). If you have disabled or masqueraded `HTTP_REFERER` in your browser, some features of Shaarli may not work
|
||||
|
||||
## PHP
|
||||
* `magic_quotes` is an horrible option of PHP which is often activated on servers. No serious developer should rely on this horror to secure their code against SQL injections. You should disable it (and Shaarli expects this option to be disabled). Nevertheless, I have added code to cope with `magic_quotes` on, so you should not be bothered even on crappy hosts.
|
||||
- `magic_quotes` is an horrible option of PHP which is often activated on servers. No serious developer should rely on this horror to secure their code against SQL injections. You should disable it (and Shaarli expects this option to be disabled). Nevertheless, I have added code to cope with `magic_quotes` on, so you should not be bothered even on crappy hosts.
|
||||
|
||||
## Server and sessions
|
||||
* Directories are protected using `.htaccess` files
|
||||
* Forms are protected against XSRF (Cross-site requests forgery):
|
||||
* Forms which act on data (save,delete…) contain a token generated by the server.
|
||||
* Any posted form which does not contain a valid token is rejected.
|
||||
* Any token can only be used once.
|
||||
* Tokens are attached to the session and cannot be reused in another session.
|
||||
* Sessions automatically expire after 60 minutes.
|
||||
* Sessions are protected against hijacking: the session ID cannot be used from a different IP address.
|
||||
- Directories are protected using `.htaccess` files
|
||||
- Forms are protected against XSRF (Cross-site requests forgery):
|
||||
- Forms which act on data (save,delete…) contain a token generated by the server.
|
||||
- Any posted form which does not contain a valid token is rejected.
|
||||
- Any token can only be used once.
|
||||
- Tokens are attached to the session and cannot be reused in another session.
|
||||
- Sessions automatically expire after 60 minutes.
|
||||
- Sessions are protected against hijacking: the session ID cannot be used from a different IP address.
|
||||
|
||||
## Shaarli datastore and configuration
|
||||
* The password is salted, hashed and stored in the data subdirectory, in a PHP file, and protected by htaccess. Even if the webserver does not support htaccess, the hash is not readable by URL. Even if the .php file is stolen, the password cannot deduced from the hash. The salt prevents rainbow-tables attacks.
|
||||
* Links are stored as an associative array which is serialized, compressed (with deflate), base64-encoded and saved as a comment in a `.php` file.
|
||||
* Even if the server does not support `.htaccess` files, the data file will still not be readable by URL.
|
||||
* The database looks like this:
|
||||
- The password is salted, hashed and stored in the data subdirectory, in a PHP file, and protected by htaccess. Even if the webserver does not support htaccess, the hash is not readable by URL. Even if the .php file is stolen, the password cannot deduced from the hash. The salt prevents rainbow-tables attacks.
|
||||
- Links are stored as an associative array which is serialized, compressed (with deflate), base64-encoded and saved as a comment in a `.php` file.
|
||||
- Even if the server does not support `.htaccess` files, the data file will still not be readable by URL.
|
||||
- The database looks like this:
|
||||
|
||||
```php
|
||||
<?php /* zP1ZjxxJtiYIvvevEPJ2lDOaLrZv7o...
|
||||
...ka7gaco/Z+TFXM2i7BlfMf8qxpaSSYfKlvqv/x8= */ ?>
|
||||
```
|
||||
|
||||
* Small hashes are used to make a link to an entry in Shaarli. They are unique. In fact, the date of the items (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 `@`.
|
||||
- Small hashes are used to make a link to an entry in Shaarli. They are unique. In fact, the date of the items (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 `@`.
|
||||
|
|
|
|||
|
|
@ -5,23 +5,26 @@
|
|||
|
||||
## Prerequisites
|
||||
### Shaarli
|
||||
* 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
|
||||
- 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
|
||||
|
||||
### HTTPS, TLS and self-signed certificates
|
||||
Related guides:
|
||||
* [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)
|
||||
* Generate a self-signed certificate (will trigger browser warnings) with apache2: `make-ssl-cert generate-default-snakeoil --force-overwrite` will create `/etc/ssl/certs/ssl-cert-snakeoil.pem` and `/etc/ssl/private/ssl-cert-snakeoil.key`
|
||||
|
||||
- [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)
|
||||
- Generate a self-signed certificate (will trigger browser warnings) with apache2:
|
||||
`make-ssl-cert generate-default-snakeoil --force-overwrite` will create `/etc/ssl/certs/ssl-cert-snakeoil.pem` and `/etc/ssl/private/ssl-cert-snakeoil.key`
|
||||
|
||||
### Proxies
|
||||
If Shaarli is served behind a proxy (i.e. there is a proxy server between clients and the web server hosting Shaarli), please refer to the proxy server documentation for proper configuration. In particular, you have to ensure that the following server variables are properly set:
|
||||
- `X-Forwarded-Proto`;
|
||||
- `X-Forwarded-Host`;
|
||||
- `X-Forwarded-For`.
|
||||
|
||||
- `X-Forwarded-Proto`
|
||||
- `X-Forwarded-Host`
|
||||
- `X-Forwarded-For`
|
||||
|
||||
See also [proxy-related](https://github.com/shaarli/Shaarli/issues?utf8=%E2%9C%93&q=label%3Aproxy+) issues.
|
||||
|
||||
|
|
@ -37,8 +40,9 @@ See also [proxy-related](https://github.com/shaarli/Shaarli/issues?utf8=%E2%9C%9
|
|||
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](http://stackoverflow.com/q/176) (StackOverflow)
|
||||
* [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/)
|
||||
|
||||
- [Apache/PHP - error log per VirtualHost](http://stackoverflow.com/q/176) (StackOverflow)
|
||||
- [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/)
|
||||
|
||||
```apache
|
||||
<VirtualHost *:80>
|
||||
|
|
@ -116,34 +120,41 @@ Apache module `mod_rewrite` **must** be enabled to use the REST API. URL rewriti
|
|||
Nginx does not natively interpret PHP scripts; to this effect, we will run a [FastCGI](https://en.wikipedia.org/wiki/FastCGI) service, to which Nginx's FastCGI module will proxy all requests to PHP resources.
|
||||
|
||||
Required packages:
|
||||
|
||||
- [nginx](http://nginx.org)
|
||||
- [php-fpm](http://php-fpm.org) - PHP FastCGI Process Manager
|
||||
|
||||
Official documentation:
|
||||
|
||||
- [Beginner's guide](http://nginx.org/en/docs/beginners_guide.html)
|
||||
- [ngx_http_fastcgi_module](http://nginx.org/en/docs/http/ngx_http_fastcgi_module.html)
|
||||
- [Pitfalls](http://wiki.nginx.org/Pitfalls)
|
||||
|
||||
Community resources:
|
||||
|
||||
- [Server-side TLS (Nginx)](https://wiki.mozilla.org/Security/Server_Side_TLS#Nginx) (Mozilla)
|
||||
- [PHP configuration examples](http://kbeezie.com/nginx-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 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 configuration examples, this user/group pair will be used:
|
||||
|
||||
- `user:group = john:users`,
|
||||
|
||||
which corresponds to the following service configuration:
|
||||
|
|
@ -237,6 +248,7 @@ http {
|
|||
|
||||
### 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~`
|
||||
|
|
@ -342,7 +354,9 @@ http {
|
|||
```
|
||||
|
||||
### 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.
|
||||
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.
|
||||
|
||||
```nginx
|
||||
# /etc/nginx/nginx.conf
|
||||
|
|
|
|||
|
|
@ -10,14 +10,15 @@
|
|||
### Supported versions
|
||||
Version | Status | Shaarli compatibility
|
||||
:---:|:---:|:---:
|
||||
7.1 | Supported (v0.9.x) | :white_check_mark:
|
||||
7.0 | Supported | :white_check_mark:
|
||||
5.6 | Supported | :white_check_mark:
|
||||
5.5 | EOL: 2016-07-10 | :white_check_mark:
|
||||
5.4 | EOL: 2015-09-14 | :white_check_mark: (up to Shaarli 0.8.x)
|
||||
5.3 | EOL: 2014-08-14 | :white_check_mark: (up to Shaarli 0.8.x)
|
||||
7.1 | Supported (v0.9.x) | Yes
|
||||
7.0 | Supported | Yes
|
||||
5.6 | Supported | Yes
|
||||
5.5 | EOL: 2016-07-10 | Yes
|
||||
5.4 | EOL: 2015-09-14 | Yes (up to Shaarli 0.8.x)
|
||||
5.3 | EOL: 2014-08-14 | Yes (up to Shaarli 0.8.x)
|
||||
|
||||
See also:
|
||||
|
||||
- [Travis configuration](https://github.com/shaarli/Shaarli/blob/master/.travis.yml)
|
||||
|
||||
### Dependency management
|
||||
|
|
|
|||
|
|
@ -1,5 +1,6 @@
|
|||
## php.ini
|
||||
PHP settings are defined in:
|
||||
|
||||
- a main configuration file, usually found under `/etc/php5/php.ini`; some distributions provide different configuration environments, e.g.
|
||||
- `/etc/php5/php.ini` - used when running console scripts
|
||||
- `/etc/php5/apache2/php.ini` - used when a client requests PHP resources from Apache
|
||||
|
|
@ -30,6 +31,7 @@ Additional .ini files parsed: /etc/php/conf.d/xdebug.ini
|
|||
|
||||
## fail2ban
|
||||
`fail2ban` is an intrusion prevention framework that reads server (Apache, SSH, etc.) and uses `iptables` profiles to block brute-force attempts:
|
||||
|
||||
- [Official website](http://www.fail2ban.org/wiki/index.php/Main_Page)
|
||||
- [Source code](https://github.com/fail2ban/fail2ban)
|
||||
|
||||
|
|
@ -68,6 +70,7 @@ Disallow: /
|
|||
```
|
||||
|
||||
See:
|
||||
- http://www.robotstxt.org/
|
||||
|
||||
- http://www.robotstxt.org
|
||||
- http://www.robotstxt.org/robotstxt.html
|
||||
- http://www.robotstxt.org/meta.html
|
||||
|
|
|
|||
|
|
@ -42,70 +42,70 @@ See also [Plugin System](Plugin-System.html).
|
|||
|
||||
### Credentials
|
||||
|
||||
> You shouldn't edit those.
|
||||
_These settings should not be edited_
|
||||
|
||||
**login**: Login username.
|
||||
**hash**: Generated password hash.
|
||||
**salt**: Password salt.
|
||||
- **login**: Login username.
|
||||
- **hash**: Generated password hash.
|
||||
- **salt**: Password salt.
|
||||
|
||||
### General
|
||||
|
||||
**title**: Shaarli's instance title.
|
||||
**header_link**: Link to the homepage.
|
||||
**links_per_page**: Number of shaares displayed per page.
|
||||
**timezone**: See [the list of supported timezones](http://php.net/manual/en/timezones.php).
|
||||
**enabled_plugins**: List of enabled plugins.
|
||||
- **title**: Shaarli's instance title.
|
||||
- **header_link**: Link to the homepage.
|
||||
- **links_per_page**: Number of shaares displayed per page.
|
||||
- **timezone**: See [the list of supported timezones](http://php.net/manual/en/timezones.php).
|
||||
- **enabled_plugins**: List of enabled plugins.
|
||||
|
||||
### Security
|
||||
|
||||
**session_protection_disabled**: Disable session cookie hijacking protection (not recommended).
|
||||
- **session_protection_disabled**: Disable session cookie hijacking protection (not recommended).
|
||||
It might be useful if your IP adress often changes.
|
||||
**ban_after**: Failed login attempts before being IP banned.
|
||||
**ban_duration**: IP ban duration in seconds.
|
||||
**open_shaarli**: Anyone can add a new link while logged out if enabled.
|
||||
**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"]`).
|
||||
- **ban_after**: Failed login attempts before being IP banned.
|
||||
- **ban_duration**: IP ban duration in seconds.
|
||||
- **open_shaarli**: Anyone can add a new link while logged out if enabled.
|
||||
- **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"]`).
|
||||
|
||||
### Resources
|
||||
|
||||
**data_dir**: Data directory.
|
||||
**datastore**: Shaarli's links database file path.
|
||||
**history**: Shaarli's operation history file path.
|
||||
**updates**: File path for the ran updates file.
|
||||
**log**: Log file path.
|
||||
**update_check**: Last update check file path.
|
||||
**raintpl_tpl**: Templates directory.
|
||||
**raintpl_tmp**: Template engine cache directory.
|
||||
**thumbnails_cache**: Thumbnails cache directory.
|
||||
**page_cache**: Shaarli's internal cache directory.
|
||||
**ban_file**: Banned IP file path.
|
||||
- **data_dir**: Data directory.
|
||||
- **datastore**: Shaarli's links database file path.
|
||||
- **history**: Shaarli's operation history file path.
|
||||
- **updates**: File path for the ran updates file.
|
||||
- **log**: Log file path.
|
||||
- **update_check**: Last update check file path.
|
||||
- **raintpl_tpl**: Templates directory.
|
||||
- **raintpl_tmp**: Template engine cache directory.
|
||||
- **thumbnails_cache**: Thumbnails cache directory.
|
||||
- **page_cache**: Shaarli's internal cache directory.
|
||||
- **ban_file**: Banned IP file path.
|
||||
|
||||
### Updates
|
||||
|
||||
**check_updates**: Enable or disable update check to the git repository.
|
||||
**check_updates_branch**: Git branch used to check updates (e.g. `stable` or `master`).
|
||||
**check_updates_interval**: Look for new version every N seconds (default: every day).
|
||||
- **check_updates**: Enable or disable update check to the git repository.
|
||||
- **check_updates_branch**: Git branch used to check updates (e.g. `stable` or `master`).
|
||||
- **check_updates_interval**: Look for new version every N seconds (default: every day).
|
||||
|
||||
### Privacy
|
||||
|
||||
**default_private_links**: Check the private checkbox by default for every new link.
|
||||
**hide_public_links**: All links are hidden while logged out.
|
||||
**hide_timestamps**: Timestamps are hidden.
|
||||
- **default_private_links**: Check the private checkbox by default for every new link.
|
||||
- **hide_public_links**: All links are hidden while logged out.
|
||||
- **hide_timestamps**: Timestamps are hidden.
|
||||
|
||||
### Feed
|
||||
|
||||
**rss_permalinks**: Enable this to redirect RSS links to Shaarli's permalinks instead of shaared URL.
|
||||
**show_atom**: Display ATOM feed button.
|
||||
- **rss_permalinks**: Enable this to redirect RSS links to Shaarli's permalinks instead of shaared URL.
|
||||
- **show_atom**: Display ATOM feed button.
|
||||
|
||||
### Thumbnail
|
||||
|
||||
**enable_thumbnails**: Enable or disable thumbnail display.
|
||||
**enable_localcache**: Enable or disable local cache.
|
||||
- **enable_thumbnails**: Enable or disable thumbnail display.
|
||||
- **enable_localcache**: Enable or disable local cache.
|
||||
|
||||
### Redirector
|
||||
|
||||
**url**: Redirector URL, such as `anonym.to`.
|
||||
**encode_url**: Enable this if the redirector needs encoded URL to work properly.
|
||||
- **url**: Redirector URL, such as `anonym.to`.
|
||||
- **encode_url**: Enable this if the redirector needs encoded URL to work properly.
|
||||
|
||||
## Configuration file example
|
||||
|
||||
|
|
@ -211,7 +211,7 @@ It might be useful if your IP adress often changes.
|
|||
|
||||
## Additional configuration
|
||||
|
||||
The playvideos plugin may require that you adapt your server's
|
||||
The `playvideos` plugin may require that you adapt your server's
|
||||
[Content Security Policy](https://github.com/shaarli/Shaarli/blob/master/plugins/playvideos/README.md#troubleshooting)
|
||||
configuration to work properly.[](.html)
|
||||
configuration to work properly.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,5 +1,6 @@
|
|||
## WIP
|
||||
This topic is currently being discussed here:
|
||||
|
||||
- [Fix coding style (static analysis)](https://github.com/shaarli/Shaarli/issues/95) (#95)
|
||||
- [Continuous Integration tools & features](https://github.com/shaarli/Shaarli/issues/130) (#130)
|
||||
|
||||
|
|
@ -7,5 +8,6 @@ This topic is currently being discussed here:
|
|||
Static analysis tools can be installed with Composer, and used through Shaarli's [Makefile](https://github.com/shaarli/Shaarli/blob/master/Makefile).
|
||||
|
||||
For an overview of the available features, see:
|
||||
|
||||
- [Code quality: Makefile to run static code checkers](https://github.com/shaarli/Shaarli/pull/124) (#124)
|
||||
- [Run PHPCS against different coding standards](https://github.com/shaarli/Shaarli/pull/276) (#276)
|
||||
|
|
|
|||
|
|
@ -8,6 +8,7 @@ There are two ways of customizing how Shaarli looks:
|
|||
## Custom CSS
|
||||
|
||||
Shaarli's appearance can be modified by adding CSS rules to:
|
||||
|
||||
- Shaarli < `v0.9.0`: `inc/user.css`
|
||||
- Shaarli >= `v0.9.0`: `data/user.css`
|
||||
|
||||
|
|
@ -19,9 +20,8 @@ See also [Download CSS styles from an OPML list](Download CSS styles from an OPM
|
|||
|
||||
## Themes
|
||||
|
||||
_WARNING - This feature is currently being worked on and will be improved in the next releases. Experimental._
|
||||
|
||||
Installation:
|
||||
|
||||
- find a theme you'd like to install
|
||||
- copy or clone the theme folder under `tpl/<a_sweet_theme>`
|
||||
- enable the theme:
|
||||
|
|
@ -54,6 +54,7 @@ Installation:
|
|||
## Example installation: AlbinoMouse theme
|
||||
|
||||
With the following configuration:
|
||||
|
||||
- Apache 2 / PHP 5.6
|
||||
- user sites are enabled, e.g. `/home/user/public_html/somedir` is served as `http://localhost/~user/somedir`
|
||||
- `http` is the name of the Apache user
|
||||
|
|
@ -77,7 +78,7 @@ Get config written:
|
|||
- fill the install form
|
||||
- log in to Shaarli
|
||||
|
||||
Edit Shaarli's [configuration|Shaarli configuration](configuration|Shaarli configuration):
|
||||
Edit Shaarli's [configuration](Shaarli-configuration):
|
||||
```bash
|
||||
# the file should be owned by Apache, thus not writeable => sudo
|
||||
$ sudo sed -i s=tpl=tpl/albinomouse-template=g shaarli/data/config.php
|
||||
|
|
|
|||
|
|
@ -7,6 +7,7 @@
|
|||
Depending on its configuration and installed plugins, the browser may remove or alter (spoof) HTTP referers, thus preventing Shaarli from properly redirecting between pages.
|
||||
|
||||
See:
|
||||
|
||||
- [HTTP referer](https://en.wikipedia.org/wiki/HTTP_referer) (Wikipedia)
|
||||
- [Improve online privacy by controlling referrer information](http://www.ghacks.net/2015/01/22/improve-online-privacy-by-controlling-referrer-information/)
|
||||
- [Better security, privacy and anonymity in Firefox](http://b.agilob.net/better-security-privacy-and-anonymity-in-firefox/)
|
||||
|
|
@ -16,29 +17,35 @@ See:
|
|||
HTTP settings are available by browsing `about:config`, here are the available settings and their values.
|
||||
|
||||
`network.http.sendRefererHeader` - determines when to send the Referer HTTP header
|
||||
- 0: Never send the referring URL
|
||||
|
||||
- `0`: Never send the referring URL
|
||||
- not recommended, may break some sites
|
||||
- 1: Send only on clicked links
|
||||
- 2 (default): Send for links and images
|
||||
- `1`: Send only on clicked links
|
||||
- `2` (default): Send for links and images
|
||||
|
||||
`network.http.referer.XOriginPolicy` - Cross-domain origin policy
|
||||
- 0 (default): Always send
|
||||
- 1: Send if base domains match
|
||||
- 2: Send if hosts match
|
||||
|
||||
- `0` (default): Always send
|
||||
- `1`: Send if base domains match
|
||||
- `2`: Send if hosts match
|
||||
|
||||
`network.http.referer.spoofSource` - Referer spoofing (~faking)
|
||||
- false (default): real referer
|
||||
- true: spoof referer (use target URI as referer)
|
||||
|
||||
- `false` (default): real referer
|
||||
- `true`: spoof referer (use target URI as referer)
|
||||
- known to break some functionality in Shaarli
|
||||
|
||||
`network.http.referer.trimmingPolicy` - trim the URI not to send a full Referer
|
||||
- 0 (default): send full URI
|
||||
- 1: scheme+host+port+path
|
||||
- 2: scheme+host+port
|
||||
|
||||
- `0`: (default): send full URI
|
||||
- `1`: scheme+host+port+path
|
||||
- `2`: scheme+host+port
|
||||
|
||||
### Firefox, localhost and redirections
|
||||
|
||||
`localhost` is not a proper Fully Qualified Domain Name (FQDN); if Firefox has been set up to spoof referers, or only accept requests from the same base domain/host, Shaarli redirections will not work properly.
|
||||
`localhost` is not a proper Fully Qualified Domain Name (FQDN); if Firefox has
|
||||
been set up to spoof referers, or only accept requests from the same base domain/host,
|
||||
Shaarli redirections will not work properly.
|
||||
|
||||
To solve this, assign a local domain to your host, e.g.
|
||||
```
|
||||
|
|
@ -73,17 +80,20 @@ Search for `failed` in this file to look for unauthorized login attempts.
|
|||
|
||||
### Old PHP versions
|
||||
|
||||
* On **free.fr** : free.fr now support php 5.6.x([link](http://les.pages.perso.chez.free.fr/migrations/php5v6.io))and so support now the tag autocompletion but you have to do the following : At the root of your webspace create a `sessions` directory and a `.htaccess` file containing:
|
||||
On **free.fr**: free.fr now supports php 5.6.x([link](http://les.pages.perso.chez.free.fr/migrations/php5v6.io))
|
||||
and so support now the tag autocompletion but you have to do the following.
|
||||
|
||||
```ini
|
||||
At the root of your webspace create a `sessions` directory and a `.htaccess` file containing:
|
||||
|
||||
```xml
|
||||
<IfDefine Free>
|
||||
php56 1
|
||||
</IfDefine>
|
||||
```
|
||||
|
||||
* If you have an error such as: `Parse error: syntax error, unexpected '=', expecting '(' in /links/index.php on line xxx`, it means that your host is using php4, not php5. Shaarli requires php 5.1. Try changing the file extension to `.php5`
|
||||
* On **1and1** : If you add the link from the page (and not from the bookmarklet), Shaarli will no be able to get the title of the page. You will have to enter it manually. (Because they have disabled the ability to download a file through HTTP).
|
||||
* If you have the error `Warning: file_get_contents() [function.file-get-contents]: URL file-access is disabled in the server configuration in /…/index.php on line xxx`, it means that your host has disabled the ability to fetch a file by HTTP in the php config (Typically in 1and1 hosting). Bad host. Change host. Or comment the following lines:
|
||||
- If you have an error such as: `Parse error: syntax error, unexpected '=', expecting '(' in /links/index.php on line xxx`, it means that your host is using php4, not php5. Shaarli requires php 5.1. Try changing the file extension to `.php5`
|
||||
- On **1and1** : If you add the link from the page (and not from the bookmarklet), Shaarli will no be able to get the title of the page. You will have to enter it manually. (Because they have disabled the ability to download a file through HTTP).
|
||||
- If you have the error `Warning: file_get_contents() [function.file-get-contents]: URL file-access is disabled in the server configuration in /…/index.php on line xxx`, it means that your host has disabled the ability to fetch a file by HTTP in the php config (Typically in 1and1 hosting). Bad host. Change host. Or comment the following lines:
|
||||
|
||||
```php
|
||||
//list($status,$headers,$data) = getHTTP($url,4); // Short timeout to keep the application responsive.
|
||||
|
|
@ -91,8 +101,8 @@ php56 1
|
|||
//if (strpos($status,'200 OK')) $title=html_extract_title($data);
|
||||
```
|
||||
|
||||
* On hosts which forbid outgoing HTTP requests (such as free.fr), some thumbnails will not work.
|
||||
* On **lost-oasis**, RSS doesn't work correctly, because of this message at the begining of the RSS/ATOM feed : `<? // tout ce qui est charge ici (generalement des includes et require) est charge en permanence. ?>`. To fix this, remove this message from `php-include/prepend.php`
|
||||
- On hosts which forbid outgoing HTTP requests (such as free.fr), some thumbnails will not work.
|
||||
- On **lost-oasis**, RSS doesn't work correctly, because of this message at the begining of the RSS/ATOM feed : `<? // tout ce qui est charge ici (generalement des includes et require) est charge en permanence. ?>`. To fix this, remove this message from `php-include/prepend.php`
|
||||
|
||||
### Dates are not properly formatted
|
||||
|
||||
|
|
@ -102,17 +112,16 @@ Shaarli tries to sniff the language of the browser (using HTTP_ACCEPT_LANGUAGE h
|
|||
|
||||
On **CentOS**/RedHat derivatives, you may need to install the `php-mbstring` package.
|
||||
|
||||
|
||||
### My session expires! I can't stay logged in
|
||||
|
||||
This can be caused by several things:
|
||||
|
||||
* Your php installation may not have a proper directory setup for session files. (eg. on Free.fr you need to create a `session` directory on the root of your website.) You may need to create the session directory of set it up.
|
||||
* Most hosts regularly clean the temporary and session directories. Your host may be cleaning those directories too aggressively (eg.OVH hosts), forcing an expire of the session. You may want to set the session directory in your web root. (eg. Create the `sessions` subdirectory and add `ini_set('session.save_path', $_SERVER['DOCUMENT_ROOT'].'/../sessions');`. Make sure this directory is not browsable !)
|
||||
* If your IP address changes during surfing, Shaarli will force expire your session for security reasons (to prevent session cookie hijacking). This can happen when surfing from WiFi or 3G (you may have switched WiFi/3G access point), or in some corporate/university proxies which use load balancing (and may have proxies with several external IP addresses).
|
||||
* Some browser addons may interfer with HTTP headers (ipfuck/ipflood/GreaseMonkey…). Try disabling those.
|
||||
* You may be using OperaTurbo or OperaMini, which use their own proxies which may change from time to time.
|
||||
* If you have another application on the same webserver where Shaarli is installed, these application may forcefully expire php sessions.
|
||||
- Your php installation may not have a proper directory setup for session files. (eg. on Free.fr you need to create a `session` directory on the root of your website.) You may need to create the session directory of set it up.
|
||||
- Most hosts regularly clean the temporary and session directories. Your host may be cleaning those directories too aggressively (eg.OVH hosts), forcing an expire of the session. You may want to set the session directory in your web root. (eg. Create the `sessions` subdirectory and add `ini_set('session.save_path', $_SERVER['DOCUMENT_ROOT'].'/../sessions');`. Make sure this directory is not browsable !)
|
||||
- If your IP address changes during surfing, Shaarli will force expire your session for security reasons (to prevent session cookie hijacking). This can happen when surfing from WiFi or 3G (you may have switched WiFi/3G access point), or in some corporate/university proxies which use load balancing (and may have proxies with several external IP addresses).
|
||||
- Some browser addons may interfer with HTTP headers (ipfuck/ipflood/GreaseMonkey…). Try disabling those.
|
||||
- You may be using OperaTurbo or OperaMini, which use their own proxies which may change from time to time.
|
||||
- If you have another application on the same webserver where Shaarli is installed, these application may forcefully expire php sessions.
|
||||
|
||||
## Sessions do not seem to work correctly on your server
|
||||
|
||||
|
|
|
|||
|
|
@ -3,8 +3,9 @@
|
|||
The framework used is [PHPUnit](https://phpunit.de/); it can be installed with [Composer](https://getcomposer.org/), which is a dependency management tool.
|
||||
|
||||
Regarding Composer, you can either use:
|
||||
* a system-wide version, e.g. installed through your distro's package manager
|
||||
* a local version, downloadable [here](https://getcomposer.org/download/)
|
||||
|
||||
- a system-wide version, e.g. installed through your distro's package manager
|
||||
- a local version, downloadable [here](https://getcomposer.org/download/)
|
||||
|
||||
#### Sample usage
|
||||
|
||||
|
|
@ -118,18 +119,20 @@ Tests: 36, Assertions: 63, Errors: 1, Failures: 2.
|
|||
By default, PHPUnit will run all suitable tests found under the `tests` directory.
|
||||
|
||||
Each test has 3 possible outcomes:
|
||||
* `.` - success
|
||||
* `F` - failure: the test was run but its results are invalid
|
||||
* the code does not behave as expected
|
||||
* dependencies to external elements: globals, session, cache...
|
||||
* `E` - error: something went wrong and the tested code has crashed
|
||||
* typos in the code, or in the test code
|
||||
* dependencies to missing external elements
|
||||
|
||||
- `.` - success
|
||||
- `F` - failure: the test was run but its results are invalid
|
||||
- the code does not behave as expected
|
||||
- dependencies to external elements: globals, session, cache...
|
||||
- `E` - error: something went wrong and the tested code has crashed
|
||||
- typos in the code, or in the test code
|
||||
- dependencies to missing external elements
|
||||
|
||||
If Xdebug has been installed and activated, two coverage reports will be generated:
|
||||
* a summary in the console
|
||||
* a detailed HTML report with metrics for tested code
|
||||
* to open it in a web browser: `firefox coverage/index.html &`
|
||||
|
||||
- a summary in the console
|
||||
- a detailed HTML report with metrics for tested code
|
||||
- to open it in a web browser: `firefox coverage/index.html &`
|
||||
|
||||
### Executing specific tests
|
||||
|
||||
|
|
|
|||
|
|
@ -8,6 +8,7 @@ The current version is present in the `version.php` file.
|
|||
### Backup your data
|
||||
|
||||
Shaarli stores all user data under the `data` directory:
|
||||
|
||||
- `data/config.php` - main configuration file
|
||||
- `data/datastore.php` - bookmarked links
|
||||
- `data/ipbans.php` - banned IP addresses
|
||||
|
|
@ -16,6 +17,7 @@ Shaarli stores all user data under the `data` directory:
|
|||
See [Shaarli configuration](Shaarli configuration) for more information about Shaarli resources.
|
||||
|
||||
It is recommended to backup this repository _before_ starting updating/upgrading Shaarli:
|
||||
|
||||
- users with SSH access: copy or archive the directory to a temporary location
|
||||
- users with FTP access: download a local copy of your Shaarli installation using your favourite client
|
||||
|
||||
|
|
@ -75,6 +77,7 @@ Updating dependencies
|
|||
If you have installed Shaarli from [Sebsauvage's original Git repository](https://github.com/sebsauvage/Shaarli), you can use [Git remotes](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes) to update your working copy.
|
||||
|
||||
The following guide assumes that:
|
||||
|
||||
- you have a basic knowledge of Git [branching](https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell) and [remote repositories](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes)
|
||||
- the default remote is named `origin` and points to Sebsauvage's repository
|
||||
- the current branch is `master`
|
||||
|
|
@ -174,7 +177,7 @@ After migrating, access your fresh Shaarli installation from a web browser; the
|
|||
|
||||
## Troubleshooting
|
||||
|
||||
If the solutions provided here doesn't work, please open an issue specifying which version you're upgrading from and to.
|
||||
If the solutions provided here don't work, please open an issue specifying which version you're upgrading from and to.
|
||||
|
||||
### You must specify an integer as a key
|
||||
|
||||
|
|
@ -185,10 +188,10 @@ Take a look at `data/updates.txt` content.
|
|||
|
||||
Try to delete it and refresh your page while being logged in.
|
||||
|
||||
#### `updates.txt` doesn't exists or doesn't contain `updateMethodDatastoreIds`
|
||||
#### `updates.txt` doesn't exist or doesn't contain `updateMethodDatastoreIds`
|
||||
|
||||
1. Create `data/updates.txt` if it doesn't exist.
|
||||
1. Create `data/updates.txt` if it doesn't exist
|
||||
2. Paste this string in the update file `;updateMethodRenameDashTags;`
|
||||
3. Login to Shaarli.
|
||||
4. Delete the update file.
|
||||
5. Refresh.
|
||||
3. Login to Shaarli
|
||||
4. Delete the update file
|
||||
5. Refresh
|
||||
|
|
|
|||
|
|
@ -19,15 +19,15 @@ php -r 'print(json_encode(unserialize(gzinflate(base64_decode(preg_replace("!.*/
|
|||
|
||||
### Changing the timestamp for a shaare
|
||||
|
||||
* Look for `<input type="hidden" name="lf_linkdate" value="{$link.linkdate}">` in `tpl/editlink.tpl` (line 14)
|
||||
* Replace `type="hidden"` with `type="text"` from this line
|
||||
* A new date/time field becomes available in the edit/new link dialog.
|
||||
* You can set the timestamp manually by entering it in the format `YYYMMDD_HHMMS`.
|
||||
- Look for `<input type="hidden" name="lf_linkdate" value="{$link.linkdate}">` in `tpl/editlink.tpl` (line 14)
|
||||
- Replace `type="hidden"` with `type="text"` from this line
|
||||
- A new date/time field becomes available in the edit/new link dialog.
|
||||
- You can set the timestamp manually by entering it in the format `YYYMMDD_HHMMS`.
|
||||
|
||||
|
||||
### See also
|
||||
|
||||
* [Add a new custom field to shaares (example patch)](https://gist.github.com/nodiscc/8b0194921f059d7b9ad89a581ecd482c)
|
||||
* [Download CSS styles for shaarlis listed in an opml file](https://gist.github.com/nodiscc/dede231c92cab22c3ad2cc24d5035012)
|
||||
* [Copy an existing Shaarli installation over SSH, and serve it locally](https://gist.github.com/nodiscc/ed161c66e5b028b5299b0a3733d01c77)
|
||||
* [Create multiple Shaarli instances, generate an HTML index of them](https://gist.github.com/nodiscc/52e711cda3bc47717c16065231cf6b20)
|
||||
- [Add a new custom field to shaares (example patch)](https://gist.github.com/nodiscc/8b0194921f059d7b9ad89a581ecd482c)
|
||||
- [Download CSS styles for shaarlis listed in an opml file](https://gist.github.com/nodiscc/dede231c92cab22c3ad2cc24d5035012)
|
||||
- [Copy an existing Shaarli installation over SSH, and serve it locally](https://gist.github.com/nodiscc/ed161c66e5b028b5299b0a3733d01c77)
|
||||
- [Create multiple Shaarli instances, generate an HTML index of them](https://gist.github.com/nodiscc/52e711cda3bc47717c16065231cf6b20)
|
||||
|
|
|
|||
|
|
@ -8,10 +8,10 @@ The `master` branch is the development branch. Any new change MUST go through th
|
|||
|
||||
Remarks:
|
||||
|
||||
* This branch shouldn't be used for production as it isn't necessary stable.
|
||||
* 3rd party aren't required to be compatible with the latest changes.
|
||||
* Official plugins, themes and libraries (contained within Shaarli organization repos) must be compatible with the master branch.
|
||||
* The version in this branch is always `dev`.
|
||||
- This branch shouldn't be used for production as it isn't necessary stable.
|
||||
- 3rd party aren't required to be compatible with the latest changes.
|
||||
- Official plugins, themes and libraries (contained within Shaarli organization repos) must be compatible with the master branch.
|
||||
- The version in this branch is always `dev`.
|
||||
|
||||
## `v0.x` branch
|
||||
|
||||
|
|
@ -37,7 +37,7 @@ For example, the current latest release is `v0.8.3`, the stable branch is an ali
|
|||
|
||||
Remarks:
|
||||
|
||||
* Shaarli release pace isn't fast, and the stable branch might be a few months behind the latest release.
|
||||
- Shaarli release pace isn't fast, and the stable branch might be a few months behind the latest release.
|
||||
|
||||
## Releases
|
||||
|
||||
|
|
|
|||
|
|
@ -80,7 +80,8 @@ See the [API documentation](http://shaarli.github.io/api-documentation/).
|
|||
|
||||
### Other usages
|
||||
Though Shaarli is primarily a bookmarking application, it can serve other purposes
|
||||
(see [usage examples](https://github.com/shaarli/Shaarli/wiki#usage-examples)):
|
||||
(see [Features](Features)):
|
||||
|
||||
- micro-blogging
|
||||
- pastebin
|
||||
- online notepad
|
||||
|
|
|
|||
|
|
@ -36,7 +36,6 @@ pages:
|
|||
- Development guidelines: Development-guidelines.md
|
||||
- Continuous integration tools: Continuous-integration-tools.md
|
||||
- GnuPG signature: GnuPG-signature.md
|
||||
- Coding guidelines: Coding-guidelines.md
|
||||
- Directory structure: Directory-structure.md
|
||||
- 3rd party libraries: 3rd-party-libraries.md
|
||||
- Plugin System: Plugin-System.md
|
||||
|
|
|
|||
Loading…
Reference in a new issue