aboutsummaryrefslogtreecommitdiffhomepage
path: root/doc/Upgrade-and-migration.md
diff options
context:
space:
mode:
Diffstat (limited to 'doc/Upgrade-and-migration.md')
-rw-r--r--doc/Upgrade-and-migration.md161
1 files changed, 161 insertions, 0 deletions
diff --git a/doc/Upgrade-and-migration.md b/doc/Upgrade-and-migration.md
new file mode 100644
index 00000000..0bc33824
--- /dev/null
+++ b/doc/Upgrade-and-migration.md
@@ -0,0 +1,161 @@
1#Upgrade and migration
2## Preparation
3### Backup your data
4
5Shaarli stores all user data under the `data` directory:
6- `data/config.php` - main configuration file
7- `data/datastore.php` - bookmarked links
8- `data/ipbans.php` - banned IP addresses
9
10See [Shaarli configuration](Shaarli-configuration.html) for more information about Shaarli resources.
11
12It is recommended to backup this repository _before_ starting updating/upgrading Shaarli:
13- users with SSH access: copy or archive the directory to a temporary location
14- users with FTP access: download a local copy of your Shaarli installation using your favourite client
15
16### Migrating data from a previous installation
17As 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:
18
19- backup the `data` directory
20- install or update Shaarli:
21 - fresh installation - see [Download and installation](Download-and-installation.html)
22 - update - see the following sections
23- check or restore the `data` directory
24
25## Upgrading from release archives
26All tagged revisions can be downloaded as tarballs or ZIP archives from the [releases](https://github.com/shaarli/Shaarli/releases) page.[](.html)
27
28We _recommend_ using the releases from the `stable` branch, which are available as:
29- gzipped tarball - https://github.com/shaarli/Shaarli/archive/stable.tar.gz
30- ZIP archive - https://github.com/shaarli/Shaarli/archive/stable.zip
31
32Once downloaded, extract the archive locally and update your remote installation (e.g. via FTP) -be sure you keep the contents of the `data` directory!
33
34After upgrading, 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.html) for more details).
35
36## Upgrading with Git
37### Updating a community Shaarli
38If 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:[](.html)
39
40```bash
41$ cd /path/to/shaarli
42$ git pull
43
44From github.com:shaarli/Shaarli
45 * branch master -> FETCH_HEAD
46Updating ebd67c6..521f0e6
47Fast-forward
48 application/Url.php | 1 +
49 shaarli_version.php | 2 +-
50 tests/Url/UrlTest.php | 1 +
51 3 files changed, 3 insertions(+), 1 deletion(-)
52```
53
54Shaarli >= `v0.8.x`: install/update third-party PHP dependencies using [Composer](https://getcomposer.org/):[](.html)
55
56```bash
57$ composer update --no-dev
58
59Loading composer repositories with package information
60Updating dependencies
61 - Installing shaarli/netscape-bookmark-parser (v1.0.1)
62 Downloading: 100%
63```
64
65### Migrating and upgrading from Sebsauvage's repository
66If 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.[](.html)
67
68The following guide assumes that:
69- 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)[](.html)
70- the default remote is named `origin` and points to Sebsauvage's repository
71- the current branch is `master`
72 - 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![](.html)
73- the working copy is clean:
74 - no versioned file has been locally modified
75 - no untracked files are present
76
77#### Step 0: show repository information
78```bash
79$ cd /path/to/shaarli
80
81$ git remote -v
82origin https://github.com/sebsauvage/Shaarli (fetch)
83origin https://github.com/sebsauvage/Shaarli (push)
84
85$ git branch -vv
86* master 029f75f [origin/master] Update README.md[](.html)
87
88$ git status
89On branch master
90Your branch is up-to-date with 'origin/master'.
91nothing to commit, working directory clean
92```
93
94#### Step 1: update Git remotes
95```
96$ git remote rename origin sebsauvage
97$ git remote -v
98sebsauvage https://github.com/sebsauvage/Shaarli (fetch)
99sebsauvage https://github.com/sebsauvage/Shaarli (push)
100
101$ git remote add origin https://github.com/shaarli/Shaarli
102$ git fetch origin
103
104remote: Counting objects: 3015, done.
105remote: Compressing objects: 100% (19/19), done.
106remote: Total 3015 (delta 446), reused 457 (delta 446), pack-reused 2550
107Receiving objects: 100% (3015/3015), 2.59 MiB | 918.00 KiB/s, done.
108Resolving deltas: 100% (1899/1899), completed with 48 local objects.
109From https://github.com/shaarli/Shaarli
110 * [new branch] master -> origin/master[](.html)
111 * [new branch] stable -> origin/stable[](.html)
112[...][](.html)
113 * [new tag] v0.6.4 -> v0.6.4[](.html)
114 * [new tag] v0.7.0 -> v0.7.0[](.html)
115```
116
117#### Step 2: use the stable community branch
118
119```bash
120$ git checkout origin/stable -b stable
121Branch stable set up to track remote branch stable from origin.
122Switched to a new branch 'stable'
123
124$ git branch -vv
125 master 029f75f [sebsauvage/master] Update README.md[](.html)
126* stable 890afc3 [origin/stable] Merge pull request #509 from ArthurHoaro/v0.6.5[](.html)
127```
128
129Shaarli >= `v0.8.x`: install/update third-party PHP dependencies using [Composer](https://getcomposer.org/):[](.html)
130
131```bash
132$ composer update --no-dev
133
134Loading composer repositories with package information
135Updating dependencies
136 - Installing shaarli/netscape-bookmark-parser (v1.0.1)
137 Downloading: 100%
138```
139
140Optionally, you can delete information related to the legacy version:
141
142```bash
143$ git branch -D master
144Deleted branch master (was 029f75f).
145
146$ git remote remove sebsauvage
147
148$ git remote -v
149origin https://github.com/shaarli/Shaarli (fetch)
150origin https://github.com/shaarli/Shaarli (push)
151
152$ git gc
153Counting objects: 3317, done.
154Delta compression using up to 8 threads.
155Compressing objects: 100% (1237/1237), done.
156Writing objects: 100% (3317/3317), done.
157Total 3317 (delta 2050), reused 3301 (delta 2034)to
158```
159
160#### Step 3: configuration
161After 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.html) for more details).