aboutsummaryrefslogtreecommitdiffhomepage
path: root/doc/md/Upgrade-and-migration.md
diff options
context:
space:
mode:
authornodiscc <nodiscc@gmail.com>2020-09-12 12:38:05 +0000
committerGitHub <noreply@github.com>2020-09-12 12:38:05 +0000
commite809908f9e593b2cec11f72849caa1dae6394451 (patch)
treeb26f77ec59b7c25800599d751212db72cfc65870 /doc/md/Upgrade-and-migration.md
parent6128ab6a55430a2b705be31ff417c0c552a0db1f (diff)
parent97870f35121bed42ac126652d81bc43416b44356 (diff)
downloadShaarli-e809908f9e593b2cec11f72849caa1dae6394451.tar.gz
Shaarli-e809908f9e593b2cec11f72849caa1dae6394451.tar.zst
Shaarli-e809908f9e593b2cec11f72849caa1dae6394451.zip
Merge pull request #1389 from shaarli/doc-rework-setup
doc: rework installation/setup guides, general refactoring
Diffstat (limited to 'doc/md/Upgrade-and-migration.md')
-rw-r--r--doc/md/Upgrade-and-migration.md144
1 files changed, 57 insertions, 87 deletions
diff --git a/doc/md/Upgrade-and-migration.md b/doc/md/Upgrade-and-migration.md
index d5682a34..bfef3e8c 100644
--- a/doc/md/Upgrade-and-migration.md
+++ b/doc/md/Upgrade-and-migration.md
@@ -1,96 +1,83 @@
1## Preparation 1# Upgrade and migration
2 2
3### Note your current version 3## Note your current version
4 4
5If anything goes wrong, it's important for us to know which version you're upgrading from. 5If anything goes wrong, it's important for us to know which version you're upgrading from.
6The current version is present in the `shaarli_version.php` file. 6The current version is present in the `shaarli_version.php` file.
7 7
8### Backup your data
9 8
10Shaarli stores all user data under the `data` directory: 9## Backup your data
11 10
12- `data/config.json.php` (or `data/config.php` for older Shaarli versions) - main configuration file 11Shaarli 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.
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 12
17See [Shaarli configuration](Shaarli-configuration) for more information about Shaarli resources. 13```bash
18 14sudo cp -r /var/www/shaarli.mydomain.org/data ~/shaarli-data-backup
19It is recommended to backup this repository _before_ starting updating/upgrading Shaarli: 15```
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 16
24### Migrating data from a previous installation 17## Upgrading from ZIP archives
25 18
26As 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: 19If you installed Shaarli from a [release ZIP archive](Installation.md#from-release-zip):
27 20
28- backup the `data` directory 21```bash
29- install or update Shaarli: 22# Download the archive to the server, and extract it
30 - fresh installation - see [Download and Installation](Download-and-Installation) 23cd ~
31 - update - see the following sections 24wget https://github.com/shaarli/Shaarli/releases/download/v0.X.Y/shaarli-v0.X.Y-full.zip
32- check or restore the `data` directory 25unzip shaarli-v0.X.Y-full.zip
33 26
34## Recommended : Upgrading from release archives 27# overwrite your Shaarli installation with the new release **All data will be lost, see _Backup your data_ above.**
28sudo rsync -avP --delete Shaarli/ /var/www/shaarli.mydomain.org/
35 29
36All tagged revisions can be downloaded as tarballs or ZIP archives from the [releases](https://github.com/shaarli/Shaarli/releases) page. 30# restore file permissions as described on the installation page
31sudo chown -R root:www-data /var/www/shaarli.mydomain.org
32sudo chmod -R g+rX /var/www/shaarli.mydomain.org
33sudo chmod -R g+rwX /var/www/shaarli.mydomain.org/{cache/,data/,pagecache/,tmp/}
37 34
38We 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. 35# restore backups of the data directory
36sudo cp -r ~/shaarli-data-backup/* /var/www/shaarli.mydomain.org/data/
39 37
40Once downloaded, extract the archive locally and update your remote installation (e.g. via FTP) -be sure you keep the content of the `data` directory! 38# If you use gettext mode for translations (not the default), reload your web server.
39sudo systemctl restart apache2
40sudo systemctl restart nginx
41```
41 42
42If you use translations in gettext mode - meaning you manually changed the default mode -, 43If 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.
43reload your web server.
44 44
45After 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). 45Access 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 46
47## Upgrading with Git
48 47
49### Updating a community Shaarli 48## Upgrading from Git
50 49
51If 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: 50If you have installed Shaarli [from sources](Installation.md#from-sources):
52 51
53```bash 52```bash
54$ cd /path/to/shaarli 53# pull new changes from your local clone
55$ git pull 54cd /var/www/shaarli.mydomain.org/
56 55sudo git pull
57From github.com:shaarli/Shaarli
58 * branch master -> FETCH_HEAD
59Updating ebd67c6..521f0e6
60Fast-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 56
67Shaarli >= `v0.8.x`: install/update third-party PHP dependencies using [Composer](https://getcomposer.org/): 57# update PHP dependencies (Shaarli >= v0.8)
58sudo composer install --no-dev
68 59
69```bash 60# update translations (Shaarli >= v0.9.2)
70$ composer install --no-dev 61sudo make translate
71 62
72Loading composer repositories with package information 63# If you use translations in gettext mode (not the default), reload your web server.
73Updating dependencies 64sudo systemctl reload apache
74 - Installing shaarli/netscape-bookmark-parser (v1.0.1) 65sudo systemctl reload nginx
75 Downloading: 100%
76```
77 66
78Shaarli >= `v0.9.2` supports translations: 67# update front-end dependencies (Shaarli >= v0.10.0)
68sudo make build_frontend
79 69
80```bash 70# restore file permissions as described on the installation page
81$ make translate 71sudo chown -R root:www-data /var/www/shaarli.mydomain.org
82``` 72sudo chmod -R g+rX /var/www/shaarli.mydomain.org
73sudo chmod -R g+rwX /var/www/shaarli.mydomain.org/{cache/,data/,pagecache/,tmp/}
74```
83 75
84If you use translations in gettext mode, reload your web server. 76Access 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).
85 77
86Shaarli >= `v0.10.0` manages its front-end dependencies with nodejs. You need to install 78---------------------------------------------------------------
87[yarn](https://yarnpkg.com/lang/en/docs/install/):
88 79
89```bash 80## Migrating and upgrading from Sebsauvage's repository
90$ make build_frontend
91```
92
93### Migrating and upgrading from Sebsauvage's repository
94 81
95If 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. 82If 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 83
@@ -104,7 +91,7 @@ The following guide assumes that:
104 - no versioned file has been locally modified 91 - no versioned file has been locally modified
105 - no untracked files are present 92 - no untracked files are present
106 93
107#### Step 0: show repository information 94### Step 0: show repository information
108 95
109```bash 96```bash
110$ cd /path/to/shaarli 97$ cd /path/to/shaarli
@@ -122,7 +109,7 @@ Your branch is up-to-date with 'origin/master'.
122nothing to commit, working directory clean 109nothing to commit, working directory clean
123``` 110```
124 111
125#### Step 1: update Git remotes 112### Step 1: update Git remotes
126 113
127``` 114```
128$ git remote rename origin sebsauvage 115$ git remote rename origin sebsauvage
@@ -146,7 +133,7 @@ From https://github.com/shaarli/Shaarli
146 * [new tag] v0.7.0 -> v0.7.0 133 * [new tag] v0.7.0 -> v0.7.0
147``` 134```
148 135
149#### Step 2: use the stable community branch 136### Step 2: use the stable community branch
150 137
151```bash 138```bash
152$ git checkout origin/stable -b stable 139$ git checkout origin/stable -b stable
@@ -177,8 +164,7 @@ $ make translate
177 164
178If you use translations in gettext mode, reload your web server. 165If you use translations in gettext mode, reload your web server.
179 166
180Shaarli >= `v0.10.0` manages its front-end dependencies with nodejs. You need to install 167Shaarli >= `v0.10.0` manages its front-end dependencies with nodejs. You need to install [yarn](https://yarnpkg.com/lang/en/docs/install/):
181[yarn](https://yarnpkg.com/lang/en/docs/install/):
182 168
183```bash 169```bash
184$ make build_frontend 170$ make build_frontend
@@ -204,30 +190,14 @@ Writing objects: 100% (3317/3317), done.
204Total 3317 (delta 2050), reused 3301 (delta 2034)to 190Total 3317 (delta 2050), reused 3301 (delta 2034)to
205``` 191```
206 192
207#### Step 3: configuration 193### Step 3: configuration
208 194
209After migrating, access your fresh Shaarli installation from a web browser; the 195After migrating, access your fresh Shaarli installation from a web browser; the
210configuration will then be automatically updated, and new settings added to 196configuration will then be automatically updated, and new settings added to
211`data/config.json.php` (see [Shaarli configuration](Shaarli-configuration) for more 197`data/config.json.php` (see [Shaarli configuration](Shaarli-configuration.md) for more
212details). 198details).
213 199
214## Troubleshooting 200## Troubleshooting
215 201
216If the solutions provided here don't work, please open an issue specifying which version you're upgrading from and to. 202If 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.
217
218### You must specify an integer as a key
219
220In `v0.8.1` we changed how link keys are handled (from timestamps to incremental integers).
221Take a look at `data/updates.txt` content.
222
223#### `updates.txt` contains `updateMethodDatastoreIds`
224
225Try to delete it and refresh your page while being logged in.
226
227#### `updates.txt` doesn't exist or doesn't contain `updateMethodDatastoreIds`
228 203
2291. Create `data/updates.txt` if it doesn't exist
2302. Paste this string in the update file `;updateMethodRenameDashTags;`
2313. Login to Shaarli
2324. Delete the update file
2335. Refresh