← Back to branch summary

~ubuntu-branches/ubuntu/natty/moin/natty-updates

« back to all changes in this revision

Viewing changes to wiki/underlay/pages/HelpOnUpdating/revisions/00000001

  • Committer: Bazaar Package Importer
  • Author(s): Jonas Smedegaard
  • Date: 2008-06-22 21:17:13 UTC
  • mfrom: (0.9.1 upstream)
  • Revision ID: james.westby@ubuntu.com-20080622211713-fpo2zrq3s5dfecxg
Tags: 1.7.0-3
Simplify /etc/moin/wikilist format: "USER URL" (drop unneeded middle
CONFIG_DIR that was wrongly advertised as DATA_DIR).  Make
moin-mass-migrate handle both formats and warn about deprecation of
the old one.

Show diffs side-by-side

added added

removed removed

Lines of Context:
wiki/underlay/pages/HelpOnUpdating/revisions/00000001
1
 
## Please edit system and help pages ONLY in the moinmaster wiki! For more
2
 
## information, please see MoinMaster:MoinPagesEditorGroup.
 
1
## Please edit system and help pages ONLY in the master wiki!
 
2
## For more information, please see MoinMoin:MoinDev/Translation.
3
3
##master-page:Unknown-Page
4
4
##master-date:Unknown-Date
5
 
#acl MoinPagesEditorGroup:read,write,delete,revert All:read
 
5
#acl -All:write Default
6
6
#format wiki
7
7
#language en
8
8
HelpContents > HelpOnAdministration > HelpOnUpdating 
9
9
 
10
10
'''Index'''
11
 
[[TableOfContents]]
 
11
<<TableOfContents>>
12
12
 
13
13
== General procedures ==
 
14
=== Download and unpack the new MoinMoin archive ===
 
15
Download the MoinMoin code that you are interested in updating to. If you are not a developer, this is usually the latest released version from the project homepage.
 
16
 
 
17
(!) Often it is better (and easy enough) to install ''latest'' release from distribution archive than relying on some outdated package provided by your Linux distribution. Some people use moin as a package, because they hope for easy upgrades and security fixes. But often, there are either no upgrades or they are not easy and in the worst case, there are not even security fixes.
 
18
 
 
19
 
 
20
=== Reading the docs ===
 
21
Please read the files `docs/CHANGES` and `docs/README.migration` contained in the moin distribution archive for details on what changed and how to upgrade.
 
22
 
 
23
/!\ The docs might contain import installation, compatibility and upgrade hints we won't repeat here.
14
24
 
15
25
=== Backup ===
16
26
 
18
28
 
19
29
You have been warned, and it's not our fault when you end up like this: X-( 
20
30
 
21
 
There are two directory trees which you should backup:
22
 
 
23
 
    * The one containing the MoinMoin executable files (e.g. {{{/usr/lib/python*.*/site-packages/MoinMoin}}})
24
 
    * and the one containing the data (e.g. {{{/usr/share/moin/wikiname/data}}} - see data_dir in your moin_config.py). 
25
 
 
26
 
The pathes depend on your installation.
27
 
 
28
 
=== Install ===
29
 
 
30
 
Download the MoinMoin code that you are interested in updating to.
31
 
 
32
 
As root, run "{{{python setup.py install}}}" to install the new version.
 
31
As you want to make a ''complete'' backup (not even losing a single edit), you want to stop your wiki server process now.
 
32
 
 
33
This is what you should backup (the real paths depend on your installation):
 
34
 * The directory containing the MoinMoin code files (e.g. {{{/usr/lib/python*.*/site-packages/MoinMoin}}})
 
35
   * (!) after you have a backup of this, you might want to delete the `MoinMoin` directory there to avoid having old code files there that are not overwritten by the new code, but maybe interfering with it)
 
36
 * The directory containing your data (e.g. {{{/usr/share/moin/wikiname/data}}} - see data_dir in your moin_config.py). 
 
37
 * your moin.cgi file (or moin.fcg or other adaptor file you use)
 
38
 * your wikiconfig.py or farmconfig.py or other wiki configuration files
 
39
 * your web server configuration files
 
