doc/md/Upgrade-and-migration.md

   1 # Upgrade and migration
   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
   9 ## Backup your data
  10
  11 Shaarli stores all user data and [configuration](Shaarli-configuration.md) under the `data` directory. [Backup](Backup-and-restore.md) this repository _before_ upgrading Shaarli. You will need to restore it after the following upgrade steps.
  12
  13 ```bash
  14 sudo cp -r /var/www/shaarli.mydomain.org/data ~/shaarli-data-backup
  15 ```
  16
  17 ## Upgrading from ZIP archives
  18
  19 If you installed Shaarli from a [release ZIP archive](Installation.md#from-release-zip):
  20
  21 ```bash
  22 # Download the archive to the server, and extract it
  23 cd ~
  24 wget https://github.com/shaarli/Shaarli/releases/download/v0.X.Y/shaarli-v0.X.Y-full.zip
  25 unzip shaarli-v0.X.Y-full.zip
  26
  27 # overwrite your Shaarli installation with the new release **All data will be lost, see _Backup your data_ above.**
  28 sudo rsync -avP --delete Shaarli/ /var/www/shaarli.mydomain.org/
  29
  30 # restore file permissions as described on the installation page
  31 sudo chown -R root:www-data /var/www/shaarli.mydomain.org
  32 sudo chmod -R u=rwX /var/www/shaarli.mydomain.org
  33 sudo chmod -R g+rX /var/www/shaarli.mydomain.org/{index.php,application/,plugins/,inc/}
  34 sudo chmod -R g+rwX /var/www/shaarli.mydomain.org/{cache/,data/,pagecache/,tmp/}
  35
  36 # restore backups of the data directory
  37 sudo cp -r ~/shaarli-data-backup/* /var/www/shaarli.mydomain.org/data/
  38
  39 # If you use gettext mode for translations (not the default), reload your web server.
  40 sudo systemctl restart apache2
  41 sudo systemctl restart nginx
  42 ```
  43
  44 If you don't have shell access (eg. on shared hosting), backup the shaarli data directory, download the ZIP archive locally, extract it, upload it to the server using file transfer, and restore the data directory backup.
  45
  46 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.md) for more details).
  47
  48
  49 ## Upgrading from Git
  50
  51 If you have installed Shaarli [from sources](Installation.md#from-sources):
  52
  53 ```bash
  54 # pull new changes from your local clone
  55 cd /var/www/shaarli.mydomain.org/
  56 sudo git pull
  57
  58 # update PHP dependencies (Shaarli >= v0.8)
  59 sudo composer install --no-dev
  60
  61 # update translations (Shaarli >= v0.9.2)
  62 sudo make translate
  63
  64 # If you use translations in gettext mode (not the default), reload your web server.
  65 sudo systemctl reload apache
  66 sudo systemctl reload nginx
  67
  68 # update front-end dependencies (Shaarli >= v0.10.0)
  69 sudo make build_frontend
  70
  71 # restore file permissions as described on the installation page
  72 sudo chown -R root:www-data /var/www/shaarli.mydomain.org
  73 sudo chmod -R u=rwX /var/www/shaarli.mydomain.org
  74 sudo chmod -R g+rX /var/www/shaarli.mydomain.org/{index.php,application/,plugins/,inc/}
  75 sudo chmod -R g+rwX /var/www/shaarli.mydomain.org/{cache/,data/,pagecache/,tmp/}
  76 ```
  77
  78 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.md) for more details).
  79
  80 ---------------------------------------------------------------
  81
  82 ## Migrating and upgrading from Sebsauvage's repository
  83
  84 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.
  85
  86 The following guide assumes that:
  87
  88 - 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)
  89 - the default remote is named `origin` and points to Sebsauvage's repository
  90 - the current branch is `master`
  91     - 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!
  92 - the working copy is clean:
  93     - no versioned file has been locally modified
  94     - no untracked files are present
  95
  96 ### Step 0: show repository information
  97
  98 ```bash
  99 $ cd /path/to/shaarli
 100
 101 $ git remote -v
 102 origin  https://github.com/sebsauvage/Shaarli (fetch)
 103 origin  https://github.com/sebsauvage/Shaarli (push)
 104
 105 $ git branch -vv
 106 * master 029f75f [origin/master] Update README.md
 107
 108 $ git status
 109 On branch master
 110 Your branch is up-to-date with 'origin/master'.
 111 nothing to commit, working directory clean
 112 ```
 113
 114 ### Step 1: update Git remotes
 115
 116 ```
 117 $ git remote rename origin sebsauvage
 118 $ git remote -v
 119 sebsauvage      https://github.com/sebsauvage/Shaarli (fetch)
 120 sebsauvage      https://github.com/sebsauvage/Shaarli (push)
 121
 122 $ git remote add origin https://github.com/shaarli/Shaarli
 123 $ git fetch origin
 124
 125 remote: Counting objects: 3015, done.
 126 remote: Compressing objects: 100% (19/19), done.
 127 remote: Total 3015 (delta 446), reused 457 (delta 446), pack-reused 2550
 128 Receiving objects: 100% (3015/3015), 2.59 MiB | 918.00 KiB/s, done.
 129 Resolving deltas: 100% (1899/1899), completed with 48 local objects.
 130 From https://github.com/shaarli/Shaarli
 131  * [new branch]      master     -> origin/master
 132  * [new branch]      stable     -> origin/stable
 133 [...]
 134  * [new tag]         v0.6.4     -> v0.6.4
 135  * [new tag]         v0.7.0     -> v0.7.0
 136 ```
 137
 138 ### Step 2: use the stable community branch
 139
 140 ```bash
 141 $ git checkout origin/stable -b stable
 142 Branch stable set up to track remote branch stable from origin.
 143 Switched to a new branch 'stable'
 144
 145 $ git branch -vv
 146   master 029f75f [sebsauvage/master] Update README.md
 147 * stable 890afc3 [origin/stable] Merge pull request #509 from ArthurHoaro/v0.6.5
 148 ```
 149
 150 Shaarli >= `v0.8.x`: install/update third-party PHP dependencies using [Composer](https://getcomposer.org/):
 151
 152 ```bash
 153 $ composer install --no-dev
 154
 155 Loading composer repositories with package information
 156 Updating dependencies
 157   - Installing shaarli/netscape-bookmark-parser (v1.0.1)
 158     Downloading: 100%
 159 ```
 160
 161 Shaarli >= `v0.9.2` supports translations:
 162
 163 ```bash
 164 $ make translate
 165 ```
 166
 167 If you use translations in gettext mode, reload your web server.
 168
 169 Shaarli >= `v0.10.0` manages its front-end dependencies with nodejs. You need to install [yarn](https://yarnpkg.com/lang/en/docs/install/):
 170
 171 ```bash
 172 $ make build_frontend
 173 ```
 174
 175 Optionally, you can delete information related to the legacy version:
 176
 177 ```bash
 178 $ git branch -D master
 179 Deleted branch master (was 029f75f).
 180
 181 $ git remote remove sebsauvage
 182
 183 $ git remote -v
 184 origin  https://github.com/shaarli/Shaarli (fetch)
 185 origin  https://github.com/shaarli/Shaarli (push)
 186
 187 $ git gc
 188 Counting objects: 3317, done.
 189 Delta compression using up to 8 threads.
 190 Compressing objects: 100% (1237/1237), done.
 191 Writing objects: 100% (3317/3317), done.
 192 Total 3317 (delta 2050), reused 3301 (delta 2034)to
 193 ```
 194
 195 ### Step 3: configuration
 196
 197 After migrating, access your fresh Shaarli installation from a web browser; the
 198 configuration will then be automatically updated, and new settings added to
 199 `data/config.json.php` (see [Shaarli configuration](Shaarli-configuration.md) for more
 200 details).
 201
 202 ## Troubleshooting
 203
 204 If the solutions provided here don't work, see [Troubleshooting](Troubleshooting.md) and/or open an issue specifying which version you're upgrading from and to.
 205