doc/Upgrade-and-migration.md

   1 #Upgrade and migration
   2 ## Preparation
   3 ### Backup your data
   4
   5 Shaarli stores all user data under the `data` directory:
   6 - `data/config.php` - main configuration file
   7 - `data/datastore.php` - bookmarked links
   8 - `data/ipbans.php` - banned IP addresses
   9
  10 See [Shaarli configuration](Shaarli-configuration.html) for more information about Shaarli resources.
  11
  12 It is recommended to backup this repository _before_ starting updating/upgrading Shaarli:
  13 - users with SSH access: copy or archive the directory to a temporary location
  14 - users with FTP access: download a local copy of your Shaarli installation using your favourite client
  15
  16 ### Migrating data from a previous installation
  17 As all user data is kept under `data`, this is the only directory you need to worry about when migrating to a new installation, which corresponds to the following steps:
  18
  19 - backup the `data` directory
  20 - install or update Shaarli:
  21     - fresh installation - see [Download and installation](Download-and-installation.html)
  22     - update - see the following sections
  23 - check or restore the `data` directory
  24
  25 ## Upgrading from release archives
  26 All tagged revisions can be downloaded as tarballs or ZIP archives from the [releases](https://github.com/shaarli/Shaarli/releases) page.[](.html)
  27
  28 We _recommend_ using the releases from the `stable` branch, which are available as:
  29 - gzipped tarball - https://github.com/shaarli/Shaarli/archive/stable.tar.gz
  30 - ZIP archive - https://github.com/shaarli/Shaarli/archive/stable.zip
  31
  32 Once downloaded, extract the archive locally and update your remote installation (e.g. via FTP) -be sure you keep the contents of the `data` directory!
  33
  34 After upgrading, access your fresh Shaarli installation from a web browser; the configuration will then be automatically updated, and new settings added to `data/config.php` (see [Shaarli configuration](Shaarli-configuration.html) for more details).
  35
  36 ## Upgrading with Git
  37 ### Updating a community Shaarli
  38 If you have installed Shaarli from the [community Git repository](Download#clone-with-git-recommended), simply [pull new changes](https://www.git-scm.com/docs/git-pull) from your local clone:[](.html)
  39
  40 ```bash
  41 $ cd /path/to/shaarli
  42 $ git pull
  43
  44 From github.com:shaarli/Shaarli
  45  * branch            master     -> FETCH_HEAD
  46 Updating ebd67c6..521f0e6
  47 Fast-forward
  48  application/Url.php   | 1 +
  49  shaarli_version.php   | 2 +-
  50  tests/Url/UrlTest.php | 1 +
  51  3 files changed, 3 insertions(+), 1 deletion(-)
  52 ```
  53
  54 Shaarli >= `v0.8.x`: install/update third-party PHP dependencies using [Composer](https://getcomposer.org/):[](.html)
  55
  56 ```bash
  57 $ composer update --no-dev
  58
  59 Loading composer repositories with package information
  60 Updating dependencies
  61   - Installing shaarli/netscape-bookmark-parser (v1.0.1)
  62     Downloading: 100%
  63 ```
  64
  65 ### Migrating and upgrading from Sebsauvage's repository
  66 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.[](.html)
  67
  68 The following guide assumes that:
  69 - 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)[](.html)
  70 - the default remote is named `origin` and points to Sebsauvage's repository
  71 - the current branch is `master`
  72     - if you have personal branches containing customizations, you will need to [rebase them](https://git-scm.com/book/en/v2/Git-Branching-Rebasing) 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![](.html)
  73 - the working copy is clean:
  74     - no versioned file has been locally modified
  75     - no untracked files are present
  76
  77 #### Step 0: show repository information
  78 ```bash
  79 $ cd /path/to/shaarli
  80
  81 $ git remote -v
  82 origin  https://github.com/sebsauvage/Shaarli (fetch)
  83 origin  https://github.com/sebsauvage/Shaarli (push)
  84
  85 $ git branch -vv
  86 * master 029f75f [origin/master] Update README.md[](.html)
  87
  88 $ git status
  89 On branch master
  90 Your branch is up-to-date with 'origin/master'.
  91 nothing to commit, working directory clean
  92 ```
  93
  94 #### Step 1: update Git remotes
  95 ```
  96 $ git remote rename origin sebsauvage
  97 $ git remote -v
  98 sebsauvage      https://github.com/sebsauvage/Shaarli (fetch)
  99 sebsauvage      https://github.com/sebsauvage/Shaarli (push)
 100
 101 $ git remote add origin https://github.com/shaarli/Shaarli
 102 $ git fetch origin
 103
 104 remote: Counting objects: 3015, done.
 105 remote: Compressing objects: 100% (19/19), done.
 106 remote: Total 3015 (delta 446), reused 457 (delta 446), pack-reused 2550
 107 Receiving objects: 100% (3015/3015), 2.59 MiB | 918.00 KiB/s, done.
 108 Resolving deltas: 100% (1899/1899), completed with 48 local objects.
 109 From https://github.com/shaarli/Shaarli
 110  * [new branch]      master     -> origin/master[](.html)
 111  * [new branch]      stable     -> origin/stable[](.html)
 112 [...][](.html)
 113  * [new tag]         v0.6.4     -> v0.6.4[](.html)
 114  * [new tag]         v0.7.0     -> v0.7.0[](.html)
 115 ```
 116
 117 #### Step 2: use the stable community branch
 118
 119 ```bash
 120 $ git checkout origin/stable -b stable
 121 Branch stable set up to track remote branch stable from origin.
 122 Switched to a new branch 'stable'
 123
 124 $ git branch -vv
 125   master 029f75f [sebsauvage/master] Update README.md[](.html)
 126 * stable 890afc3 [origin/stable] Merge pull request #509 from ArthurHoaro/v0.6.5[](.html)
 127 ```
 128
 129 Shaarli >= `v0.8.x`: install/update third-party PHP dependencies using [Composer](https://getcomposer.org/):[](.html)
 130
 131 ```bash
 132 $ composer update --no-dev
 133
 134 Loading composer repositories with package information
 135 Updating dependencies
 136   - Installing shaarli/netscape-bookmark-parser (v1.0.1)
 137     Downloading: 100%
 138 ```
 139
 140 Optionally, you can delete information related to the legacy version:
 141
 142 ```bash
 143 $ git branch -D master
 144 Deleted branch master (was 029f75f).
 145
 146 $ git remote remove sebsauvage
 147
 148 $ git remote -v
 149 origin  https://github.com/shaarli/Shaarli (fetch)
 150 origin  https://github.com/shaarli/Shaarli (push)
 151
 152 $ git gc
 153 Counting objects: 3317, done.
 154 Delta compression using up to 8 threads.
 155 Compressing objects: 100% (1237/1237), done.
 156 Writing objects: 100% (3317/3317), done.
 157 Total 3317 (delta 2050), reused 3301 (delta 2034)to
 158 ```
 159
 160 #### Step 3: configuration
 161 After migrating, access your fresh Shaarli installation from a web browser; the configuration will then be automatically updated, and new settings added to `data/config.php` (see [Shaarli configuration](Shaarli-configuration.html) for more details).