40
 * optionally you can also backup your underlay_data_dir (it shouldn't contain data from you, but it is maybe easier to rollback if you have a backup of it and don't need to get it from some other place)
 
41
 
 
42
=== Code update ===
 
43
First remove the old MoinMoin code (including any `*.pyc` and `*.pyo` files).
 
44
 
 
45
If you are installing from the original distribution archive, run "{{{python setup.py install}}}" as root to install the new version.
 
46
 
 
47
If you are using some Linux (or other) distributor's package, please read their docs.
 
48
 
 
49
Please also upgrade your moin.cgi (or moin.wsgi or other) server adaptor file. You likely have to edit it to fix some pathes and you also need to set some specific user/group/mode on that file (just look at the old one before replacing it).
33
50
 
34
51
=== Configuration update ===
35
52
 
36
 
After upgrading, your existing wiki should continue to work (the goal is to have sane defaults for any new config values, but then there can be bugs). Check that this is indeed the case, and then take the time to check the CHANGES file in your distribution. Often, new features will be invisible unless your extend your configuration in "moin_config.py" (1.3: wikiconfig.py).
37
 
 
38
 
This is especially true for:
39
 
 * somewhat dangerous macros that won't be activated by default, because they're not advisable for public wikis. You need to explicitely activate those by adding an {{{allowed_actions}}} list to the config. Currently, the actions {{{DeletePage}}} and {{{AttachFile}}} are considered unsafe.
40
 
 
41
 
 * email features: you need to provide {{{mail_smarthost}}} and {{{mail_from}}}.
42
 
 
43
 
 * new pages icons: to get new icons like "XML", "Subscribe" etc. it's best to just delete the {{{page_icons}}} setting, now that "config.py" has a default for it. If you changed it in the past, add new icons from the "config.py" default to your "moin_config.py".
44
 
 
45
 
=== Updating files ===
46
 
 
47
 
 Images and CSS:: On every update, you should copy the content of the "share/moin/htdocs/" directory to the directory visible to your web server, normally a new release has some new images and CSS in it. If you use the default distutils setup scheme, this is no longer necessary (distutils updates the files for you, and your webserver gets the files from the installed images and CSS).
48
 
 
49
 
 System pages:: When upgrading to a new version, copy at least the help pages ("Help*") to your existing directory. Then check whether you miss any new system pages. In 1.3 these pages are kept separate in the underlay directory.
50
 
  * When updating from 1.2 or lower to 1.3 or higher, you will want to clean out the copies of the system pages in your {{{wiki/data}}} directory. All of these pages will now reside in the underlay directory. If you have system pages from 1.2 or lower in your {{{wiki/data}}} directory, they will overshadow the more up-to-date documentation. This can be done using the following manual procedure:
51
 
   1. You have just converted from 1.2 or lower to post-1.3.
52
 
   1. Go to your wiki's !EditedSystemPages.
53
 
   1. Find all the pages that are !MoinMoin system or help pages. You will know if it is one of those pages because it is not your page.
54
 
   1. Check if it is okay to delete by either:
55
 
      1. Using the this page "info" link and check the Revision History to see if it is greater than 1. If so, there are modifications, so do not delete the page and evaluate the modifications to see if they are necessary.
56
 
      1. Using your file browser (Windows Explorer, etc) to go to your {{{wiki/data/<<systemPage>>/revisions}}} directory and to see if there are no modifications. If there are, do not delete the page and evaluate the modifications to see if they are necessary.
