2 <!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
3 <!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
6 <meta http-equiv=
"X-UA-Compatible" content=
"IE=edge">
7 <meta name=
"viewport" content=
"width=device-width, initial-scale=1.0">
10 <link rel=
"shortcut icon" href=
"../img/favicon.ico">
11 <title>Upgrade and migration - Shaarli Documentation
</title>
12 <link href='https://fonts.googleapis.com/css?family=Lato:
400,
700|Roboto+Slab:
400,
700|Inconsolata:
400,
700' rel='stylesheet' type='text/css'
>
14 <link rel=
"stylesheet" href=
"../css/theme.css" type=
"text/css" />
15 <link rel=
"stylesheet" href=
"../css/theme_extra.css" type=
"text/css" />
16 <link rel=
"stylesheet" href=
"../css/highlight.css">
17 <link href=
"../github-markdown.css" rel=
"stylesheet">
21 var mkdocs_page_name = "Upgrade and migration";
22 var mkdocs_page_input_path = "Upgrade-and-migration.md";
23 var mkdocs_page_url = "/Upgrade-and-migration/";
26 <script src=
"../js/jquery-2.1.1.min.js"></script>
27 <script src=
"../js/modernizr-2.8.3.min.js"></script>
28 <script type=
"text/javascript" src=
"../js/highlight.pack.js"></script>
32 <body class=
"wy-body-for-nav" role=
"document">
34 <div class=
"wy-grid-for-nav">
37 <nav data-toggle=
"wy-nav-shift" class=
"wy-nav-side stickynav">
38 <div class=
"wy-side-nav-search">
39 <a href=
".." class=
"icon icon-home"> Shaarli Documentation
</a>
41 <form id =
"rtd-search-form" class=
"wy-form" action=
"../search.html" method=
"get">
42 <input type=
"text" name=
"q" placeholder=
"Search docs" />
47 <div class=
"wy-menu wy-menu-vertical" data-spy=
"affix" role=
"navigation" aria-label=
"main navigation">
51 <li class=
"toctree-l1">
53 <a class=
"" href=
"..">Home
</a>
56 <li class=
"toctree-l1">
58 <span class=
"caption-text">Setup
</span>
62 <a class=
"" href=
"../Download-and-Installation/">Download and Installation
</a>
66 <a class=
"current" href=
"./">Upgrade and migration
</a>
69 <li class=
"toctree-l3"><a href=
"#preparation">Preparation
</a></li>
73 <li><a class=
"toctree-l4" href=
"#note-your-current-version">Note your current version
</a></li>
75 <li><a class=
"toctree-l4" href=
"#backup-your-data">Backup your data
</a></li>
77 <li><a class=
"toctree-l4" href=
"#migrating-data-from-a-previous-installation">Migrating data from a previous installation
</a></li>
82 <li class=
"toctree-l3"><a href=
"#recommended-upgrading-from-release-archives">Recommended : Upgrading from release archives
</a></li>
85 <li class=
"toctree-l3"><a href=
"#upgrading-with-git">Upgrading with Git
</a></li>
89 <li><a class=
"toctree-l4" href=
"#updating-a-community-shaarli">Updating a community Shaarli
</a></li>
91 <li><a class=
"toctree-l4" href=
"#migrating-and-upgrading-from-sebsauvages-repository">Migrating and upgrading from Sebsauvage's repository
</a></li>
96 <li class=
"toctree-l3"><a href=
"#troubleshooting">Troubleshooting
</a></li>
100 <li><a class=
"toctree-l4" href=
"#you-must-specify-an-integer-as-a-key">You must specify an integer as a key
</a></li>
109 <a class=
"" href=
"../Server-requirements/">Server requirements
</a>
113 <a class=
"" href=
"../Server-configuration/">Server configuration
</a>
117 <a class=
"" href=
"../Server-security/">Server security
</a>
121 <a class=
"" href=
"../Shaarli-configuration/">Shaarli configuration
</a>
125 <a class=
"" href=
"../Plugins/">Plugins
</a>
130 <li class=
"toctree-l1">
132 <span class=
"caption-text">Docker
</span>
136 <a class=
"" href=
"../Docker-101/">Docker
101</a>
140 <a class=
"" href=
"../Shaarli-images/">Shaarli images
</a>
144 <a class=
"" href=
"../Reverse-proxy-configuration/">Reverse proxy configuration
</a>
148 <a class=
"" href=
"../Docker-resources/">Docker resources
</a>
153 <li class=
"toctree-l1">
155 <span class=
"caption-text">Usage
</span>
159 <a class=
"" href=
"../Features/">Features
</a>
163 <a class=
"" href=
"../Bookmarklet/">Bookmarklet
</a>
167 <a class=
"" href=
"../Browsing-and-searching/">Browsing and searching
</a>
171 <a class=
"" href=
"../Firefox-share/">Firefox share
</a>
175 <a class=
"" href=
"../RSS-feeds/">RSS feeds
</a>
179 <a class=
"" href=
"../REST-API/">REST API
</a>
184 <li class=
"toctree-l1">
186 <span class=
"caption-text">How To
</span>
190 <a class=
"" href=
"../Backup,-restore,-import-and-export/">Backup, restore, import and export
</a>
194 <a class=
"" href=
"../Various-hacks/">Various hacks
</a>
199 <li class=
"toctree-l1">
201 <a class=
"" href=
"../Troubleshooting/">Troubleshooting
</a>
204 <li class=
"toctree-l1">
206 <span class=
"caption-text">Development
</span>
210 <a class=
"" href=
"../Development-guidelines/">Development guidelines
</a>
214 <a class=
"" href=
"../Continuous-integration-tools/">Continuous integration tools
</a>
218 <a class=
"" href=
"../GnuPG-signature/">GnuPG signature
</a>
222 <a class=
"" href=
"../Coding-guidelines/">Coding guidelines
</a>
226 <a class=
"" href=
"../Directory-structure/">Directory structure
</a>
230 <a class=
"" href=
"../3rd-party-libraries/">3rd party libraries
</a>
234 <a class=
"" href=
"../Plugin-System/">Plugin System
</a>
238 <a class=
"" href=
"../Release-Shaarli/">Release Shaarli
</a>
242 <a class=
"" href=
"../Versioning-and-Branches/">Versioning and Branches
</a>
246 <a class=
"" href=
"../Security/">Security
</a>
250 <a class=
"" href=
"../Static-analysis/">Static analysis
</a>
254 <a class=
"" href=
"../Theming/">Theming
</a>
258 <a class=
"" href=
"../Unit-tests/">Unit tests
</a>
263 <li class=
"toctree-l1">
265 <span class=
"caption-text">About
</span>
269 <a class=
"" href=
"../FAQ/">FAQ
</a>
273 <a class=
"" href=
"../Community-&-Related-software/">Community & Related software
</a>
283 <section data-toggle=
"wy-nav-shift" class=
"wy-nav-content-wrap">
286 <nav class=
"wy-nav-top" role=
"navigation" aria-label=
"top navigation">
287 <i data-toggle=
"wy-nav-top" class=
"fa fa-bars"></i>
288 <a href=
"..">Shaarli Documentation
</a>
292 <div class=
"wy-nav-content">
293 <div class=
"rst-content">
294 <div role=
"navigation" aria-label=
"breadcrumbs navigation">
295 <ul class=
"wy-breadcrumbs">
296 <li><a href=
"..">Docs
</a> »</li>
300 <li>Setup
»</li>
304 <li>Upgrade and migration
</li>
305 <li class=
"wy-breadcrumbs-aside">
307 <a href=
"https://github.com/shaarli/Shaarli/edit/master/docs/Upgrade-and-migration.md"
308 class=
"icon icon-github"> Edit on GitHub
</a>
315 <div class=
"section">
317 <h2 id=
"preparation">Preparation
</h2>
318 <h3 id=
"note-your-current-version">Note your current version
</h3>
319 <p>If anything goes wrong, it's important for us to know which version you're upgrading from.
<br />
320 The current version is present in the
<code>version.php
</code> file.
</p>
321 <h3 id=
"backup-your-data">Backup your data
</h3>
322 <p>Shaarli stores all user data under the
<code>data
</code> directory:
323 -
<code>data/config.php
</code> - main configuration file
324 -
<code>data/datastore.php
</code> - bookmarked links
325 -
<code>data/ipbans.php
</code> - banned IP addresses
326 -
<code>data/updates.txt
</code> - contains all automatic update to the configuration and datastore files already run
</p>
327 <p>See
<a href=
"../Shaarli configuration">Shaarli configuration
</a> for more information about Shaarli resources.
</p>
328 <p>It is recommended to backup this repository
<em>before
</em> starting updating/upgrading Shaarli:
329 - users with SSH access: copy or archive the directory to a temporary location
330 - users with FTP access: download a local copy of your Shaarli installation using your favourite client
</p>
331 <h3 id=
"migrating-data-from-a-previous-installation">Migrating data from a previous installation
</h3>
332 <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>
334 <li>backup the
<code>data
</code> directory
</li>
335 <li>install or update Shaarli:
<ul>
336 <li>fresh installation - see
<a href=
"../Download and installation">Download and installation
</a></li>
337 <li>update - see the following sections
</li>
340 <li>check or restore the
<code>data
</code> directory
</li>
342 <h2 id=
"recommended-upgrading-from-release-archives">Recommended : Upgrading from release archives
</h2>
343 <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.
</p>
344 <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">Download and installation
</a> for
<code>git
</code> complete instructions.
</p>
345 <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>
346 <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">Shaarli configuration
</a> for more details).
</p>
347 <h2 id=
"upgrading-with-git">Upgrading with Git
</h2>
348 <h3 id=
"updating-a-community-shaarli">Updating a community Shaarli
</h3>
349 <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:
</p>
350 <pre><code class=
"bash">$ cd /path/to/shaarli
353 From github.com:shaarli/Shaarli
354 * branch master -
> FETCH_HEAD
355 Updating ebd67c6.
.521f0e6
357 application/Url.php |
1 +
358 shaarli_version.php |
2 +-
359 tests/Url/UrlTest.php |
1 +
360 3 files changed,
3 insertions(+),
1 deletion(-)
363 <p>Shaarli
>=
<code>v0.8.x
</code>: install/update third-party PHP dependencies using
<a href=
"https://getcomposer.org/">Composer
</a>:
</p>
364 <pre><code class=
"bash">$ composer install --no-dev
366 Loading composer repositories with package information
367 Updating dependencies
368 - Installing shaarli/netscape-bookmark-parser (v1.0
.1)
372 <h3 id=
"migrating-and-upgrading-from-sebsauvages-repository">Migrating and upgrading from Sebsauvage's repository
</h3>
373 <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.
</p>
374 <p>The following guide assumes that:
375 - 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>
376 - the default remote is named
<code>origin
</code> and points to Sebsauvage's repository
377 - the current branch is
<code>master
</code>
378 - 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!
379 - the working copy is clean:
380 - no versioned file has been locally modified
381 - no untracked files are present
</p>
382 <h4 id=
"step-0-show-repository-information">Step
0: show repository information
</h4>
383 <pre><code class=
"bash">$ cd /path/to/shaarli
386 origin https://github.com/sebsauvage/Shaarli (fetch)
387 origin https://github.com/sebsauvage/Shaarli (push)
390 * master
029f75f [origin/master] Update README.md
394 Your branch is up-to-date with 'origin/master'.
395 nothing to commit, working directory clean
398 <h4 id=
"step-1-update-git-remotes">Step
1: update Git remotes
</h4>
399 <pre><code>$ git remote rename origin sebsauvage
401 sebsauvage https://github.com/sebsauvage/Shaarli (fetch)
402 sebsauvage https://github.com/sebsauvage/Shaarli (push)
404 $ git remote add origin https://github.com/shaarli/Shaarli
407 remote: Counting objects:
3015, done.
408 remote: Compressing objects:
100% (
19/
19), done.
409 remote: Total
3015 (delta
446), reused
457 (delta
446), pack-reused
2550
410 Receiving objects:
100% (
3015/
3015),
2.59 MiB |
918.00 KiB/s, done.
411 Resolving deltas:
100% (
1899/
1899), completed with
48 local objects.
412 From https://github.com/shaarli/Shaarli
413 * [new branch] master -
> origin/master
414 * [new branch] stable -
> origin/stable
416 * [new tag] v0.6
.4 -
> v0.6
.4
417 * [new tag] v0.7
.0 -
> v0.7
.0
420 <h4 id=
"step-2-use-the-stable-community-branch">Step
2: use the stable community branch
</h4>
421 <pre><code class=
"bash">$ git checkout origin/stable -b stable
422 Branch stable set up to track remote branch stable from origin.
423 Switched to a new branch 'stable'
426 master
029f75f [sebsauvage/master] Update README.md
427 * stable
890afc3 [origin/stable] Merge pull request #
509 from ArthurHoaro/v0.6
.5
430 <p>Shaarli
>=
<code>v0.8.x
</code>: install/update third-party PHP dependencies using
<a href=
"https://getcomposer.org/">Composer
</a>:
</p>
431 <pre><code class=
"bash">$ composer install --no-dev
433 Loading composer repositories with package information
434 Updating dependencies
435 - Installing shaarli/netscape-bookmark-parser (v1.0
.1)
439 <p>Optionally, you can delete information related to the legacy version:
</p>
440 <pre><code class=
"bash">$ git branch -D master
441 Deleted branch master (was
029f75f).
443 $ git remote remove sebsauvage
446 origin https://github.com/shaarli/Shaarli (fetch)
447 origin https://github.com/shaarli/Shaarli (push)
450 Counting objects:
3317, done.
451 Delta compression using up to
8 threads.
452 Compressing objects:
100% (
1237/
1237), done.
453 Writing objects:
100% (
3317/
3317), done.
454 Total
3317 (delta
2050), reused
3301 (delta
2034)to
457 <h4 id=
"step-3-configuration">Step
3: configuration
</h4>
458 <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">Shaarli configuration
</a> for more details).
</p>
459 <h2 id=
"troubleshooting">Troubleshooting
</h2>
460 <p>If the solutions provided here doesn't work, please open an issue specifying which version you're upgrading from and to.
</p>
461 <h3 id=
"you-must-specify-an-integer-as-a-key">You must specify an integer as a key
</h3>
462 <p>In
<code>v0.8
.1</code> we changed how link keys are handled (from timestamps to incremental integers).
463 Take a look at
<code>data/updates.txt
</code> content.
</p>
464 <h4 id=
"updatestxt-contains-updatemethoddatastoreids"><code>updates.txt
</code> contains
<code>updateMethodDatastoreIds
</code></h4>
465 <p>Try to delete it and refresh your page while being logged in.
</p>
466 <h4 id=
"updatestxt-doesnt-exists-or-doesnt-contain-updatemethoddatastoreids"><code>updates.txt
</code> doesn't exists or doesn't contain
<code>updateMethodDatastoreIds
</code></h4>
468 <li>Create
<code>data/updates.txt
</code> if it doesn't exist.
</li>
469 <li>Paste this string in the update file
<code>;updateMethodRenameDashTags;
</code></li>
470 <li>Login to Shaarli.
</li>
471 <li>Delete the update file.
</li>
479 <div class=
"rst-footer-buttons" role=
"navigation" aria-label=
"footer navigation">
481 <a href=
"../Server-requirements/" class=
"btn btn-neutral float-right" title=
"Server requirements">Next
<span class=
"icon icon-circle-arrow-right"></span></a>
484 <a href=
"../Download-and-Installation/" class=
"btn btn-neutral" title=
"Download and Installation"><span class=
"icon icon-circle-arrow-left"></span> Previous
</a>
491 <div role=
"contentinfo">
492 <!-- Copyright etc -->
496 Built with
<a href=
"http://www.mkdocs.org">MkDocs
</a> using a
<a href=
"https://github.com/snide/sphinx_rtd_theme">theme
</a> provided by
<a href=
"https://readthedocs.org">Read the Docs
</a>.
506 <div class=
"rst-versions" role=
"note" style=
"cursor: pointer">
507 <span class=
"rst-current-version" data-toggle=
"rst-current-version">
509 <a href=
"https://github.com/shaarli/Shaarli" class=
"fa fa-github" style=
"float: left; color: #fcfcfc"> GitHub
</a>
512 <span><a href=
"../Download-and-Installation/" style=
"color: #fcfcfc;">« Previous
</a></span>
515 <span style=
"margin-left: 15px"><a href=
"../Server-requirements/" style=
"color: #fcfcfc">Next
»</a></span>
519 <script src=
"../js/theme.js"></script>