aboutsummaryrefslogtreecommitdiffhomepage
path: root/doc/Upgrade-and-migration.md
diff options
context:
space:
mode:
authornodiscc <nodiscc@gmail.com>2017-01-26 18:52:54 +0100
committernodiscc <nodiscc@gmail.com>2017-06-18 00:19:49 +0200
commit53ed6d7d1e678d7486337ce67a2f17b30bac21ac (patch)
treef8bef0164a70bd03d2b9781951c01bdd018f1842 /doc/Upgrade-and-migration.md
parentd5d22a6d07917865c44148ad76f43c65a929a890 (diff)
downloadShaarli-53ed6d7d1e678d7486337ce67a2f17b30bac21ac.tar.gz
Shaarli-53ed6d7d1e678d7486337ce67a2f17b30bac21ac.tar.zst
Shaarli-53ed6d7d1e678d7486337ce67a2f17b30bac21ac.zip
Generate HTML documentation using MkDocs (WIP)
MkDocs is a static site generator geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML file. * http://www.mkdocs.org/ * http://www.mkdocs.org/user-guide/configuration/ Ref. #312 * remove pandoc-generated HTML documentation * move markdown doc to doc/md/, * mkdocs.yml: * generate HTML doc in doc/html * add pages TOC/ordering * use index.md as index page * Makefile: remove execute permissions from generated files * Makefile: rewrite htmlpages GFM to markdown conversion using sed: awk expression aslo matched '][' which causes invalid output on complex links with images or code blocks * Add mkdocs.yml to .gitattributes, exclude this file from release archives * Makefile: rename: htmldoc -> doc_html target * run make doc: pull latest markdown documentation from wiki * run make htmlpages: update html documentation
Diffstat (limited to 'doc/Upgrade-and-migration.md')
-rw-r--r--doc/Upgrade-and-migration.md186
1 files changed, 0 insertions, 186 deletions
diff --git a/doc/Upgrade-and-migration.md b/doc/Upgrade-and-migration.md
deleted file mode 100644
index d36eb862..00000000
--- a/doc/Upgrade-and-migration.md
+++ /dev/null
@@ -1,186 +0,0 @@
1#Upgrade and migration
2## Preparation
3### Note your current version
4
5If anything goes wrong, it's important for us to know which version you're upgrading from.
6The current version is present in the `version.php` file.
7
8### Backup your data
9
10Shaarli stores all user data under the `data` directory:
11- `data/config.php` - main configuration file
12- `data/datastore.php` - bookmarked links
13- `data/ipbans.php` - banned IP addresses
14- `data/updates.txt` - contains all automatic update to the configuration and datastore files already run
15
16See [Shaarli configuration](Shaarli-configuration.html) for more information about Shaarli resources.
17
18It is recommended to backup this repository _before_ starting updating/upgrading Shaarli:
19- users with SSH access: copy or archive the directory to a temporary location
20- users with FTP access: download a local copy of your Shaarli installation using your favourite client
21
22### Migrating data from a previous installation
23As 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:
24
25- backup the `data` directory
26- install or update Shaarli:
27 - fresh installation - see [Download and installation](Download-and-installation.html)
28 - update - see the following sections
29- check or restore the `data` directory
30
31## Recommended : Upgrading from release archives
32All tagged revisions can be downloaded as tarballs or ZIP archives from the [releases](https://github.com/shaarli/Shaarli/releases) page.[](.html)
33
34We recommend that you use the latest release tarball with the `-full` suffix. It contains the dependencies, please read [Download and installation](Download-and-installation.html) for `git` complete instructions.
35
36Once downloaded, extract the archive locally and update your remote installation (e.g. via FTP) -be sure you keep the content of the `data` directory!
37
38After 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.html) for more details).
39
40## Upgrading with Git
41### Updating a community Shaarli
42If 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)
43
44```bash
45$ cd /path/to/shaarli
46$ git pull
47
48From github.com:shaarli/Shaarli
49 * branch master -> FETCH_HEAD
50Updating ebd67c6..521f0e6
51Fast-forward
52 application/Url.php | 1 +
53 shaarli_version.php | 2 +-
54 tests/Url/UrlTest.php | 1 +
55 3 files changed, 3 insertions(+), 1 deletion(-)
56```
57
58Shaarli >= `v0.8.x`: install/update third-party PHP dependencies using [Composer](https://getcomposer.org/):[](.html)
59
60```bash
61$ composer install --no-dev
62
63Loading composer repositories with package information
64Updating dependencies
65 - Installing shaarli/netscape-bookmark-parser (v1.0.1)
66 Downloading: 100%
67```
68
69### Migrating and upgrading from Sebsauvage's repository
70If 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)
71
72The following guide assumes that:
73- 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)
74- the default remote is named `origin` and points to Sebsauvage's repository
75- the current branch is `master`
76 - 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)
77- the working copy is clean:
78 - no versioned file has been locally modified
79 - no untracked files are present
80
81#### Step 0: show repository information
82```bash
83$ cd /path/to/shaarli
84
85$ git remote -v
86origin https://github.com/sebsauvage/Shaarli (fetch)
87origin https://github.com/sebsauvage/Shaarli (push)
88
89$ git branch -vv
90* master 029f75f [origin/master] Update README.md[](.html)
91
92$ git status
93On branch master
94Your branch is up-to-date with 'origin/master'.
95nothing to commit, working directory clean
96```
97
98#### Step 1: update Git remotes
99```
100$ git remote rename origin sebsauvage
101$ git remote -v
102sebsauvage https://github.com/sebsauvage/Shaarli (fetch)
103sebsauvage https://github.com/sebsauvage/Shaarli (push)
104
105$ git remote add origin https://github.com/shaarli/Shaarli
106$ git fetch origin
107
108remote: Counting objects: 3015, done.
109remote: Compressing objects: 100% (19/19), done.
110remote: Total 3015 (delta 446), reused 457 (delta 446), pack-reused 2550
111Receiving objects: 100% (3015/3015), 2.59 MiB | 918.00 KiB/s, done.
112Resolving deltas: 100% (1899/1899), completed with 48 local objects.
113From https://github.com/shaarli/Shaarli
114 * [new branch] master -> origin/master[](.html)
115 * [new branch] stable -> origin/stable[](.html)
116[...][](.html)
117 * [new tag] v0.6.4 -> v0.6.4[](.html)
118 * [new tag] v0.7.0 -> v0.7.0[](.html)
119```
120
121#### Step 2: use the stable community branch
122
123```bash
124$ git checkout origin/stable -b stable
125Branch stable set up to track remote branch stable from origin.
126Switched to a new branch 'stable'
127
128$ git branch -vv
129 master 029f75f [sebsauvage/master] Update README.md[](.html)
130* stable 890afc3 [origin/stable] Merge pull request #509 from ArthurHoaro/v0.6.5[](.html)
131```
132
133Shaarli >= `v0.8.x`: install/update third-party PHP dependencies using [Composer](https://getcomposer.org/):[](.html)
134
135```bash
136$ composer install --no-dev
137
138Loading composer repositories with package information
139Updating dependencies
140 - Installing shaarli/netscape-bookmark-parser (v1.0.1)
141 Downloading: 100%
142```
143
144Optionally, you can delete information related to the legacy version:
145
146```bash
147$ git branch -D master
148Deleted branch master (was 029f75f).
149
150$ git remote remove sebsauvage
151
152$ git remote -v
153origin https://github.com/shaarli/Shaarli (fetch)
154origin https://github.com/shaarli/Shaarli (push)
155
156$ git gc
157Counting objects: 3317, done.
158Delta compression using up to 8 threads.
159Compressing objects: 100% (1237/1237), done.
160Writing objects: 100% (3317/3317), done.
161Total 3317 (delta 2050), reused 3301 (delta 2034)to
162```
163
164#### Step 3: configuration
165After 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).
166
167## Troubleshooting
168
169If the solutions provided here doesn't work, please open an issue specifying which version you're upgrading from and to.
170
171### You must specify an integer as a key
172
173In `v0.8.1` we changed how link keys are handled (from timestamps to incremental integers).
174Take a look at `data/updates.txt` content.
175
176#### `updates.txt` contains `updateMethodDatastoreIds`
177
178Try to delete it and refresh your page while being logged in.
179
180#### `updates.txt` doesn't exists or doesn't contain `updateMethodDatastoreIds`
181
182 1. Create `data/updates.txt` if it doesn't exist.
183 2. Paste this string in the update file `;updateMethodRenameDashTags;`
184 3. Login to Shaarli.
185 4. Delete the update file.
186 5. Refresh.