57
 
   1. (If you have useful edits, please contribute them to the [http://moinmaster.wikiwikiweb.de/ MoinMoin development].)
58
 
   1. Delete that {{{wiki/data/<<systemPage>>}}} using your file browser.
59
 
  * Japanese translation follows.
60
 
  * 1.2以前から1.3以降のアップグレードの際、{{{wiki/data}}}ディレクトリに置いた、システムページのコピーを削除した方が良い。これからこのページはunderlayディレクトリに置く。もし1.2以前のシステムページが{{{wiki/data}}}ディレクトリにある場合、最も最新システムページをかぶせてしまう。以下のとおり、手動の手順：
61
 
   1. 以前から1.3以降のアップグレードを行ったばかり。
62
 
   1. 自分のEditedSystemPagesを開く。
63
 
   1. !MoinMoinのシステムやヘルプページなどを探す。そのページがシステムやヘルプページであることは、自分のページではないことで分かる。
64
 
   1. 削除する前の確認を行う。以下のどちらの方法とする：
65
 
      1. このページの「情報」をクリックして、「"更新履歴"を表示」のページでは更新回数が1以上のこと。そうだったら、変更はあるので、削除しないで、その変更の必要性を判断する。
66
 
      1. ファイルブラウザアプリケーション（Windowsエクスプロラーなど）で、自分の{{{wiki/data/<<systemPage>>/revisions}}}ディレクトリにたどりつけて、変更があることを確認する。そうだったら、変更はあるので、削除しないで、その変更の必要性を判断する。
67
 
   1. (有効な変更があれば、 [http://moinmaster.wikiwikiweb.de/ MoinMoin development]にぜひ与えてください。)
68
 
   1. そのページ{{{wiki/data/<<systemPage>>}}}をファイルブラウザアプリケーションで削除する。
69
 
 
70
 
 InterWiki:: Check that you have the newest "intermap.txt" file; If you have your own entries, you can point "shared_intermap" at a file loaded ''before'' the file in your data directory, which takes precedence (i.e. have global entries in the shared one, private entries the data dir file).
 
53
After upgrading, your existing wiki should continue to work (the goal is to have sane defaults for any new config values, but then there can be bugs and also changes that must break compatibility).
 
54
 
 
55
Check that this is indeed the case, and then take the time to check the CHANGES file in your distribution archive. Often, new features will be invisible unless you extend your configuration in `wikiconfig.py`.
 
56
 
 
57
Check that you have the latest "intermap.txt" file; If you have your own entries, you can point "shared_intermap" at a file loaded ''before'' the file in your data directory, which takes precedence (i.e. have global entries in the shared one, private entries the data dir file).
 
58
 
 
59
=== Static stuff update ===
 
60
 
 
61
On every update, you should copy the content of the "wiki/htdocs/" directory we provide to the directory visible to your web server, normally a new release has some new images, CSS and Javascript in it.
 
62
 
 
63
You also have to change your web server / directory setup to match the `url_prefix_static` setting of moin. This defaults to `/moin_staticVVV` (VVV is 170 for moin release 1.7.0) and the default will change on every release (moin 1.7.1 will use `/moin_static171` by default). This is done to be able to use a very long cache lifetime for the static stuff, so your wiki will be faster and cause less load and traffic.
 
64
 
 
65
=== Wiki pages update ===
 
66
==== System and Help pages ====
 
67
System and help pages are separately stored in the `underlay` directory. Just use the fresh underlay directory we provide in the distribution archive (move the old one to your backup directory).
 
68
 
 
69
==== Your valuable own pages ====
 
70
See CHANGES and README.migration for maybe necessary steps to convert your `data_dir` to what we expect.
71
71
 
72
72
=== Troubleshooting ===
73
 
 
74
 
A good idea is to do a request for "moin.cgi?action=test" (which calls an internal diagnosis feature) after you installed a new release, which will spot some common errors.
75
 
 
76
 
Depending on your installation, more tightly secured permissions are a good idea. Ideally, you assign all files in the data directory to the user the web server runs under, and then you use `700` or `755`.
77
 
 
78
 
== Upgrade information for specfic versions ==
79
 
 
80
 
The following sections provide information pertaining to specific versions of the software; if you jump several versions, read all the sections applying to your situation.
81
 
 
82
 
[[Anchor(update-1-0)]]
83
 
=== Version 1.0 ===
84
 
 
85
 
Version 1.0 is the last to support Python 1.5.2, but some optional features (like statistics) already require Python 2.0.
86
 
 
87
 
 
88
 
[[Anchor(update-1-1)]]
89
 
=== Version 1.1 ===
90
 
 
91
 
Be sure to read the above section on ''General procedures'' before you start upgrading.
92
 
 
93
 
'''Version 1.1 requires Python 2.0 or higher''', we recommend to use Python 2.2 (version 2.2.2 if that is available on your host) or even better >= 2.3.2 (with 2.3.x, MoinMoin runs about 20-30% faster).
94
 
 
95
 
 
96
 
'''Upgrading your configuration'''
97
 
 
98
 
 * If you changed the default for `page_template_ending`, this is now called `page_template_regex` and must contain a regex (defaults to '[a-z]Template$').
99
 
 * Same applies to `page_form_ending` now called `page_form_regex` (default: '[a-z]Form$')
100
 
 * Not a new feature, but configurable now: `page_category_regex` (default: '^Category[A-Z]')
101
 
 * If you have added your own `SecurityPolicy`, the class interface for that has changed (see `security.py`).
102
 
 
103
 
'''Enabling new features'''
104
 
 
105
 
 * `default_lang` (default: 'en') - If user does not set a language in his user settings, this will be used.
106
 
 * `edit_locking` (default: `'warn 10'`) - Editor locking policy: None, 'warn <timeout in minutes>', or 'lock <timeout in minutes>'.
107
 
 * `hosts_deny` (default: `[]`) - a list of denied IPs; if an IP ends with a dot, it denies a whole subnet (class A, B or C).
108
 
 * `html_pagetitle` (default: `None`) -  Allows you to set a specific HTML page title (if not set, it defaults to the value of sitename).
109
 
 * `mail_login` (default: `None`) - This is only needed when you use SMTP AUTH to send mail; in that case, set this to the username and password separated by a space, i.e. "user pwd".
110
 
 * `smileys` (default: `{}`) -  User-defined smileys (a dict with the markup as the key and a tuple of width, height, border, image name as the value).
111
 
 * don't forget to read the CHANGES file in the distribution archive
112
 
 
113
 
[[Anchor(update-1-2)]]
114
 
=== Version 1.2 ===
115
 
 
116
 
'''Version 1.2 requires Python 2.2.2 or higher''', we recommend to use Python >=2.3.2 (with 2.3.x, MoinMoin runs about 20-30% faster).
117
 
 
118
 
 * the URL for the RecentChanges RSS feed changed. It now only works with `?action=rss_rc`.
119
 
 
120
 
 * drawings use a new applet. It saves PNG instead of GIF and can do image maps to make areas of the drawing active. On display a GIF will be searched if no PNG is found. We recommend changing all GIFs to indexed PNGs cause this fallback might disappear in later versions.
121
 
 Sample code using bash & !ImageMagick (be sure you know what you do):
122
 
 {{{
123
 
for draw in `find /path/to/wiki/data -name \*.draw`; do
124
 
    file=`dirname $draw`/`basename $draw .draw`
125
 
    if [ -e "${file}.gif" ]; then
126
 
        echo "Converting ${file}.gif to ${file}.png"
127
 
        convert "${file}.gif" "${file}.png"
128
 
    fi
129
 
done
130
 
}}}
131
 
 
132
 
 * `caching_formats` (default: {{{['text_html',]}}}) - enable caching for the given output formats; enabled by default. Developers maybe want to disable this and use the empty list.
133
 
 
134
 
 * Themeing and HTML/CSS cleanup
135
 
  * Browsers with completely broken CSS support (like e.g. Netscape 4.x) are no longer supported. If you still need to support them, do not upgrade to moin 1.2. If you still use these browsers, we recommend that you upgrade your browser first (Mozilla 1.5 has nice and standards compliant HTML and CSS support and is available as Free Software for Windows, Linux and Mac).
136
 
  * If you changed any html in code or by config you will have to check if it still works. For the usual stuff, look into `MoinMoin/theme/classic.py` and `classic/css/screen.css`. For config defaults of the html fragments, read `MoinMoin/config.py`. If you want to modify a theme, don't simply change classic, but copy or subclass it under a new theme name.
137
 
  * because of the new theme support the layout of the `htdocs` directory changed:
138
 
   * Instead of using icons under `img/` and css under `css/`, there will be an additional `themename/` directory in between, e.g. `classic/img/` and `classic/css/`. If you added own icons, you may have to copy them to the themes directory.
139
 
   * The filename of the CSS file has changed to the media type, so the normal one used for screen output has changed name from `moinmoin.css` to `screen.css`. There also were quite some changes and enhancements to the CSS files, so better use the new ones.
140
 
  * config.css_url was removed
141
 
 
142
 
 * Plugins - we use a new plugin loader that requires a correct `__init__.py` file in the plugin directories. See the directory `wiki/data/plugin/` in the distribution archive and just copy it over to your wiki's plugin directory.
143
 
 
144
 
 * Do not forget to update to the new Twikidrawplugin that comes with moin 1.2.
145
 
 
146
 
 * removed config variables:
147
 
  * external_diff (not needed any more, we have internal diff now)
148
 
  * shared_metadb (wasn't implemented for long - we will re-add it, when it is)
149
 
  * title1/2 (please use page_header1/2)
150
 
  * page_icons_up
151
 
 
152
 
 * changed config variables:
153
 
  * changed_time_fmt (removed some html and brackets around time from default)
154
 
  * html_head (default is empty string now)
155
 
  * page_footer1/2 (default is empty string now)
156
 
  * page_icons (is now a list of icon names, not html any more)
157
 
  * umask (default is 0770 now, not world r/w any more == more secure)
158
 
 
159
 
 * new config variables (see MoinMaster:HelpOnConfiguration):
160
 
  * cookie_lifetime
161
 
  * mail_login
162
 
  * page_credits
163
 
  * page_dict_regex
164
 
  * page_group_regex
165
 
  * page_header1/2
166
 
  * page_iconbar 
167
 
  * page_icons_table
168
 
  * page_license_enabled
169
 
  * page_license_page
170
 
  * theme_default
171
 
  * theme_force
172
 
  * tz_offset 
173
 
 
174
 
 
175
 
[[Anchor(update-1-2-1)]]
176
 
[[Anchor(update-1-2-2)]]
177
 
[[Anchor(update-1-2-3)]]
178
 
=== Version 1.2.1, 1.2.2, 1.2.3 ===
179
 
As 1.2.x is primarily a bug-fix release for 1.2, there is not much special if you run 1.2 and want to update to 1.2.x.
180
 
 
181
 
If you run a version previous to 1.2, please read above about upgrading to 1.2 first.
182
 
 
183
 
In any case, read the `CHANGES` file in the toplevel directory of your moin archive - all fixes are described there and also some few new features.
184
 
 
185
 
Be aware that except code fixes, there were also fixes in the data and htdocs directory - so please selectively copy them over to your running wiki installation.
186
 
 
187
 
[[Anchor(update-1-3)]]
188
 
=== Version 1.3 and above ===
189
 
 
190
 
/!\ Upgrading to moin 1.3 will be non-trivial. It will definitely take you more than 5 minutes. /!\
191
 
 
192
 
This is because of many changes to configuration, data format, filenames and pathes.
193
 
 
194
 
In any case, make a backup or you risk destroying your wiki's content.
195
 
 
196
 
Please read the files `CHANGES` and `README.migration` in the toplevel directory of your moin archive for details on what changed and how to upgrade.
197
 
 
198
 
''For this and greater versions, See MoinMoin:MoinMoinUpgrade.''
199
 
 
200
 
=== Deprecation Note ===
201
 
 
202
 
This page is deprecated (at least the version specific stuff on it), for 1.5 it will be gone and we will use CHANGES file exclusively.
 
73
Use absolute pathes, not relative ones.
 
74
 
 
75
Make sure you have an adequate logging configuration (see server adaptor script and the logging configuration file) and carefully read the log!
 
76
 
 
77
Make sure python can find the !MoinMoin code package and your wiki configuration files (fix `sys.path` in the server adaptor script or PYTHONPATH in the environment).
 
78
 
 
79
Make sure !MoinMoin can find the data_dir and data_underlay_dir (see `wikiconfig.py`).
 
80
 
 
81
When you are editing python code files (e.g. `wikiconfig.py`), be careful to indent correctly (use 4 spaces, not tabs) and also be careful not to make syntax errors. If you have a working config, do not make too many changes at once (and have a backup of a working version).
 
82
 
 
83
Check permissions (the moin process needs read/write access to `data_dir` and `data_underlay_dir`, it needs at least read access to the MoinMoin code and configuration).
 
84
 
 
85
Depending on your installation, more tightly secured permissions are a good idea. Ideally, you assign all files in the data directory to the user the web server runs under, and then you use `700` or `770` - see also the `config.umask` setting.