2016-10-12 12:36:59 +02:00
<!DOCTYPE html>
< html >
< head >
< meta charset = "utf-8" >
< meta name = "generator" content = "pandoc" >
< meta name = "viewport" content = "width=device-width, initial-scale=1.0, user-scalable=yes" >
< title > Shaarli – < / title >
< style type = "text/css" > code { white-space : pre ; } < / style >
< style type = "text/css" >
div.sourceCode { overflow-x: auto; }
table.sourceCode, tr.sourceCode, td.lineNumbers, td.sourceCode {
margin: 0; padding: 0; vertical-align: baseline; border: none; }
table.sourceCode { width: 100%; line-height: 100%; }
td.lineNumbers { text-align: right; padding-right: 4px; padding-left: 4px; color: #aaaaaa; border-right: 1px solid #aaaaaa; }
td.sourceCode { padding-left: 5px; }
code > span.kw { color: #007020; font-weight: bold; } /* Keyword */
code > span.dt { color: #902000; } /* DataType */
code > span.dv { color: #40a070; } /* DecVal */
code > span.bn { color: #40a070; } /* BaseN */
code > span.fl { color: #40a070; } /* Float */
code > span.ch { color: #4070a0; } /* Char */
code > span.st { color: #4070a0; } /* String */
code > span.co { color: #60a0b0; font-style: italic; } /* Comment */
code > span.ot { color: #007020; } /* Other */
code > span.al { color: #ff0000; font-weight: bold; } /* Alert */
code > span.fu { color: #06287e; } /* Function */
code > span.er { color: #ff0000; font-weight: bold; } /* Error */
code > span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */
code > span.cn { color: #880000; } /* Constant */
code > span.sc { color: #4070a0; } /* SpecialChar */
code > span.vs { color: #4070a0; } /* VerbatimString */
code > span.ss { color: #bb6688; } /* SpecialString */
code > span.im { } /* Import */
code > span.va { color: #19177c; } /* Variable */
code > span.cf { color: #007020; font-weight: bold; } /* ControlFlow */
code > span.op { color: #666666; } /* Operator */
code > span.bu { } /* BuiltIn */
code > span.ex { } /* Extension */
code > span.pp { color: #bc7a00; } /* Preprocessor */
code > span.at { color: #7d9029; } /* Attribute */
code > span.do { color: #ba2121; font-style: italic; } /* Documentation */
code > span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */
code > span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */
code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */
< / style >
< link rel = "stylesheet" href = "github-markdown.css" >
<!-- [if lt IE 9]>
< script src = "//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv-printshiv.min.js" > < / script >
<![endif]-->
< / head >
< body >
< div id = "local-sidebar" >
< ul >
< li > < a href = "Home.html" > Home< / a > < / li >
< li > Setup
< ul >
< li > < a href = "Download-and-Installation.html" > Download and Installation< / a > < / li >
< li > < a href = "Upgrade-and-migration.html" > Upgrade and migration< / a > < / li >
< li > < a href = "Server-requirements.html" > Server requirements< / a > < / li >
< li > < a href = "Server-configuration.html" > Server configuration< / a > < / li >
< li > < a href = "Server-security.html" > Server security< / a > < / li >
< li > < a href = "Shaarli-configuration.html" > Shaarli configuration< / a > < / li >
< li > < a href = "Plugins.html" > Plugins< / a > < / li >
< / ul > < / li >
< li > < a href = "Docker.html" > Docker< / a > < / li >
< li > < a href = "Usage.html" > Usage< / a >
< ul >
< li > < a href = "Sharing-button.html" > Sharing button< / a > (bookmarklet)< / li >
< li > < a href = "Browsing-and-Searching.html" > Browsing and Searching< / a > < / li >
< li > < a href = "Firefox-share.html" > Firefox share< / a > < / li >
< li > < a href = "RSS-feeds.html" > RSS feeds< / a > < / li >
2017-05-07 18:44:05 +02:00
< li > < a href = "REST-API.html" > REST API< / a > < / li >
2016-10-12 12:36:59 +02:00
< / ul > < / li >
< li > How To
< ul >
< li > < a href = "Backup,-restore,-import-and-export.html" > Backup, restore, import and export< / a > < / li >
< li > < a href = "Copy-an-existing-installation-over-SSH-and-serve-it-locally.html" > Copy an existing installation over SSH and serve it locally< / a > < / li >
< li > < a href = "Create-and-serve-multiple-Shaarlis-(farm).html" > Create and serve multiple Shaarlis (farm)< / a > < / li >
< li > < a href = "Download-CSS-styles-from-an-OPML-list.html" > Download CSS styles from an OPML list< / a > < / li >
< li > < a href = "Datastore-hacks.html" > Datastore hacks< / a > < / li >
< / ul > < / li >
< li > < a href = "Troubleshooting.html" > Troubleshooting< / a > < / li >
< li > < a href = "Development.html" > Development< / a >
< ul >
< li > < a href = "GnuPG-signature.html" > GnuPG signature< / a > < / li >
< li > < a href = "Coding-guidelines.html" > Coding guidelines< / a > < / li >
< li > < a href = "Directory-structure.html" > Directory structure< / a > < / li >
< li > < a href = "3rd-party-libraries.html" > 3rd party libraries< / a > < / li >
< li > < a href = "Plugin-System.html" > Plugin System< / a > < / li >
< li > < a href = "Release-Shaarli.html" > Release Shaarli< / a > < / li >
2017-05-07 18:44:05 +02:00
< li > < a href = "Versioning-and-Branches.html" > Versioning and Branches< / a > < / li >
2016-10-12 12:36:59 +02:00
< li > < a href = "Security.html" > Security< / a > < / li >
< li > < a href = "Static-analysis.html" > Static analysis< / a > < / li >
< li > < a href = "Theming.html" > Theming< / a > < / li >
< li > < a href = "Unit-tests.html" > Unit tests< / a > < / li >
< / ul > < / li >
< li > About
< ul >
< li > < a href = "FAQ.html" > FAQ< / a > < / li >
< li > < a href = "Community-&-Related-software.html" > Community & Related software< / a > < / li >
< / ul > < / li >
< / ul >
< / div >
< h1 id = "upgrade-and-migration" > Upgrade and migration< / h1 >
< h2 id = "preparation" > Preparation< / h2 >
2017-05-07 18:44:05 +02:00
< h3 id = "note-your-current-version" > Note your current version< / h3 >
< p > If anything goes wrong, it's important for us to know which version you're upgrading from.< br / >
The current version is present in the < code > version.php< / code > file.< / p >
2016-10-12 12:36:59 +02:00
< h3 id = "backup-your-data" > Backup your data< / h3 >
< p > Shaarli stores all user data under the < code > data< / code > directory:< / p >
< ul >
< li > < code > data/config.php< / code > - main configuration file< / li >
< li > < code > data/datastore.php< / code > - bookmarked links< / li >
< li > < code > data/ipbans.php< / code > - banned IP addresses< / li >
2017-05-07 18:44:05 +02:00
< li > < code > data/updates.txt< / code > - contains all automatic update to the configuration and datastore files already run< / li >
2016-10-12 12:36:59 +02:00
< / ul >
< p > See < a href = "Shaarli-configuration.html" > Shaarli configuration< / a > for more information about Shaarli resources.< / p >
< p > It is recommended to backup this repository < em > before< / em > starting updating/upgrading Shaarli:< / p >
< ul >
< li > users with SSH access: copy or archive the directory to a temporary location< / li >
< li > users with FTP access: download a local copy of your Shaarli installation using your favourite client< / li >
< / ul >
< h3 id = "migrating-data-from-a-previous-installation" > Migrating data from a previous installation< / h3 >
< p > As all user data is kept under < code > data< / code > , this is the only directory you need to worry about when migrating to a new installation, which corresponds to the following steps:< / p >
< ul >
< li > backup the < code > data< / code > directory< / li >
< li > install or update Shaarli:
< ul >
< li > fresh installation - see < a href = "Download-and-installation.html" > Download and installation< / a > < / li >
< li > update - see the following sections< / li >
< / ul > < / li >
< li > check or restore the < code > data< / code > directory< / li >
< / ul >
2017-05-07 18:44:05 +02:00
< h2 id = "recommended-upgrading-from-release-archives" > Recommended : Upgrading from release archives< / h2 >
2016-10-12 12:36:59 +02:00
< p > All tagged revisions can be downloaded as tarballs or ZIP archives from the < a href = "https://github.com/shaarli/Shaarli/releases" > releases< / a > page.< a href = ".html" > < / a > < / p >
2017-05-07 18:44:05 +02:00
< p > We recommend that you use the latest release tarball with the < code > -full< / code > suffix. It contains the dependencies, please read < a href = "Download-and-installation.html" > Download and installation< / a > for < code > git< / code > complete instructions.< / p >
< p > Once downloaded, extract the archive locally and update your remote installation (e.g. via FTP) -be sure you keep the content of the < code > data< / code > directory!< / p >
< p > After upgrading, access your fresh Shaarli installation from a web browser; the configuration and data store will then be automatically updated, and new settings added to < code > data/config.json.php< / code > (see < a href = "Shaarli-configuration.html" > Shaarli configuration< / a > for more details).< / p >
2016-10-12 12:36:59 +02:00
< h2 id = "upgrading-with-git" > Upgrading with Git< / h2 >
< h3 id = "updating-a-community-shaarli" > Updating a community Shaarli< / h3 >
< p > If you have installed Shaarli from the < a href = "Download#clone-with-git-recommended" > community Git repository< / a > , simply < a href = "https://www.git-scm.com/docs/git-pull" > pull new changes< / a > from your local clone:< a href = ".html" > < / a > < / p >
< div class = "sourceCode" > < pre class = "sourceCode bash" > < code class = "sourceCode bash" > $ < span class = "bu" > cd< / span > /path/to/shaarli
$ < span class = "fu" > git< / span > pull
< span class = "ex" > From< / span > github.com:shaarli/Shaarli
< span class = "ex" > *< / span > branch master -< span class = "op" > > < / span > FETCH_HEAD
< span class = "ex" > Updating< / span > ebd67c6..521f0e6
< span class = "ex" > Fast-forward< / span >
< span class = "ex" > application/Url.php< / span > < span class = "kw" > |< / span > < span class = "ex" > 1< / span > +
< span class = "ex" > shaarli_version.php< / span > < span class = "kw" > |< / span > < span class = "ex" > 2< / span > +-
< span class = "ex" > tests/Url/UrlTest.php< / span > < span class = "kw" > |< / span > < span class = "ex" > 1< / span > +
< span class = "ex" > 3< / span > files changed, 3 insertions(+), < span class = "ex" > 1< / span > deletion(-)< / code > < / pre > < / div >
< p > Shaarli > = < code > v0.8.x< / code > : install/update third-party PHP dependencies using < a href = "https://getcomposer.org/" > Composer< / a > :< a href = ".html" > < / a > < / p >
2017-05-07 18:44:05 +02:00
< div class = "sourceCode" > < pre class = "sourceCode bash" > < code class = "sourceCode bash" > $ < span class = "ex" > composer< / span > install --no-dev
2016-10-12 12:36:59 +02:00
< span class = "ex" > Loading< / span > composer repositories with package information
< span class = "ex" > Updating< / span > dependencies
< span class = "ex" > -< / span > Installing shaarli/netscape-bookmark-parser (v1.0.1)
< span class = "ex" > Downloading< / span > : 100%< / code > < / pre > < / div >
< h3 id = "migrating-and-upgrading-from-sebsauvages-repository" > Migrating and upgrading from Sebsauvage's repository< / h3 >
< p > If you have installed Shaarli from < a href = "https://github.com/sebsauvage/Shaarli" > Sebsauvage's original Git repository< / a > , you can use < a href = "https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes" > Git remotes< / a > to update your working copy.< a href = ".html" > < / a > < / p >
< p > The following guide assumes that:< / p >
< ul >
< li > you have a basic knowledge of Git < a href = "https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell" > branching< / a > and < a href = "https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes" > remote repositories< / a > < a href = ".html" > < / a > < / li >
< li > the default remote is named < code > origin< / code > and points to Sebsauvage's repository< / li >
< li > the current branch is < code > master< / code >
< ul >
< li > if you have personal branches containing customizations, you will need to < a href = "https://git-scm.com/book/en/v2/Git-Branching-Rebasing" > rebase them< / a > after the upgrade; beware though, a lot of changes have been made since the community fork has been created, so things are very likely to break< embed src = ".html" / > < / li >
< / ul > < / li >
< li > the working copy is clean:
< ul >
< li > no versioned file has been locally modified< / li >
< li > no untracked files are present< / li >
< / ul > < / li >
< / ul >
< h4 id = "step-0-show-repository-information" > Step 0: show repository information< / h4 >
< div class = "sourceCode" > < pre class = "sourceCode bash" > < code class = "sourceCode bash" > $ < span class = "bu" > cd< / span > /path/to/shaarli
$ < span class = "fu" > git< / span > remote -v
< span class = "ex" > origin< / span > https://github.com/sebsauvage/Shaarli (fetch)
< span class = "ex" > origin< / span > https://github.com/sebsauvage/Shaarli (push)
$ < span class = "fu" > git< / span > branch -vv
< span class = "ex" > *< / span > master 029f75f [origin/master] Update README.md[](.html)
$ < span class = "fu" > git< / span > status
< span class = "ex" > On< / span > branch master
< span class = "ex" > Your< / span > branch is up-to-date with < span class = "st" > ' origin/master' < / span > .
< span class = "ex" > nothing< / span > to commit, working directory clean< / code > < / pre > < / div >
< h4 id = "step-1-update-git-remotes" > Step 1: update Git remotes< / h4 >
< pre > < code > $ git remote rename origin sebsauvage
$ git remote -v
sebsauvage https://github.com/sebsauvage/Shaarli (fetch)
sebsauvage https://github.com/sebsauvage/Shaarli (push)
$ git remote add origin https://github.com/shaarli/Shaarli
$ git fetch origin
remote: Counting objects: 3015, done.
remote: Compressing objects: 100% (19/19), done.
remote: Total 3015 (delta 446), reused 457 (delta 446), pack-reused 2550
Receiving objects: 100% (3015/3015), 2.59 MiB | 918.00 KiB/s, done.
Resolving deltas: 100% (1899/1899), completed with 48 local objects.
From https://github.com/shaarli/Shaarli
* [new branch] master -> origin/master[](.html)
* [new branch] stable -> origin/stable[](.html)
[...][](.html)
* [new tag] v0.6.4 -> v0.6.4[](.html)
* [new tag] v0.7.0 -> v0.7.0[](.html)< / code > < / pre >
< h4 id = "step-2-use-the-stable-community-branch" > Step 2: use the stable community branch< / h4 >
< div class = "sourceCode" > < pre class = "sourceCode bash" > < code class = "sourceCode bash" > $ < span class = "fu" > git< / span > checkout origin/stable -b stable
< span class = "ex" > Branch< / span > stable set up to track remote branch stable from origin.
< span class = "ex" > Switched< / span > to a new branch < span class = "st" > ' stable' < / span >
$ < span class = "fu" > git< / span > branch -vv
< span class = "ex" > master< / span > 029f75f [sebsauvage/master] Update README.md[](.html)
< span class = "ex" > *< / span > stable 890afc3 [origin/stable] Merge pull request < span class = "co" > #509 from ArthurHoaro/v0.6.5[](.html)< / span > < / code > < / pre > < / div >
< p > Shaarli > = < code > v0.8.x< / code > : install/update third-party PHP dependencies using < a href = "https://getcomposer.org/" > Composer< / a > :< a href = ".html" > < / a > < / p >
2017-05-07 18:44:05 +02:00
< div class = "sourceCode" > < pre class = "sourceCode bash" > < code class = "sourceCode bash" > $ < span class = "ex" > composer< / span > install --no-dev
2016-10-12 12:36:59 +02:00
< span class = "ex" > Loading< / span > composer repositories with package information
< span class = "ex" > Updating< / span > dependencies
< span class = "ex" > -< / span > Installing shaarli/netscape-bookmark-parser (v1.0.1)
< span class = "ex" > Downloading< / span > : 100%< / code > < / pre > < / div >
< p > Optionally, you can delete information related to the legacy version:< / p >
< div class = "sourceCode" > < pre class = "sourceCode bash" > < code class = "sourceCode bash" > $ < span class = "fu" > git< / span > branch -D master
< span class = "ex" > Deleted< / span > branch master (was 029f75f)< span class = "ex" > .< / span >
$ < span class = "fu" > git< / span > remote remove sebsauvage
$ < span class = "fu" > git< / span > remote -v
< span class = "ex" > origin< / span > https://github.com/shaarli/Shaarli (fetch)
< span class = "ex" > origin< / span > https://github.com/shaarli/Shaarli (push)
$ < span class = "fu" > git< / span > gc
< span class = "ex" > Counting< / span > objects: 3317, done.
< span class = "ex" > Delta< / span > compression using up to 8 threads.
< span class = "ex" > Compressing< / span > objects: 100% (1237/1237), < span class = "kw" > done< / span > < span class = "ex" > .< / span >
< span class = "ex" > Writing< / span > objects: 100% (3317/3317), < span class = "kw" > done< / span > < span class = "ex" > .< / span >
< span class = "ex" > Total< / span > 3317 (delta 2050), < span class = "ex" > reused< / span > 3301 (delta 2034)< span class = "ex" > to< / span > < / code > < / pre > < / div >
< h4 id = "step-3-configuration" > Step 3: configuration< / h4 >
< p > After migrating, access your fresh Shaarli installation from a web browser; the configuration will then be automatically updated, and new settings added to < code > data/config.php< / code > (see < a href = "Shaarli-configuration.html" > Shaarli configuration< / a > for more details).< / p >
2017-05-07 18:44:05 +02:00
< h2 id = "troubleshooting" > Troubleshooting< / h2 >
< p > If the solutions provided here doesn't work, please open an issue specifying which version you're upgrading from and to.< / p >
< h3 id = "you-must-specify-an-integer-as-a-key" > You must specify an integer as a key< / h3 >
< p > In < code > v0.8.1< / code > we changed how link keys are handled (from timestamps to incremental integers).< br / >
Take a look at < code > data/updates.txt< / code > content.< / p >
< h4 id = "updates.txt-contains-updatemethoddatastoreids" > < code > updates.txt< / code > contains < code > updateMethodDatastoreIds< / code > < / h4 >
< p > Try to delete it and refresh your page while being logged in.< / p >
< h4 id = "updates.txt-doesnt-exists-or-doesnt-contain-updatemethoddatastoreids" > < code > updates.txt< / code > doesn't exists or doesn't contain < code > updateMethodDatastoreIds< / code > < / h4 >
< ol >
< li > Create < code > data/updates.txt< / code > if it doesn't exist.< / li >
< li > Paste this string in the update file < code > ;updateMethodRenameDashTags;< / code > < / li >
< li > Login to Shaarli.< / li >
< li > Delete the update file.< / li >
< li > Refresh.< / li >
< / ol >
2016-10-12 12:36:59 +02:00
< / body >
< / html >
