"docs": [
{
"location": "/",
- "text": "Welcome to the \nShaarli\n wiki!\n\n\nHere you can find some info on how to use, configure, tweak and solve problems with your Shaarli.\n\n\nFor general info, read the \nREADME\n.\n\n\nIf you have any questions or ideas, please join the \nchat\n (also reachable via \nIRC\n), post them in our \ngeneral discussion\n (\narchive\n) or read the current \nissues\n. If you've found a bug, please create a \nnew issue\n.\n\n\nIf you would like a feature added to Shaarli, check the issues labeled \nfeature\n, \nenhancement\n, and \nplugin\n.\n\n\nNote: This documentation is available online at https://github.com/shaarli/Shaarli/wiki, and locally in the \ndoc/\n directory of your Shaarli installation.",
+ "text": "Shaarli\n documentation\n\n\nHere you can find some info on how to use, configure, tweak and solve problems with your Shaarli.\n\n\nFor general info, read the \nREADME\n.\n\n\nIf you have any questions or ideas, please join the \nchat\n (also reachable via \nIRC\n), post them in our \ngeneral discussion\n or read the current \nissues\n.\nIf you've found a bug, please create a \nnew issue\n.\n\n\nIf you would like a feature added to Shaarli, check the issues labeled \nfeature\n, \nenhancement\n, and \nplugin\n.\n\n\nNote: This documentation is available online at https://shaarli.readthedocs.io/, and locally in the \ndoc/html/\n directory of your Shaarli installation.\n\n\n\n\n\n\n\n\nDemo\n\n\nYou can use this \npublic demo instance of Shaarli\n.\nIt runs the latest development version of Shaarli and is updated/reset daily.\n\n\nLogin: \ndemo\n; Password: \ndemo\n\n\nFeatures\n\n\nInterface\n\n\n\n\nminimalist design (simple is beautiful)\n\n\nFAST\n\n\nATOM and RSS feeds\n\n\nviews:\n\n\npaginated link list\n\n\ntag cloud\n\n\npicture wall: image and video thumbnails\n\n\ndaily: newspaper-like daily digest\n\n\ndaily RSS feed\n\n\n\n\n\n\npermalinks for easy reference\n\n\nlinks can be public or private\n\n\nextensible through \nplugins\n\n\n\n\nTag, view and search your links!\n\n\n\n\nadd a custom title and description to archived links\n\n\nadd tags to classify and search links\n\n\nfeatures tag autocompletion, renaming, merging and deletion\n\n\n\n\n\n\nfull-text and tag search\n\n\n\n\nEasy setup\n\n\n\n\ndead-simple installation: drop the files, open the page\n\n\nlinks are stored in a file\n\n\ncompact storage\n\n\nno database required\n\n\neasy backup: simply copy the datastore file\n\n\n\n\n\n\nimport and export links as Netscape bookmarks\n\n\n\n\nAccessibility\n\n\n\n\nFirefox bookmarlet to share links in one click\n\n\nsupport for mobile browsers\n\n\nworks with Javascript disabled\n\n\neasy page customization through HTML/CSS/RainTPL\n\n\n\n\nSecurity\n\n\n\n\nbruteforce-proof login form\n\n\nprotected against \nXSRF\n\nand session cookie hijacking\n\n\n\n\nGoodies\n\n\n\n\nthumbnail generation for images and video services:\ndailymotion, flickr, imageshack, imgur, vimeo, xkcd, youtube...\n\n\nlazy-loading with \nbLazy\n\n\n\n\n\n\nPubSubHubbub\n protocol support\n\n\nURL cleanup: automatic removal of \n?utm_source=...\n, \nfb=...\n\n\ndiscreet pop-up notification when a new release is available\n\n\n\n\nREST API\n\n\nEasily extensible by any client using the REST API exposed by Shaarli.\n\n\nSee the \nAPI documentation\n.\n\n\nOther usages\n\n\nThough Shaarli is primarily a bookmarking application, it can serve other purposes\n(see \nusage examples\n):\n- micro-blogging\n- pastebin\n- online notepad\n- snippet archive\n\n\nAbout\n\n\nShaarli community fork\n\n\nThis friendly fork is maintained by the Shaarli community at https://github.com/shaarli/Shaarli\n\n\nThis is a community fork of the original \nShaarli\n project by \nS\u00e9bastien Sauvage\n.\n\n\nThe original project is currently unmaintained, and the developer \nhas informed us\n\nthat he would have no time to work on Shaarli in the near future.\nThe Shaarli community has carried on the work to provide\n\nmany patches\n\nfor \nbug fixes and enhancements\n\nin this repository, and will keep maintaining the project for the foreseeable future, while keeping Shaarli simple and efficient.\n\n\nContributing\n\n\nIf you'd like to help, please:\n- have a look at the open \nissues\n\nand \npull requests\n\n- feel free to report bugs (feedback is much appreciated)\n- suggest new features and improvements to both code and \ndocumentation\n\n- propose solutions to existing problems\n- submit pull requests :-)\n\n\nLicense\n\n\nShaarli is \nFree Software\n. See \nCOPYING\n for a detail of the contributors and licenses for each individual component.",
"title": "Home"
},
+ {
+ "location": "/#shaarli-documentation",
+ "text": "Here you can find some info on how to use, configure, tweak and solve problems with your Shaarli. For general info, read the README . If you have any questions or ideas, please join the chat (also reachable via IRC ), post them in our general discussion or read the current issues .\nIf you've found a bug, please create a new issue . If you would like a feature added to Shaarli, check the issues labeled feature , enhancement , and plugin . Note: This documentation is available online at https://shaarli.readthedocs.io/, and locally in the doc/html/ directory of your Shaarli installation.",
+ "title": "Shaarli documentation"
+ },
+ {
+ "location": "/#demo",
+ "text": "You can use this public demo instance of Shaarli .\nIt runs the latest development version of Shaarli and is updated/reset daily. Login: demo ; Password: demo",
+ "title": "Demo"
+ },
+ {
+ "location": "/#features",
+ "text": "",
+ "title": "Features"
+ },
+ {
+ "location": "/#interface",
+ "text": "minimalist design (simple is beautiful) FAST ATOM and RSS feeds views: paginated link list tag cloud picture wall: image and video thumbnails daily: newspaper-like daily digest daily RSS feed permalinks for easy reference links can be public or private extensible through plugins",
+ "title": "Interface"
+ },
+ {
+ "location": "/#tag-view-and-search-your-links",
+ "text": "add a custom title and description to archived links add tags to classify and search links features tag autocompletion, renaming, merging and deletion full-text and tag search",
+ "title": "Tag, view and search your links!"
+ },
+ {
+ "location": "/#easy-setup",
+ "text": "dead-simple installation: drop the files, open the page links are stored in a file compact storage no database required easy backup: simply copy the datastore file import and export links as Netscape bookmarks",
+ "title": "Easy setup"
+ },
+ {
+ "location": "/#accessibility",
+ "text": "Firefox bookmarlet to share links in one click support for mobile browsers works with Javascript disabled easy page customization through HTML/CSS/RainTPL",
+ "title": "Accessibility"
+ },
+ {
+ "location": "/#security",
+ "text": "bruteforce-proof login form protected against XSRF \nand session cookie hijacking",
+ "title": "Security"
+ },
+ {
+ "location": "/#goodies",
+ "text": "thumbnail generation for images and video services:\ndailymotion, flickr, imageshack, imgur, vimeo, xkcd, youtube... lazy-loading with bLazy PubSubHubbub protocol support URL cleanup: automatic removal of ?utm_source=... , fb=... discreet pop-up notification when a new release is available",
+ "title": "Goodies"
+ },
+ {
+ "location": "/#rest-api",
+ "text": "Easily extensible by any client using the REST API exposed by Shaarli. See the API documentation .",
+ "title": "REST API"
+ },
+ {
+ "location": "/#other-usages",
+ "text": "Though Shaarli is primarily a bookmarking application, it can serve other purposes\n(see usage examples ):\n- micro-blogging\n- pastebin\n- online notepad\n- snippet archive",
+ "title": "Other usages"
+ },
+ {
+ "location": "/#about",
+ "text": "",
+ "title": "About"
+ },
+ {
+ "location": "/#shaarli-community-fork",
+ "text": "This friendly fork is maintained by the Shaarli community at https://github.com/shaarli/Shaarli This is a community fork of the original Shaarli project by S\u00e9bastien Sauvage . The original project is currently unmaintained, and the developer has informed us \nthat he would have no time to work on Shaarli in the near future.\nThe Shaarli community has carried on the work to provide many patches \nfor bug fixes and enhancements \nin this repository, and will keep maintaining the project for the foreseeable future, while keeping Shaarli simple and efficient.",
+ "title": "Shaarli community fork"
+ },
+ {
+ "location": "/#contributing",
+ "text": "If you'd like to help, please:\n- have a look at the open issues \nand pull requests \n- feel free to report bugs (feedback is much appreciated)\n- suggest new features and improvements to both code and documentation \n- propose solutions to existing problems\n- submit pull requests :-)",
+ "title": "Contributing"
+ },
+ {
+ "location": "/#license",
+ "text": "Shaarli is Free Software . See COPYING for a detail of the contributors and licenses for each individual component.",
+ "title": "License"
+ },
{
"location": "/Download-and-Installation/",
"text": "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 \nserver\n is properly \nconfigured\n.\n\n\nSeveral releases are available:\n\n\n\n\nLatest release (recommended)\n\n\nDownload as an archive\n\n\nGet the latest released version from the \nreleases\n page.\n\n\nDownload our \nshaarli-full\n archive\n to include dependencies.\n\n\nThe current latest released version is \nv0.8.4\n\n\nOr in command lines:\n\n\n$ wget https://github.com/shaarli/Shaarli/releases/download/v0.8.4/shaarli-v0.8.4-full.zip\n$ unzip shaarli-v0.8.4-full.zip\n$ mv Shaarli /path/to/shaarli/\n\n\n\n\n\n\n\n\n\n\n!\n\n\nIn most cases, download Shaarli from the \nreleases\n page. Cloning using \ngit\n or downloading Github branches as zip files requires additional steps (see below).\n\n\n\n\n\n\n\n\n\n\nUsing git\n\n\nmkdir -p /path/to/shaarli && cd /path/to/shaarli/\ngit clone -b v0.8 https://github.com/shaarli/Shaarli.git .\ncomposer install --no-dev\n\n\n\n\n\n\nStable version\n\n\nThe stable version has been experienced by Shaarli users, and will receive security updates.\n\n\nDownload as an archive\n\n\nAs a .zip archive:\n\n\n$ wget https://github.com/shaarli/Shaarli/archive/stable.zip\n$ unzip stable.zip\n$ mv Shaarli-stable /path/to/shaarli/\n\n\n\n\nAs a .tar.gz archive :\n\n\n$ wget https://github.com/shaarli/Shaarli/archive/stable.tar.gz\n$ tar xvf stable.tar.gz\n$ mv Shaarli-stable /path/to/shaarli/\n\n\n\n\nClone with Git\n\n\nComposer\n is required to build a functional Shaarli installation when pulling from git.\n\n\n$ git clone https://github.com/shaarli/Shaarli.git -b stable /path/to/shaarli/\n# install/update third-party dependencies\n$ cd /path/to/shaarli/\n$ composer install --no-dev\n\n\n\n\n\n\nDevelopment version (mainline)\n\n\nUse at your own risk!\n\n\nTo get the latest changes from the \nmaster\n branch:\n\n\n# clone the repository \n$ git clone https://github.com/shaarli/Shaarli.git -b master /path/to/shaarli/\n# install/update third-party dependencies\n$ cd /path/to/shaarli\n$ composer install --no-dev\n\n\n\n\n\n\nFinish Installation\n\n\nOnce Shaarli is downloaded and files have been placed at the correct location, open it this location your favorite browser.\n\n\n\n\nSetup your Shaarli installation, and it's ready to use!\n\n\n\n\nUpdating Shaarli\n\n\nSee \nUpgrade and Migration",
},
{
"location": "/Shaarli-configuration/",
- "text": "Foreword\n\n\nDo not edit configuration options in index.php! Your changes would be lost.\n \n\n\nOnce your Shaarli instance is installed, the file \ndata/config.json.php\n is generated:\n\n it contains all settings in JSON format, and can be edited to customize values\n\n it defines which \nplugins\n are enabled\n\n\n its values override those defined in \nindex.php\n\n\n it is wrap in a PHP comment to prevent anyone accessing it, regardless of server configuration\n\n\nFile and directory permissions\n\n\nThe server process running Shaarli must have:\n- \nread\n access to the following resources:\n - PHP scripts: \nindex.php\n, \napplication/*.php\n, \nplugins/*.php\n\n - 3rd party PHP and Javascript libraries: \ninc/*.php\n, \ninc/*.js\n\n - static assets:\n - CSS stylesheets: \ninc/*.css\n\n - \nimages/*\n\n - RainTPL templates: \ntpl/*.html\n\n- \nread\n, \nwrite\n and \nexecution\n access to the following directories:\n - \ncache\n - thumbnail cache\n - \ndata\n - link data store, configuration options\n - \npagecache\n - Atom/RSS feed cache\n - \ntmp\n - RainTPL page cache\n\n\nOn a Linux distribution:\n- the web server user will likely be \nwww\n or \nhttp\n (for Apache2)\n- it will be a member of a group of the same name: \nwww:www\n, \nhttp:http\n\n- to give it access to Shaarli, either:\n - unzip Shaarli in the default web server location (usually \n/var/www/\n) and set the web server user as the owner\n - put users in the same group as the web server, and set the appropriate access rights\n- if you have a domain / subdomain to serve Shaarli, \nconfigure the server\n accordingly\n\n\nConfiguration\n\n\nIn \ndata/config.json.php\n.\n\n\nSee also \nPlugin System\n.\n\n\nCredentials\n\n\n\n\nYou shouldn't edit those.\n\n\n\n\nlogin\n: Login username.\n\n\nhash\n: Generated password hash.\n\n\nsalt\n: Password salt.\n\n\nGeneral\n\n\ntitle\n: Shaarli's instance title.\n\n\nheader_link\n: Link to the homepage.\n\n\nlinks_per_page\n: Number of shaares displayed per page.\n\n\ntimezone\n: See \nthe list of supported timezones\n.\n\n\nenabled_plugins\n: List of enabled plugins.\n\n\nSecurity\n\n\nsession_protection_disabled\n: Disable session cookie hijacking protection (not recommended). \nIt might be useful if your IP adress often changes.\n\n\nban_after\n: Failed login attempts before being IP banned.\n\n\nban_duration\n: IP ban duration in seconds.\n\n\nopen_shaarli\n: Anyone can add a new link while logged out if enabled.\n\n\ntrusted_proxies\n: List of trusted IP which won't be banned after failed login attemps. Useful if Shaarli is behind a reverse proxy.\n\n\nallowed_protocols\n: List of allowed protocols in shaare URLs or markdown-rendered descriptions. Useful if you want to store \njavascript:\n links (bookmarklets) in Shaarli (default: \n[\"ftp\", \"ftps\", \"magnet\"]\n).\n\n\nResources\n\n\ndata_dir\n: Data directory.\n\n\ndatastore\n: Shaarli's links database file path.\n\n\nhistory\n: Shaarli's operation history file path.\n\nupdates\n: File path for the ran updates file.\n\n\nlog\n: Log file path.\n\n\nupdate_check\n: Last update check file path.\n\n\nraintpl_tpl\n: Templates directory.\n\n\nraintpl_tmp\n: Template engine cache directory.\n\n\nthumbnails_cache\n: Thumbnails cache directory.\n\n\npage_cache\n: Shaarli's internal cache directory.\n\n\nban_file\n: Banned IP file path.\n\n\nUpdates\n\n\ncheck_updates\n: Enable or disable update check to the git repository.\n\n\ncheck_updates_branch\n: Git branch used to check updates (e.g. \nstable\n or \nmaster\n).\n\n\ncheck_updates_interval\n: Look for new version every N seconds (default: every day).\n\n\nPrivacy\n\n\ndefault_private_links\n: Check the private checkbox by default for every new link.\n\n\nhide_public_links\n: All links are hidden while logged out.\n\n\nhide_timestamps\n: Timestamps are hidden.\n\n\nFeed\n\n\nrss_permalinks\n: Enable this to redirect RSS links to Shaarli's permalinks instead of shaared URL.\n\n\nshow_atom\n: Display ATOM feed button.\n\n\nThumbnail\n\n\nenable_thumbnails\n: Enable or disable thumbnail display.\n\n\nenable_localcache\n: Enable or disable local cache.\n\n\nRedirector\n\n\nurl\n: Redirector URL, such as \nanonym.to\n.\n\n\nencode_url\n: Enable this if the redirector needs encoded URL to work properly.\n\n\nConfiguration file example\n\n\n<?php /*\n{\n \"credentials\": {\n \"login\": \"<login>\",\n \"hash\": \"<password hash>\",\n \"salt\": \"<password salt>\"\n },\n \"security\": {\n \"ban_after\": 4,\n \"session_protection_disabled\": false,\n \"ban_duration\": 1800,\n \"trusted_proxies\": [\n \"1.2.3.4\",\n \"5.6.7.8\"\n ],\n \"allowed_protocols\": [\n \"ftp\",\n \"ftps\",\n \"magnet\"\n ]\n },\n \"resources\": {\n \"data_dir\": \"data\",\n \"config\": \"data\\/config.php\",\n \"datastore\": \"data\\/datastore.php\",\n \"ban_file\": \"data\\/ipbans.php\",\n \"updates\": \"data\\/updates.txt\",\n \"log\": \"data\\/log.txt\",\n \"update_check\": \"data\\/lastupdatecheck.txt\",\n \"raintpl_tmp\": \"tmp\\/\",\n \"raintpl_tpl\": \"tpl\\/\",\n \"thumbnails_cache\": \"cache\",\n \"page_cache\": \"pagecache\"\n },\n \"general\": {\n \"check_updates\": true,\n \"rss_permalinks\": true,\n \"links_per_page\": 20,\n \"default_private_links\": true,\n \"enable_thumbnails\": true,\n \"enable_localcache\": true,\n \"check_updates_branch\": \"stable\",\n \"check_updates_interval\": 86400,\n \"enabled_plugins\": [\n \"markdown\",\n \"wallabag\",\n \"archiveorg\"\n ],\n \"timezone\": \"Europe\\/Paris\",\n \"title\": \"My Shaarli\",\n \"header_link\": \"?\"\n },\n \"extras\": {\n \"show_atom\": false,\n \"hide_public_links\": false,\n \"hide_timestamps\": false,\n \"open_shaarli\": false,\n \"redirector\": \"http://anonym.to/?\",\n \"redirector_encode_url\": false\n },\n \"general\": {\n \"header_link\": \"?\",\n \"links_per_page\": 20,\n \"enabled_plugins\": [\n \"markdown\",\n \"wallabag\"\n ],\n \"timezone\": \"Europe\\/Paris\",\n \"title\": \"My Shaarli\"\n },\n \"updates\": {\n \"check_updates\": true,\n \"check_updates_branch\": \"stable\",\n \"check_updates_interval\": 86400\n },\n \"feed\": {\n \"rss_permalinks\": true,\n \"show_atom\": false\n },\n \"privacy\": {\n \"default_private_links\": true,\n \"hide_public_links\": false,\n \"hide_timestamps\": false\n },\n \"thumbnail\": {\n \"enable_thumbnails\": true,\n \"enable_localcache\": true\n },\n \"redirector\": {\n \"url\": \"http://anonym.to/?\",\n \"encode_url\": false\n },\n \"plugins\": {\n \"WALLABAG_URL\": \"http://demo.wallabag.org\",\n \"WALLABAG_VERSION\": \"1\"\n }\n} ?>\n\n\n\n\nAdditional configuration\n\n\nThe playvideos plugin may require that you adapt your server's \n\nContent Security Policy\n \nconfiguration to work properly.",
+ "text": "Foreword\n\n\nDo not edit configuration options in index.php! Your changes would be lost.\n \n\n\nOnce your Shaarli instance is installed, the file \ndata/config.json.php\n is generated:\n\n it contains all settings in JSON format, and can be edited to customize values\n\n it defines which \nplugins\n are enabled\n\n\n its values override those defined in \nindex.php\n\n\n it is wrap in a PHP comment to prevent anyone accessing it, regardless of server configuration\n\n\nFile and directory permissions\n\n\nThe server process running Shaarli must have:\n\n\n\n\nread\n access to the following resources:\n\n\nPHP scripts: \nindex.php\n, \napplication/*.php\n, \nplugins/*.php\n\n\n3rd party PHP and Javascript libraries: \ninc/*.php\n, \ninc/*.js\n\n\nstatic assets:\n\n\nCSS stylesheets: \ninc/*.css\n\n\nimages/*\n\n\n\n\n\n\nRainTPL templates: \ntpl/*.html\n\n\n\n\n\n\nread\n, \nwrite\n and \nexecution\n access to the following directories:\n\n\ncache\n - thumbnail cache\n\n\ndata\n - link data store, configuration options\n\n\npagecache\n - Atom/RSS feed cache\n\n\ntmp\n - RainTPL page cache\n\n\n\n\n\n\n\n\nOn a Linux distribution:\n\n\n\n\nthe web server user will likely be \nwww\n or \nhttp\n (for Apache2)\n\n\nit will be a member of a group of the same name: \nwww:www\n, \nhttp:http\n\n\nto give it access to Shaarli, either:\n\n\nunzip Shaarli in the default web server location (usually \n/var/www/\n) and set the web server user as the owner\n\n\nput users in the same group as the web server, and set the appropriate access rights\n\n\n\n\n\n\nif you have a domain / subdomain to serve Shaarli, \nconfigure the server\n accordingly\n\n\n\n\nConfiguration\n\n\nIn \ndata/config.json.php\n.\n\n\nSee also \nPlugin System\n.\n\n\nCredentials\n\n\n\n\nYou shouldn't edit those.\n\n\n\n\nlogin\n: Login username.\n\n\nhash\n: Generated password hash.\n\n\nsalt\n: Password salt.\n\n\nGeneral\n\n\ntitle\n: Shaarli's instance title.\n\n\nheader_link\n: Link to the homepage.\n\n\nlinks_per_page\n: Number of shaares displayed per page.\n\n\ntimezone\n: See \nthe list of supported timezones\n.\n\n\nenabled_plugins\n: List of enabled plugins.\n\n\nSecurity\n\n\nsession_protection_disabled\n: Disable session cookie hijacking protection (not recommended). \nIt might be useful if your IP adress often changes.\n\n\nban_after\n: Failed login attempts before being IP banned.\n\n\nban_duration\n: IP ban duration in seconds.\n\n\nopen_shaarli\n: Anyone can add a new link while logged out if enabled.\n\n\ntrusted_proxies\n: List of trusted IP which won't be banned after failed login attemps. Useful if Shaarli is behind a reverse proxy.\n\n\nallowed_protocols\n: List of allowed protocols in shaare URLs or markdown-rendered descriptions. Useful if you want to store \njavascript:\n links (bookmarklets) in Shaarli (default: \n[\"ftp\", \"ftps\", \"magnet\"]\n).\n\n\nResources\n\n\ndata_dir\n: Data directory.\n\n\ndatastore\n: Shaarli's links database file path.\n\n\nhistory\n: Shaarli's operation history file path.\n\nupdates\n: File path for the ran updates file.\n\n\nlog\n: Log file path.\n\n\nupdate_check\n: Last update check file path.\n\n\nraintpl_tpl\n: Templates directory.\n\n\nraintpl_tmp\n: Template engine cache directory.\n\n\nthumbnails_cache\n: Thumbnails cache directory.\n\n\npage_cache\n: Shaarli's internal cache directory.\n\n\nban_file\n: Banned IP file path.\n\n\nUpdates\n\n\ncheck_updates\n: Enable or disable update check to the git repository.\n\n\ncheck_updates_branch\n: Git branch used to check updates (e.g. \nstable\n or \nmaster\n).\n\n\ncheck_updates_interval\n: Look for new version every N seconds (default: every day).\n\n\nPrivacy\n\n\ndefault_private_links\n: Check the private checkbox by default for every new link.\n\n\nhide_public_links\n: All links are hidden while logged out.\n\n\nhide_timestamps\n: Timestamps are hidden.\n\n\nFeed\n\n\nrss_permalinks\n: Enable this to redirect RSS links to Shaarli's permalinks instead of shaared URL.\n\n\nshow_atom\n: Display ATOM feed button.\n\n\nThumbnail\n\n\nenable_thumbnails\n: Enable or disable thumbnail display.\n\n\nenable_localcache\n: Enable or disable local cache.\n\n\nRedirector\n\n\nurl\n: Redirector URL, such as \nanonym.to\n.\n\n\nencode_url\n: Enable this if the redirector needs encoded URL to work properly.\n\n\nConfiguration file example\n\n\n<?php /*\n{\n \"credentials\": {\n \"login\": \"<login>\",\n \"hash\": \"<password hash>\",\n \"salt\": \"<password salt>\"\n },\n \"security\": {\n \"ban_after\": 4,\n \"session_protection_disabled\": false,\n \"ban_duration\": 1800,\n \"trusted_proxies\": [\n \"1.2.3.4\",\n \"5.6.7.8\"\n ],\n \"allowed_protocols\": [\n \"ftp\",\n \"ftps\",\n \"magnet\"\n ]\n },\n \"resources\": {\n \"data_dir\": \"data\",\n \"config\": \"data\\/config.php\",\n \"datastore\": \"data\\/datastore.php\",\n \"ban_file\": \"data\\/ipbans.php\",\n \"updates\": \"data\\/updates.txt\",\n \"log\": \"data\\/log.txt\",\n \"update_check\": \"data\\/lastupdatecheck.txt\",\n \"raintpl_tmp\": \"tmp\\/\",\n \"raintpl_tpl\": \"tpl\\/\",\n \"thumbnails_cache\": \"cache\",\n \"page_cache\": \"pagecache\"\n },\n \"general\": {\n \"check_updates\": true,\n \"rss_permalinks\": true,\n \"links_per_page\": 20,\n \"default_private_links\": true,\n \"enable_thumbnails\": true,\n \"enable_localcache\": true,\n \"check_updates_branch\": \"stable\",\n \"check_updates_interval\": 86400,\n \"enabled_plugins\": [\n \"markdown\",\n \"wallabag\",\n \"archiveorg\"\n ],\n \"timezone\": \"Europe\\/Paris\",\n \"title\": \"My Shaarli\",\n \"header_link\": \"?\"\n },\n \"extras\": {\n \"show_atom\": false,\n \"hide_public_links\": false,\n \"hide_timestamps\": false,\n \"open_shaarli\": false,\n \"redirector\": \"http://anonym.to/?\",\n \"redirector_encode_url\": false\n },\n \"general\": {\n \"header_link\": \"?\",\n \"links_per_page\": 20,\n \"enabled_plugins\": [\n \"markdown\",\n \"wallabag\"\n ],\n \"timezone\": \"Europe\\/Paris\",\n \"title\": \"My Shaarli\"\n },\n \"updates\": {\n \"check_updates\": true,\n \"check_updates_branch\": \"stable\",\n \"check_updates_interval\": 86400\n },\n \"feed\": {\n \"rss_permalinks\": true,\n \"show_atom\": false\n },\n \"privacy\": {\n \"default_private_links\": true,\n \"hide_public_links\": false,\n \"hide_timestamps\": false\n },\n \"thumbnail\": {\n \"enable_thumbnails\": true,\n \"enable_localcache\": true\n },\n \"redirector\": {\n \"url\": \"http://anonym.to/?\",\n \"encode_url\": false\n },\n \"plugins\": {\n \"WALLABAG_URL\": \"http://demo.wallabag.org\",\n \"WALLABAG_VERSION\": \"1\"\n }\n} ?>\n\n\n\n\nAdditional configuration\n\n\nThe playvideos plugin may require that you adapt your server's \n\nContent Security Policy\n \nconfiguration to work properly.",
"title": "Shaarli configuration"
},
{
},
{
"location": "/Shaarli-configuration/#file-and-directory-permissions",
- "text": "The server process running Shaarli must have:\n- read access to the following resources:\n - PHP scripts: index.php , application/*.php , plugins/*.php \n - 3rd party PHP and Javascript libraries: inc/*.php , inc/*.js \n - static assets:\n - CSS stylesheets: inc/*.css \n - images/* \n - RainTPL templates: tpl/*.html \n- read , write and execution access to the following directories:\n - cache - thumbnail cache\n - data - link data store, configuration options\n - pagecache - Atom/RSS feed cache\n - tmp - RainTPL page cache On a Linux distribution:\n- the web server user will likely be www or http (for Apache2)\n- it will be a member of a group of the same name: www:www , http:http \n- to give it access to Shaarli, either:\n - unzip Shaarli in the default web server location (usually /var/www/ ) and set the web server user as the owner\n - put users in the same group as the web server, and set the appropriate access rights\n- if you have a domain / subdomain to serve Shaarli, configure the server accordingly",
+ "text": "The server process running Shaarli must have: read access to the following resources: PHP scripts: index.php , application/*.php , plugins/*.php 3rd party PHP and Javascript libraries: inc/*.php , inc/*.js static assets: CSS stylesheets: inc/*.css images/* RainTPL templates: tpl/*.html read , write and execution access to the following directories: cache - thumbnail cache data - link data store, configuration options pagecache - Atom/RSS feed cache tmp - RainTPL page cache On a Linux distribution: the web server user will likely be www or http (for Apache2) it will be a member of a group of the same name: www:www , http:http to give it access to Shaarli, either: unzip Shaarli in the default web server location (usually /var/www/ ) and set the web server user as the owner put users in the same group as the web server, and set the appropriate access rights if you have a domain / subdomain to serve Shaarli, configure the server accordingly",
"title": "File and directory permissions"
},
{
"title": "Third party plugins"
},
{
- "location": "/Docker-101/",
+ "location": "/docker/docker-101/",
"text": "Basics\n\n\nInstall \nDocker\n, by following the instructions relevant\nto your OS / distribution, and start the service.\n\n\nSearch an image on \nDockerHub\n\n\n$ docker search debian\n\nNAME DESCRIPTION STARS OFFICIAL AUTOMATED\nubuntu Ubuntu is a Debian-based Linux operating s... 2065 [OK]\ndebian Debian is a Linux distribution that's comp... 603 [OK]\ngoogle/debian 47 [OK]\n\n\n\n\nShow available tags for a repository\n\n\n$ curl https://index.docker.io/v1/repositories/debian/tags | python -m json.tool\n\n% Total % Received % Xferd Average Speed Time Time Time Current\nDload Upload Total Spent Left Speed\n100 1283 0 1283 0 0 433 0 --:--:-- 0:00:02 --:--:-- 433\n\n\n\n\nSample output:\n\n\n[\n {\n \"layer\": \"85a02782\",\n \"name\": \"stretch\"\n },\n {\n \"layer\": \"59abecbc\",\n \"name\": \"testing\"\n },\n {\n \"layer\": \"bf0fd686\",\n \"name\": \"unstable\"\n },\n {\n \"layer\": \"60c52dbe\",\n \"name\": \"wheezy\"\n },\n {\n \"layer\": \"c5b806fe\",\n \"name\": \"wheezy-backports\"\n }\n]\n\n\n\n\n\nPull an image from DockerHub\n\n\n$ docker pull repository[:tag]\n\n$ docker pull debian:wheezy\nwheezy: Pulling from debian\n4c8cbfd2973e: Pull complete\n60c52dbe9d91: Pull complete\nDigest: sha256:c584131da2ac1948aa3e66468a4424b6aea2f33acba7cec0b631bdb56254c4fe\nStatus: Downloaded newer image for debian:wheezy",
"title": "Docker 101"
},
{
- "location": "/Docker-101/#basics",
+ "location": "/docker/docker-101/#basics",
"text": "Install Docker , by following the instructions relevant\nto your OS / distribution, and start the service.",
"title": "Basics"
},
{
- "location": "/Docker-101/#search-an-image-on-dockerhub",
+ "location": "/docker/docker-101/#search-an-image-on-dockerhub",
"text": "$ docker search debian\n\nNAME DESCRIPTION STARS OFFICIAL AUTOMATED\nubuntu Ubuntu is a Debian-based Linux operating s... 2065 [OK]\ndebian Debian is a Linux distribution that's comp... 603 [OK]\ngoogle/debian 47 [OK]",
"title": "Search an image on DockerHub"
},
{
- "location": "/Docker-101/#show-available-tags-for-a-repository",
+ "location": "/docker/docker-101/#show-available-tags-for-a-repository",
"text": "$ curl https://index.docker.io/v1/repositories/debian/tags | python -m json.tool\n\n% Total % Received % Xferd Average Speed Time Time Time Current\nDload Upload Total Spent Left Speed\n100 1283 0 1283 0 0 433 0 --:--:-- 0:00:02 --:--:-- 433 Sample output: [\n {\n \"layer\": \"85a02782\",\n \"name\": \"stretch\"\n },\n {\n \"layer\": \"59abecbc\",\n \"name\": \"testing\"\n },\n {\n \"layer\": \"bf0fd686\",\n \"name\": \"unstable\"\n },\n {\n \"layer\": \"60c52dbe\",\n \"name\": \"wheezy\"\n },\n {\n \"layer\": \"c5b806fe\",\n \"name\": \"wheezy-backports\"\n }\n]",
"title": "Show available tags for a repository"
},
{
- "location": "/Docker-101/#pull-an-image-from-dockerhub",
+ "location": "/docker/docker-101/#pull-an-image-from-dockerhub",
"text": "$ docker pull repository[:tag]\n\n$ docker pull debian:wheezy\nwheezy: Pulling from debian\n4c8cbfd2973e: Pull complete\n60c52dbe9d91: Pull complete\nDigest: sha256:c584131da2ac1948aa3e66468a4424b6aea2f33acba7cec0b631bdb56254c4fe\nStatus: Downloaded newer image for debian:wheezy",
"title": "Pull an image from DockerHub"
},
{
- "location": "/Shaarli-images/",
- "text": "Get and run a Shaarli image\n\n\nDockerHub repository\n\n\nThe images can be found in the \nshaarli/shaarli\n\nrepository.\n\n\nAvailable image tags\n\n\n\n\nlatest\n: master branch (tarball release)\n\n\nstable\n: stable branch (tarball release)\n\n\ndev\n: master branch (Git clone)\n\n\n\n\nAll images rely on:\n- \nDebian 8 Jessie\n\n- \nPHP5-FPM\n\n- \nNginx\n\n\nDownload from DockerHub\n\n\n$ docker pull shaarli/shaarli\nlatest: Pulling from shaarli/shaarli\n32716d9fcddb: Pull complete\n84899d045435: Pull complete\n4b6ad7444763: Pull complete\ne0345ef7a3e0: Pull complete\n5c1dd344094f: Pull complete\n6422305a200b: Pull complete\n7d63f861dbef: Pull complete\n3eb97210645c: Pull complete\n869319d746ff: Already exists\n869319d746ff: Pulling fs layer\n902b87aaaec9: Already exists\nDigest: sha256:f836b4627b958b3f83f59c332f22f02fcd495ace3056f2be2c4912bd8704cc98\nStatus: Downloaded newer image for shaarli/shaarli:latest\n\n\n\n\nCreate and start a new container from the image\n\n\n# map the host's :8000 port to the container's :80 port\n$ docker create -p 8000:80 shaarli/shaarli\nd40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101\n\n# launch the container in the background\n$ docker start d40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101\nd40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101\n\n# list active containers\n$ docker ps\nCONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES\nd40b7af693d6 shaarli/shaarli /usr/bin/supervisor 15 seconds ago Up 4 seconds 0.0.0.0:8000->80/tcp backstabbing_galileo\n\n\n\n\nStop and destroy a container\n\n\n$ docker stop backstabbing_galileo # those docker guys are really rude to physicists!\nbackstabbing_galileo\n\n# check the container is stopped\n$ docker ps\nCONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES\n\n# list ALL containers\n$ docker ps -a\nCONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES\nd40b7af693d6 shaarli/shaarli /usr/bin/supervisor 5 minutes ago Exited (0) 48 seconds ago backstabbing_galileo\n\n# destroy the container\n$ docker rm backstabbing_galileo # let's put an end to these barbarian practices\nbackstabbing_galileo\n\n$ docker ps -a\nCONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES",
+ "location": "/docker/shaarli-images/",
+ "text": "Get and run a Shaarli image\n\n\nDockerHub repository\n\n\nThe images can be found in the \nshaarli/shaarli\n\nrepository.\n\n\nAvailable image tags\n\n\n\n\nlatest\n: master branch (tarball release)\n\n\nstable\n: stable branch (tarball release)\n\n\n\n\nAll images rely on:\n- \nDebian 8 Jessie\n\n- \nPHP5-FPM\n\n- \nNginx\n\n\nDownload from DockerHub\n\n\n$ docker pull shaarli/shaarli\nlatest: Pulling from shaarli/shaarli\n32716d9fcddb: Pull complete\n84899d045435: Pull complete\n4b6ad7444763: Pull complete\ne0345ef7a3e0: Pull complete\n5c1dd344094f: Pull complete\n6422305a200b: Pull complete\n7d63f861dbef: Pull complete\n3eb97210645c: Pull complete\n869319d746ff: Already exists\n869319d746ff: Pulling fs layer\n902b87aaaec9: Already exists\nDigest: sha256:f836b4627b958b3f83f59c332f22f02fcd495ace3056f2be2c4912bd8704cc98\nStatus: Downloaded newer image for shaarli/shaarli:latest\n\n\n\n\nCreate and start a new container from the image\n\n\n# map the host's :8000 port to the container's :80 port\n$ docker create -p 8000:80 shaarli/shaarli\nd40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101\n\n# launch the container in the background\n$ docker start d40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101\nd40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101\n\n# list active containers\n$ docker ps\nCONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES\nd40b7af693d6 shaarli/shaarli /usr/bin/supervisor 15 seconds ago Up 4 seconds 0.0.0.0:8000->80/tcp backstabbing_galileo\n\n\n\n\nStop and destroy a container\n\n\n$ docker stop backstabbing_galileo # those docker guys are really rude to physicists!\nbackstabbing_galileo\n\n# check the container is stopped\n$ docker ps\nCONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES\n\n# list ALL containers\n$ docker ps -a\nCONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES\nd40b7af693d6 shaarli/shaarli /usr/bin/supervisor 5 minutes ago Exited (0) 48 seconds ago backstabbing_galileo\n\n# destroy the container\n$ docker rm backstabbing_galileo # let's put an end to these barbarian practices\nbackstabbing_galileo\n\n$ docker ps -a\nCONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES",
"title": "Shaarli images"
},
{
- "location": "/Shaarli-images/#get-and-run-a-shaarli-image",
+ "location": "/docker/shaarli-images/#get-and-run-a-shaarli-image",
"text": "",
"title": "Get and run a Shaarli image"
},
{
- "location": "/Shaarli-images/#dockerhub-repository",
+ "location": "/docker/shaarli-images/#dockerhub-repository",
"text": "The images can be found in the shaarli/shaarli \nrepository.",
"title": "DockerHub repository"
},
{
- "location": "/Shaarli-images/#available-image-tags",
- "text": "latest : master branch (tarball release) stable : stable branch (tarball release) dev : master branch (Git clone) All images rely on:\n- Debian 8 Jessie \n- PHP5-FPM \n- Nginx",
+ "location": "/docker/shaarli-images/#available-image-tags",
+ "text": "latest : master branch (tarball release) stable : stable branch (tarball release) All images rely on:\n- Debian 8 Jessie \n- PHP5-FPM \n- Nginx",
"title": "Available image tags"
},
{
- "location": "/Shaarli-images/#download-from-dockerhub",
+ "location": "/docker/shaarli-images/#download-from-dockerhub",
"text": "$ docker pull shaarli/shaarli\nlatest: Pulling from shaarli/shaarli\n32716d9fcddb: Pull complete\n84899d045435: Pull complete\n4b6ad7444763: Pull complete\ne0345ef7a3e0: Pull complete\n5c1dd344094f: Pull complete\n6422305a200b: Pull complete\n7d63f861dbef: Pull complete\n3eb97210645c: Pull complete\n869319d746ff: Already exists\n869319d746ff: Pulling fs layer\n902b87aaaec9: Already exists\nDigest: sha256:f836b4627b958b3f83f59c332f22f02fcd495ace3056f2be2c4912bd8704cc98\nStatus: Downloaded newer image for shaarli/shaarli:latest",
"title": "Download from DockerHub"
},
{
- "location": "/Shaarli-images/#create-and-start-a-new-container-from-the-image",
+ "location": "/docker/shaarli-images/#create-and-start-a-new-container-from-the-image",
"text": "# map the host's :8000 port to the container's :80 port\n$ docker create -p 8000:80 shaarli/shaarli\nd40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101\n\n# launch the container in the background\n$ docker start d40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101\nd40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101\n\n# list active containers\n$ docker ps\nCONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES\nd40b7af693d6 shaarli/shaarli /usr/bin/supervisor 15 seconds ago Up 4 seconds 0.0.0.0:8000->80/tcp backstabbing_galileo",
"title": "Create and start a new container from the image"
},
{
- "location": "/Shaarli-images/#stop-and-destroy-a-container",
+ "location": "/docker/shaarli-images/#stop-and-destroy-a-container",
"text": "$ docker stop backstabbing_galileo # those docker guys are really rude to physicists!\nbackstabbing_galileo\n\n# check the container is stopped\n$ docker ps\nCONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES\n\n# list ALL containers\n$ docker ps -a\nCONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES\nd40b7af693d6 shaarli/shaarli /usr/bin/supervisor 5 minutes ago Exited (0) 48 seconds ago backstabbing_galileo\n\n# destroy the container\n$ docker rm backstabbing_galileo # let's put an end to these barbarian practices\nbackstabbing_galileo\n\n$ docker ps -a\nCONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES",
"title": "Stop and destroy a container"
},
{
- "location": "/Reverse-proxy-configuration/",
+ "location": "/docker/reverse-proxy-configuration/",
"text": "TODO, see https://github.com/shaarli/Shaarli/issues/888\n\n\nHAProxy\n\n\nNginx",
"title": "Reverse proxy configuration"
},
{
- "location": "/Reverse-proxy-configuration/#haproxy",
+ "location": "/docker/reverse-proxy-configuration/#haproxy",
"text": "",
"title": "HAProxy"
},
{
- "location": "/Reverse-proxy-configuration/#nginx",
+ "location": "/docker/reverse-proxy-configuration/#nginx",
"text": "",
"title": "Nginx"
},
{
- "location": "/Docker-resources/",
+ "location": "/docker/resources/",
"text": "Docker\n\n\n\n\nInteractive Docker training portal\n on \nKatakoda\n\n\nWhere are Docker images stored?\n\n\nDockerfile reference\n\n\nDockerfile best practices\n\n\nVolumes\n\n\n\n\nDockerHub\n\n\n\n\nRepositories\n\n\nTeams and organizations\n\n\nGitHub automated build\n\n\n\n\nService management\n\n\n\n\nUsing supervisord\n\n\nNginx in the foreground\n\n\nsupervisord",
"title": "Docker resources"
},
{
- "location": "/Docker-resources/#docker",
+ "location": "/docker/resources/#docker",
"text": "Interactive Docker training portal on Katakoda Where are Docker images stored? Dockerfile reference Dockerfile best practices Volumes",
"title": "Docker"
},
{
- "location": "/Docker-resources/#dockerhub",
+ "location": "/docker/resources/#dockerhub",
"text": "Repositories Teams and organizations GitHub automated build",
"title": "DockerHub"
},
{
- "location": "/Docker-resources/#service-management",
+ "location": "/docker/resources/#service-management",
"text": "Using supervisord Nginx in the foreground supervisord",
"title": "Service management"
},
},
{
"location": "/Release-Shaarli/",
- "text": "See \nGit - Maintaining a project - Tagging your \nreleases\n.\n\n\nPrerequisites\n\n\nThis guide assumes that you have:\n- a GPG key matching your GitHub authentication credentials\n - i.e., the email address identified by the GPG key is the same as the one in your \n~/.gitconfig\n \n- a GitHub fork of Shaarli\n- a local clone of your Shaarli fork, with the following remotes:\n - \norigin\n pointing to your GitHub fork\n - \nupstream\n pointing to the main Shaarli repository\n- maintainer permissions on the main Shaarli repository, to:\n - push the signed tag\n - create a new release\n- \nComposer\n and \nPandoc\n need to be installed\n\n\nGitHub release draft and \nCHANGELOG.md\n\n\nSee http://keepachangelog.com/en/0.3.0/ for changelog formatting.\n\n\nGitHub release draft\n\n\nGitHub allows drafting the release note for the upcoming release, from the \nReleases\n page. This way, the release note can be drafted while contributions are merged to \nmaster\n.\n\n\nCHANGELOG.md\n\n\nThis file should contain the same information as the release note draft for the upcoming version.\n\n\nUpdate it to:\n- add new entries (additions, fixes, etc.)\n- mark the current version as released by setting its date and link\n- add a new section for the future unreleased version\n\n\n$ cd /path/to/shaarli\n\n$ nano CHANGELOG.md\n\n[...]\n## vA.B.C - UNRELEASED\nTBA\n\n## [vX.Y.Z](https://github.com/shaarli/Shaarli/releases/tag/vX.Y.Z) - YYYY-MM-DD\n[...]\n\n\n\n\nIncrement the version code, updated docs, create and push a signed tag\n\n\nGenerate documentation\n\n\n$ cd /path/to/shaarli\n\n# create a new branch\n$ git fetch upstream\n$ git checkout upstream/master -b v0.5.0\n\n# rebuild the documentation from the wiki\n$ make htmldoc\n\n# commit the changes\n$ git add doc\n$ git commit -s -m \"Generate documentation for v0.5.0\"\n\n# push the commit on your GitHub fork\n$ git push origin v0.5.0\n\n\n\n\nCreate and merge a Pull Request\n\n\nThis one is pretty straightforward ;-)\n\n\nBump Shaarli version to v0.x branch\n\n\n$ git checkout master\n$ git fetch upstream\n$ git pull upstream master\n\n# IF the branch doesn't exists\n$ git checkout -b v0.5\n# OR if the branch already exists\n$ git checkout v0.5\n$ git rebase upstream/master\n\n# Bump shaarli version from dev to 0.5.0, **without the `v`**\n$ vim shaarli_version.php\n$ git add shaarli_version\n$ git commit -s -m \"Bump Shaarli version to v0.5.0\"\n$ git push upstream v0.5\n\n\n\n\nCreate and push a signed tag\n\n\n# update your local copy\n$ git checkout v0.5\n$ git fetch upstream\n$ git pull upstream v0.5\n\n# create a signed tag\n$ git tag -s -m \"Release v0.5.0\" v0.5.0\n\n# push it to \"upstream\"\n$ git push --tags upstream\n\n\n\n\nVerify a signed tag\n\n\nv0.5.0\n is the first GPG-signed tag pushed on the Community Shaarli.\n\n\nLet's have a look at its signature!\n\n\n$ cd /path/to/shaarli\n$ git fetch upstream\n\n# get the SHA1 reference of the tag\n$ git show-ref tags/v0.5.0\nf7762cf803f03f5caf4b8078359a63783d0090c1 refs/tags/v0.5.0\n\n# verify the tag signature information\n$ git verify-tag f7762cf803f03f5caf4b8078359a63783d0090c1\ngpg: Signature made Thu 30 Jul 2015 11:46:34 CEST using RSA key ID 4100DF6F\ngpg: Good signature from \"VirtualTam <virtualtam@flibidi.net>\" [ultimate]\n\n\n\n\nPublish the GitHub release\n\n\nUpdate release badges\n\n\nUpdate \nREADME.md\n so version badges display and point to the newly released Shaarli version(s), in the \nmaster\n branch.\n\n\nCreate a GitHub release from a Git tag\n\n\nFrom the previously drafted release:\n- edit the release notes (if needed)\n- specify the appropriate Git tag\n- publish the release\n- profit!\n\n\nGenerate and upload all-in-one release archives\n\n\nUsers with a shared hosting may have:\n- no SSH access\n- no possibility to install PHP packages or server extensions\n- no possibility to run scripts\n\n\nTo ease Shaarli installations, it is possible to generate and upload additional release archives,\nthat will contain Shaarli code plus all required third-party libraries.\n\n\nFrom the \nv0.5\n branch:\n\n\n$ make release_archive\n\n\n\n\nThis will create the following archives:\n- \nshaarli-vX.Y.Z-full.tar\n\n- \nshaarli-vX.Y.Z-full.zip\n\n\nThe archives need to be manually uploaded on the previously created GitHub release.\n\n\nUpdate \nstable\n and \nlatest\n branches\n\n\n$ git checkout latest\n# latest release\n$ git merge v0.5.0\n# fix eventual conflicts\n$ make test\n$ git push upstream latest\n$ git checkout stable\n# latest previous major\n$ git merge v0.4.5 \n# fix eventual conflicts\n$ make test\n$ git push upstream stable",
+ "text": "See \nGit - Maintaining a project - Tagging your \nreleases\n.\n\n\nPrerequisites\n\n\nThis guide assumes that you have:\n- a GPG key matching your GitHub authentication credentials\n - i.e., the email address identified by the GPG key is the same as the one in your \n~/.gitconfig\n \n- a GitHub fork of Shaarli\n- a local clone of your Shaarli fork, with the following remotes:\n - \norigin\n pointing to your GitHub fork\n - \nupstream\n pointing to the main Shaarli repository\n- maintainer permissions on the main Shaarli repository, to:\n - push the signed tag\n - create a new release\n- \nComposer\n needs to be installed\n- The \nvenv\n Python 3 module needs to be installed for HTML documentation generation.\n\n\nGitHub release draft and \nCHANGELOG.md\n\n\nSee http://keepachangelog.com/en/0.3.0/ for changelog formatting.\n\n\nGitHub release draft\n\n\nGitHub allows drafting the release note for the upcoming release, from the \nReleases\n page. This way, the release note can be drafted while contributions are merged to \nmaster\n.\n\n\nCHANGELOG.md\n\n\nThis file should contain the same information as the release note draft for the upcoming version.\n\n\nUpdate it to:\n- add new entries (additions, fixes, etc.)\n- mark the current version as released by setting its date and link\n- add a new section for the future unreleased version\n\n\n$ cd /path/to/shaarli\n\n$ nano CHANGELOG.md\n\n[...]\n## vA.B.C - UNRELEASED\nTBA\n\n## [vX.Y.Z](https://github.com/shaarli/Shaarli/releases/tag/vX.Y.Z) - YYYY-MM-DD\n[...]\n\n\n\n\nIncrement the version code, updated docs, create and push a signed tag\n\n\nGenerate documentation\n\n\n$ cd /path/to/shaarli\n\n# create a new branch\n$ git fetch upstream\n$ git checkout upstream/master -b v0.5.0\n\n# rebuild the HTML documentation from Markdown\n$ make htmlpages\n\n# commit the changes\n$ git add doc\n$ git commit -s -m \"Generate documentation for v0.5.0\"\n\n# push the commit on your GitHub fork\n$ git push origin v0.5.0\n\n\n\n\nCreate and merge a Pull Request\n\n\nThis one is pretty straightforward ;-)\n\n\nBump Shaarli version to v0.x branch\n\n\n$ git checkout master\n$ git fetch upstream\n$ git pull upstream master\n\n# IF the branch doesn't exists\n$ git checkout -b v0.5\n# OR if the branch already exists\n$ git checkout v0.5\n$ git rebase upstream/master\n\n# Bump shaarli version from dev to 0.5.0, **without the `v`**\n$ vim shaarli_version.php\n$ git add shaarli_version\n$ git commit -s -m \"Bump Shaarli version to v0.5.0\"\n$ git push upstream v0.5\n\n\n\n\nCreate and push a signed tag\n\n\n# update your local copy\n$ git checkout v0.5\n$ git fetch upstream\n$ git pull upstream v0.5\n\n# create a signed tag\n$ git tag -s -m \"Release v0.5.0\" v0.5.0\n\n# push it to \"upstream\"\n$ git push --tags upstream\n\n\n\n\nVerify a signed tag\n\n\nv0.5.0\n is the first GPG-signed tag pushed on the Community Shaarli.\n\n\nLet's have a look at its signature!\n\n\n$ cd /path/to/shaarli\n$ git fetch upstream\n\n# get the SHA1 reference of the tag\n$ git show-ref tags/v0.5.0\nf7762cf803f03f5caf4b8078359a63783d0090c1 refs/tags/v0.5.0\n\n# verify the tag signature information\n$ git verify-tag f7762cf803f03f5caf4b8078359a63783d0090c1\ngpg: Signature made Thu 30 Jul 2015 11:46:34 CEST using RSA key ID 4100DF6F\ngpg: Good signature from \"VirtualTam <virtualtam@flibidi.net>\" [ultimate]\n\n\n\n\nPublish the GitHub release\n\n\nUpdate release badges\n\n\nUpdate \nREADME.md\n so version badges display and point to the newly released Shaarli version(s), in the \nmaster\n branch.\n\n\nCreate a GitHub release from a Git tag\n\n\nFrom the previously drafted release:\n- edit the release notes (if needed)\n- specify the appropriate Git tag\n- publish the release\n- profit!\n\n\nGenerate and upload all-in-one release archives\n\n\nUsers with a shared hosting may have:\n- no SSH access\n- no possibility to install PHP packages or server extensions\n- no possibility to run scripts\n\n\nTo ease Shaarli installations, it is possible to generate and upload additional release archives,\nthat will contain Shaarli code plus all required third-party libraries.\n\n\nFrom the \nv0.5\n branch:\n\n\n$ make release_archive\n\n\n\n\nThis will create the following archives:\n- \nshaarli-vX.Y.Z-full.tar\n\n- \nshaarli-vX.Y.Z-full.zip\n\n\nThe archives need to be manually uploaded on the previously created GitHub release.\n\n\nUpdate \nstable\n and \nlatest\n branches\n\n\n$ git checkout latest\n# latest release\n$ git merge v0.5.0\n# fix eventual conflicts\n$ make test\n$ git push upstream latest\n$ git checkout stable\n# latest previous major\n$ git merge v0.4.5 \n# fix eventual conflicts\n$ make test\n$ git push upstream stable",
"title": "Release Shaarli"
},
{
"location": "/Release-Shaarli/#prerequisites",
- "text": "This guide assumes that you have:\n- a GPG key matching your GitHub authentication credentials\n - i.e., the email address identified by the GPG key is the same as the one in your ~/.gitconfig \n- a GitHub fork of Shaarli\n- a local clone of your Shaarli fork, with the following remotes:\n - origin pointing to your GitHub fork\n - upstream pointing to the main Shaarli repository\n- maintainer permissions on the main Shaarli repository, to:\n - push the signed tag\n - create a new release\n- Composer and Pandoc need to be installed",
+ "text": "This guide assumes that you have:\n- a GPG key matching your GitHub authentication credentials\n - i.e., the email address identified by the GPG key is the same as the one in your ~/.gitconfig \n- a GitHub fork of Shaarli\n- a local clone of your Shaarli fork, with the following remotes:\n - origin pointing to your GitHub fork\n - upstream pointing to the main Shaarli repository\n- maintainer permissions on the main Shaarli repository, to:\n - push the signed tag\n - create a new release\n- Composer needs to be installed\n- The venv Python 3 module needs to be installed for HTML documentation generation.",
"title": "Prerequisites"
},
{
},
{
"location": "/Release-Shaarli/#generate-documentation",
- "text": "$ cd /path/to/shaarli\n\n# create a new branch\n$ git fetch upstream\n$ git checkout upstream/master -b v0.5.0\n\n# rebuild the documentation from the wiki\n$ make htmldoc\n\n# commit the changes\n$ git add doc\n$ git commit -s -m \"Generate documentation for v0.5.0\"\n\n# push the commit on your GitHub fork\n$ git push origin v0.5.0",
+ "text": "$ cd /path/to/shaarli\n\n# create a new branch\n$ git fetch upstream\n$ git checkout upstream/master -b v0.5.0\n\n# rebuild the HTML documentation from Markdown\n$ make htmlpages\n\n# commit the changes\n$ git add doc\n$ git commit -s -m \"Generate documentation for v0.5.0\"\n\n# push the commit on your GitHub fork\n$ git push origin v0.5.0",
"title": "Generate documentation"
},
{