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