doc/md/Upgrade-and-migration.md

   1 ## Preparation
   2
   3 ### Note your current version
   4
   5 If anything goes wrong, it's important for us to know which version you're upgrading from.
   6 The current version is present in the `shaarli_version.php` file.
   7
   8 ### Backup your data
   9
  10 Shaarli stores all user data under the `data` directory:
  11
  12 - `data/config.json.php` (or `data/config.php` for older Shaarli versions) - main configuration file
  13 - `data/datastore.php` - bookmarked links
  14 - `data/ipbans.php` - banned IP addresses
  15 - `data/updates.txt` - contains all automatic update to the configuration and datastore files already run
  16
  17 See [Shaarli configuration](Shaarli-configuration) for more information about Shaarli resources.
  18
  19 It is recommended to backup this repository _before_ starting updating/upgrading Shaarli:
  20
  21 - users with SSH access: copy or archive the directory to a temporary location
  22 - users with FTP access: download a local copy of your Shaarli installation using your favourite client
  23
  24 ### Migrating data from a previous installation
  25
  26 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:
  27
  28 - backup the `data` directory
  29 - install or update Shaarli:
  30     - fresh installation - see [Download and Installation](Download-and-Installation)
  31     - update - see the following sections
  32 - check or restore the `data` directory
  33
  34 ## Recommended : Upgrading from release archives
  35
  36 All tagged revisions can be downloaded as tarballs or ZIP archives from the [releases](https://github.com/shaarli/Shaarli/releases) page.
  37
  38 We recommend that you use the latest release tarball with the `-full` suffix. It contains the dependencies, please read [Download and Installation](Download-and-Installation) for `git` complete instructions.
  39
  40 Once downloaded, extract the archive locally and update your remote installation (e.g. via FTP) -be sure you keep the content of the `data` directory!
  41
  42 If you use translations in gettext mode - meaning you manually changed the default mode -,
  43 reload your web server.
  44
  45 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 `data/config.json.php` (see [Shaarli configuration](Shaarli configuration) for more details).
  46
  47 ## Upgrading with Git
  48
  49 ### Updating a community Shaarli
  50
  51 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:
  52
  53 ```bash
  54 $ cd /path/to/shaarli
  55 $ git pull
  56
  57 From github.com:shaarli/Shaarli
  58  * branch            master     -> FETCH_HEAD
  59 Updating ebd67c6..521f0e6
  60 Fast-forward
  61  application/Url.php   | 1 +
  62  shaarli_version.php   | 2 +-
  63  tests/Url/UrlTest.php | 1 +
  64  3 files changed, 3 insertions(+), 1 deletion(-)
  65 ```
  66
  67 Shaarli >= `v0.8.x`: install/update third-party PHP dependencies using [Composer](https://getcomposer.org/):
  68
  69 ```bash
  70 $ composer install --no-dev
  71
  72 Loading composer repositories with package information
  73 Updating dependencies
  74   - Installing shaarli/netscape-bookmark-parser (v1.0.1)
  75     Downloading: 100%
  76 ```
  77
  78 Shaarli >= `v0.9.2` supports translations:
  79
  80 ```bash
  81 $ make translate
  82 ```
  83
  84 If you use translations in gettext mode, reload your web server.
  85
  86 Shaarli >= `v0.10.0` manages its front-end dependencies with nodejs. You need to install
  87 [yarn](https://yarnpkg.com/lang/en/docs/install/):
  88
  89 ```bash
  90 $ make build_frontend
  91 ```
  92
  93 ### Migrating and upgrading from Sebsauvage's repository
  94
  95 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.
  96
  97 The following guide assumes that:
  98
  99 - 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)
 100 - the default remote is named `origin` and points to Sebsauvage's repository
 101 - the current branch is `master`
 102     - 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!
 103 - the working copy is clean:
 104     - no versioned file has been locally modified
 105     - no untracked files are present
 106
 107 #### Step 0: show repository information
 108
 109 ```bash
 110 $ cd /path/to/shaarli
 111
 112 $ git remote -v
 113 origin  https://github.com/sebsauvage/Shaarli (fetch)
 114 origin  https://github.com/sebsauvage/Shaarli (push)
 115
 116 $ git branch -vv
 117 * master 029f75f [origin/master] Update README.md
 118
 119 $ git status
 120 On branch master
 121 Your branch is up-to-date with 'origin/master'.
 122 nothing to commit, working directory clean
 123 ```
 124
 125 #### Step 1: update Git remotes
 126
 127 ```
 128 $ git remote rename origin sebsauvage
 129 $ git remote -v
 130 sebsauvage      https://github.com/sebsauvage/Shaarli (fetch)
 131 sebsauvage      https://github.com/sebsauvage/Shaarli (push)
 132
 133 $ git remote add origin https://github.com/shaarli/Shaarli
 134 $ git fetch origin
 135
 136 remote: Counting objects: 3015, done.
 137 remote: Compressing objects: 100% (19/19), done.
 138 remote: Total 3015 (delta 446), reused 457 (delta 446), pack-reused 2550
 139 Receiving objects: 100% (3015/3015), 2.59 MiB | 918.00 KiB/s, done.
 140 Resolving deltas: 100% (1899/1899), completed with 48 local objects.
 141 From https://github.com/shaarli/Shaarli
 142  * [new branch]      master     -> origin/master
 143  * [new branch]      stable     -> origin/stable
 144 [...]
 145  * [new tag]         v0.6.4     -> v0.6.4
 146  * [new tag]         v0.7.0     -> v0.7.0
 147 ```
 148
 149 #### Step 2: use the stable community branch
 150
 151 ```bash
 152 $ git checkout origin/stable -b stable
 153 Branch stable set up to track remote branch stable from origin.
 154 Switched to a new branch 'stable'
 155
 156 $ git branch -vv
 157   master 029f75f [sebsauvage/master] Update README.md
 158 * stable 890afc3 [origin/stable] Merge pull request #509 from ArthurHoaro/v0.6.5
 159 ```
 160
 161 Shaarli >= `v0.8.x`: install/update third-party PHP dependencies using [Composer](https://getcomposer.org/):
 162
 163 ```bash
 164 $ composer install --no-dev
 165
 166 Loading composer repositories with package information
 167 Updating dependencies
 168   - Installing shaarli/netscape-bookmark-parser (v1.0.1)
 169     Downloading: 100%
 170 ```
 171
 172 Shaarli >= `v0.9.2` supports translations:
 173
 174 ```bash
 175 $ make translate
 176 ```
 177
 178 If you use translations in gettext mode, reload your web server.
 179
 180 Shaarli >= `v0.10.0` manages its front-end dependencies with nodejs. You need to install
 181 [yarn](https://yarnpkg.com/lang/en/docs/install/):
 182
 183 ```bash
 184 $ make build_frontend
 185 ```
 186
 187 Optionally, you can delete information related to the legacy version:
 188
 189 ```bash
 190 $ git branch -D master
 191 Deleted branch master (was 029f75f).
 192
 193 $ git remote remove sebsauvage
 194
 195 $ git remote -v
 196 origin  https://github.com/shaarli/Shaarli (fetch)
 197 origin  https://github.com/shaarli/Shaarli (push)
 198
 199 $ git gc
 200 Counting objects: 3317, done.
 201 Delta compression using up to 8 threads.
 202 Compressing objects: 100% (1237/1237), done.
 203 Writing objects: 100% (3317/3317), done.
 204 Total 3317 (delta 2050), reused 3301 (delta 2034)to
 205 ```
 206
 207 #### Step 3: configuration
 208
 209 After migrating, access your fresh Shaarli installation from a web browser; the
 210 configuration will then be automatically updated, and new settings added to
 211 `data/config.json.php` (see [Shaarli configuration](Shaarli-configuration) for more
 212 details).
 213
 214 ## Troubleshooting
 215
 216 If the solutions provided here don't work, please open an issue specifying which version you're upgrading from and to.
 217
 218 ### You must specify an integer as a key
 219
 220 In `v0.8.1` we changed how link keys are handled (from timestamps to incremental integers).
 221 Take a look at `data/updates.txt` content.
 222
 223 #### `updates.txt` contains `updateMethodDatastoreIds`
 224
 225 Try to delete it and refresh your page while being logged in.
 226
 227 #### `updates.txt` doesn't exist or doesn't contain `updateMethodDatastoreIds`
 228
 229 1. Create `data/updates.txt` if it doesn't exist
 230 2. Paste this string in the update file `;updateMethodRenameDashTags;`
 231 3. Login to Shaarli
 232 4. Delete the update file
 233 5. Refresh