diff options
author | ArthurHoaro <arthur@hoa.ro> | 2018-07-28 11:07:55 +0200 |
---|---|---|
committer | ArthurHoaro <arthur@hoa.ro> | 2018-07-28 11:07:55 +0200 |
commit | 83faedadff76c5bdca036f39f13943f63b27e164 (patch) | |
tree | 6f44cede16ec6a60f10b9699e211e0818f06d2c8 /doc/md/Upgrade-and-migration.md | |
parent | 1d9eb22a3df85b67fe6652c0876cd7382c2fb525 (diff) | |
parent | 658988f3aeba7a5a938783249ccf2765251e5597 (diff) | |
download | Shaarli-83faedadff76c5bdca036f39f13943f63b27e164.tar.gz Shaarli-83faedadff76c5bdca036f39f13943f63b27e164.tar.zst Shaarli-83faedadff76c5bdca036f39f13943f63b27e164.zip |
Merge tag 'v0.9.7' into stable
Release v0.9.7
Diffstat (limited to 'doc/md/Upgrade-and-migration.md')
-rw-r--r-- | doc/md/Upgrade-and-migration.md | 216 |
1 files changed, 216 insertions, 0 deletions
diff --git a/doc/md/Upgrade-and-migration.md b/doc/md/Upgrade-and-migration.md new file mode 100644 index 00000000..1dc07339 --- /dev/null +++ b/doc/md/Upgrade-and-migration.md | |||
@@ -0,0 +1,216 @@ | |||
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 `version.php` file. | ||
7 | |||
8 | ### Backup your data | ||
9 | |||
10 | Shaarli stores all user data under the `data` directory: | ||
11 | |||
12 | - `data/config.php` - 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 | ### Migrating and upgrading from Sebsauvage's repository | ||
87 | |||
88 | 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. | ||
89 | |||
90 | The following guide assumes that: | ||
91 | |||
92 | - 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) | ||
93 | - the default remote is named `origin` and points to Sebsauvage's repository | ||
94 | - the current branch is `master` | ||
95 | - 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! | ||
96 | - the working copy is clean: | ||
97 | - no versioned file has been locally modified | ||
98 | - no untracked files are present | ||
99 | |||
100 | #### Step 0: show repository information | ||
101 | |||
102 | ```bash | ||
103 | $ cd /path/to/shaarli | ||
104 | |||
105 | $ git remote -v | ||
106 | origin https://github.com/sebsauvage/Shaarli (fetch) | ||
107 | origin https://github.com/sebsauvage/Shaarli (push) | ||
108 | |||
109 | $ git branch -vv | ||
110 | * master 029f75f [origin/master] Update README.md | ||
111 | |||
112 | $ git status | ||
113 | On branch master | ||
114 | Your branch is up-to-date with 'origin/master'. | ||
115 | nothing to commit, working directory clean | ||
116 | ``` | ||
117 | |||
118 | #### Step 1: update Git remotes | ||
119 | |||
120 | ``` | ||
121 | $ git remote rename origin sebsauvage | ||
122 | $ git remote -v | ||
123 | sebsauvage https://github.com/sebsauvage/Shaarli (fetch) | ||
124 | sebsauvage https://github.com/sebsauvage/Shaarli (push) | ||
125 | |||
126 | $ git remote add origin https://github.com/shaarli/Shaarli | ||
127 | $ git fetch origin | ||
128 | |||
129 | remote: Counting objects: 3015, done. | ||
130 | remote: Compressing objects: 100% (19/19), done. | ||
131 | remote: Total 3015 (delta 446), reused 457 (delta 446), pack-reused 2550 | ||
132 | Receiving objects: 100% (3015/3015), 2.59 MiB | 918.00 KiB/s, done. | ||
133 | Resolving deltas: 100% (1899/1899), completed with 48 local objects. | ||
134 | From https://github.com/shaarli/Shaarli | ||
135 | * [new branch] master -> origin/master | ||
136 | * [new branch] stable -> origin/stable | ||
137 | [...] | ||
138 | * [new tag] v0.6.4 -> v0.6.4 | ||
139 | * [new tag] v0.7.0 -> v0.7.0 | ||
140 | ``` | ||
141 | |||
142 | #### Step 2: use the stable community branch | ||
143 | |||
144 | ```bash | ||
145 | $ git checkout origin/stable -b stable | ||
146 | Branch stable set up to track remote branch stable from origin. | ||
147 | Switched to a new branch 'stable' | ||
148 | |||
149 | $ git branch -vv | ||
150 | master 029f75f [sebsauvage/master] Update README.md | ||
151 | * stable 890afc3 [origin/stable] Merge pull request #509 from ArthurHoaro/v0.6.5 | ||
152 | ``` | ||
153 | |||
154 | Shaarli >= `v0.8.x`: install/update third-party PHP dependencies using [Composer](https://getcomposer.org/): | ||
155 | |||
156 | ```bash | ||
157 | $ composer install --no-dev | ||
158 | |||
159 | Loading composer repositories with package information | ||
160 | Updating dependencies | ||
161 | - Installing shaarli/netscape-bookmark-parser (v1.0.1) | ||
162 | Downloading: 100% | ||
163 | ``` | ||
164 | |||
165 | Shaarli >= `v0.9.2` supports translations: | ||
166 | |||
167 | ```bash | ||
168 | $ make translate | ||
169 | ``` | ||
170 | |||
171 | If you use translations in gettext mode, reload your web server. | ||
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 configuration will then be automatically updated, and new settings added to `data/config.php` (see [Shaarli configuration](Shaarli-configuration) for more details). | ||
196 | |||
197 | ## Troubleshooting | ||
198 | |||
199 | If the solutions provided here don't work, please open an issue specifying which version you're upgrading from and to. | ||
200 | |||
201 | ### You must specify an integer as a key | ||
202 | |||
203 | In `v0.8.1` we changed how link keys are handled (from timestamps to incremental integers). | ||
204 | Take a look at `data/updates.txt` content. | ||
205 | |||
206 | #### `updates.txt` contains `updateMethodDatastoreIds` | ||
207 | |||
208 | Try to delete it and refresh your page while being logged in. | ||
209 | |||
210 | #### `updates.txt` doesn't exist or doesn't contain `updateMethodDatastoreIds` | ||
211 | |||
212 | 1. Create `data/updates.txt` if it doesn't exist | ||
213 | 2. Paste this string in the update file `;updateMethodRenameDashTags;` | ||
214 | 3. Login to Shaarli | ||
215 | 4. Delete the update file | ||
216 | 5. Refresh | ||