]>
Commit | Line | Data |
---|---|---|
fdf88d19 | 1 | ## Preparation |
53ed6d7d | 2 | |
b230bf20 A |
3 | ### Note your current version |
4 | ||
48679a15 | 5 | If anything goes wrong, it's important for us to know which version you're upgrading from. |
6c4cc14e | 6 | The current version is present in the `shaarli_version.php` file. |
b230bf20 | 7 | |
fdf88d19 A |
8 | ### Backup your data |
9 | ||
10 | Shaarli stores all user data under the `data` directory: | |
43ad7c8e | 11 | |
48679a15 | 12 | - `data/config.json.php` (or `data/config.php` for older Shaarli versions) - main configuration file |
fdf88d19 A |
13 | - `data/datastore.php` - bookmarked links |
14 | - `data/ipbans.php` - banned IP addresses | |
b230bf20 | 15 | - `data/updates.txt` - contains all automatic update to the configuration and datastore files already run |
fdf88d19 | 16 | |
ba624567 | 17 | See [Shaarli configuration](Shaarli-configuration) for more information about Shaarli resources. |
fdf88d19 A |
18 | |
19 | It is recommended to backup this repository _before_ starting updating/upgrading Shaarli: | |
43ad7c8e | 20 | |
fdf88d19 A |
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 | |
53ed6d7d | 25 | |
fdf88d19 A |
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: | |
3028a84c | 30 | - fresh installation - see [Download and Installation](Download-and-Installation) |
fdf88d19 A |
31 | - update - see the following sections |
32 | - check or restore the `data` directory | |
33 | ||
b230bf20 | 34 | ## Recommended : Upgrading from release archives |
fdf88d19 | 35 | |
53ed6d7d | 36 | All tagged revisions can be downloaded as tarballs or ZIP archives from the [releases](https://github.com/shaarli/Shaarli/releases) page. |
37 | ||
f39b1242 | 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. |
fdf88d19 | 39 | |
b230bf20 | 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! |
fdf88d19 | 41 | |
48679a15 | 42 | If you use translations in gettext mode - meaning you manually changed the default mode -, |
1a47014f A |
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). | |
fdf88d19 A |
46 | |
47 | ## Upgrading with Git | |
53ed6d7d | 48 | |
fdf88d19 | 49 | ### Updating a community Shaarli |
53ed6d7d | 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: | |
fdf88d19 A |
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 | ||
53ed6d7d | 67 | Shaarli >= `v0.8.x`: install/update third-party PHP dependencies using [Composer](https://getcomposer.org/): |
fdf88d19 A |
68 | |
69 | ```bash | |
b230bf20 | 70 | $ composer install --no-dev |
fdf88d19 A |
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 | ||
1a47014f A |
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 | ||
d7eb06bd A |
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 | ||
fdf88d19 | 93 | ### Migrating and upgrading from Sebsauvage's repository |
53ed6d7d | 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. | |
fdf88d19 A |
96 | |
97 | The following guide assumes that: | |
43ad7c8e | 98 | |
53ed6d7d | 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) |
fdf88d19 A |
100 | - the default remote is named `origin` and points to Sebsauvage's repository |
101 | - the current branch is `master` | |
53ed6d7d | 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! |
fdf88d19 A |
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 | |
53ed6d7d | 108 | |
fdf88d19 A |
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 | |
53ed6d7d | 117 | * master 029f75f [origin/master] Update README.md |
fdf88d19 A |
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 | |
53ed6d7d | 126 | |
fdf88d19 A |
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 | |
53ed6d7d | 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 | |
fdf88d19 A |
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 | |
53ed6d7d | 157 | master 029f75f [sebsauvage/master] Update README.md |
158 | * stable 890afc3 [origin/stable] Merge pull request #509 from ArthurHoaro/v0.6.5 | |
fdf88d19 A |
159 | ``` |
160 | ||
53ed6d7d | 161 | Shaarli >= `v0.8.x`: install/update third-party PHP dependencies using [Composer](https://getcomposer.org/): |
fdf88d19 A |
162 | |
163 | ```bash | |
b230bf20 | 164 | $ composer install --no-dev |
fdf88d19 A |
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 | ||
1a47014f A |
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 | ||
d7eb06bd A |
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 | ||
fdf88d19 A |
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 | |
53ed6d7d | 208 | |
48679a15 V |
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). | |
b230bf20 A |
213 | |
214 | ## Troubleshooting | |
215 | ||
43ad7c8e | 216 | If the solutions provided here don't work, please open an issue specifying which version you're upgrading from and to. |
b230bf20 A |
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 | ||
43ad7c8e | 227 | #### `updates.txt` doesn't exist or doesn't contain `updateMethodDatastoreIds` |
b230bf20 | 228 | |
43ad7c8e V |
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 |