doc/tips/optimising_ikiwiki.mdwn

   1 [[!meta date="2009-10-15 18:42:46 -0400"]]
   2
   3 Ikiwiki is a wiki compiler, which means that, unlike a traditional wiki,
   4 all the work needed to display your wiki is done up front. Where you can
   5 see it and get annoyed at it. In some ways, this is better than a wiki
   6 where a page view means running a program to generate the page on the fly.
   7
   8 But enough excuses. If ikiwiki is taking too long to build your wiki,
   9 let's fix that. Read on for some common problems that can be avoided to
  10 make ikiwiki run quick.
  11
  12 [[!toc]]
  13
  14 (And if none of that helps, file a [[bug|bugs]]. One other great thing about
  15 ikiwiki being a wiki compiler is that it's easy to provide a test case when
  16 it's slow, and get the problem fixed!)
  17
  18 ## rebuild vs refresh
  19
  20 Are you building your wiki by running a command like this?
  21
  22         ikiwiki --setup my.setup
  23
  24 If so, you're always telling ikiwiki to rebuild the entire site, from
  25 scratch. But, ikiwiki is smart, it can incrementally update a site,
  26 building only things affected by the changes you make. You just have to let
  27 it do so:
  28
  29         ikiwiki --setup my.setup --refresh
  30
  31 Ikiwiki automatically uses an incremental refresh like this when handing
  32 a web edit, or when run from a [[rcs]] post-commit hook. (If you've
  33 configured the hook in the usual way.) Most people who have run into this
  34 problem got in the habit of running `ikiwiki --setup my.setup` by hand
  35 when their wiki was small, and found it got slower as they added pages.
  36
  37 ## use the latest version
  38
  39 If your version of ikiwiki is not [[!version]], try upgrading. New
  40 optimisations are frequently added to ikiwiki, some of them yielding
  41 *enormous* speed increases.
  42
  43 ## run ikiwiki in verbose mode
  44
  45 Try changing a page, and run ikiwiki with `-v` so it will tell you
  46 everything it does to deal with that changed page. Take note of
  47 which other pages are rebuilt, and which parts of the build take a long
  48 time. This can help you zero in on individual pages that contain some of
  49 the expensive things listed below.
  50
  51 ## expensive inlines
  52
  53 Do you have an archive page for your blog that shows all posts,
  54 using an inline that looks like this?
  55
  56         \[[!inline pages="blog/*" show=0]]
  57
  58 Or maybe you have some tag pages for your blog that show all tagged posts,
  59 something like this?
  60
  61         \[[!inline pages="blog/* and tagged(foo)" show=0]]
  62
  63 These are expensive, because they have to be updated whenever you modify a
  64 matching page. And, if there are a lot of pages, it generates a large html
  65 file, which is a lot of work. And also large RSS/Atom files, which is even
  66 more work!
  67
  68 To optimise the inline, consider enabling quick archive mode. Then the
  69 inline will only need to be updated when new pages are added; no RSS
  70 or Atom feeds will be built, and the generated html file will be much
  71 smaller.
  72
  73         \[[!inline pages="blog/*" show=0 archive=yes quick=yes]]
  74
  75         \[[!inline pages="blog/* and link(tag)" show=0 archive=yes quick=yes]]
  76
  77 Only downsides: This won't show titles set by the [[ikiwiki/directive/meta]]
  78 directive. And there's no RSS feed for users to use -- but if this page
  79 is only for the archives or tag for your blog, users should be subscribing
  80 to the blog's main page's RSS feed instead.
  81
  82 For the main blog page, the inline should only show the latest N posts,
  83 which won't be a performance problem:
  84
  85         \[[!inline pages="blog/*" show=30]]
  86
  87 ## expensive maps
  88
  89 Do you have a sitemap type page, that uses a map directive like this?
  90
  91         \[[!map pages="*" show=title]]
  92
  93 This is expensive because it has to be updated whenever a page is modified.
  94 The resulting html file might get big and expensive to generate as you
  95 keep adding pages.
  96
  97 First, consider removing the "show=title". Then the map will not show page
  98 titles set by the [[ikiwiki/directive/meta]] directive -- but will also
  99 only need to be generated when pages are added or removed, not for every
 100 page change.
 101
 102 Consider limiting the map to only show the toplevel pages of your site,
 103 like this:
 104
 105         \[[!map pages="* and !*/*" show=title]]
 106
 107 Or, alternatively, to drop from the map parts of the site that accumulate
 108 lots of pages, like individual blog posts:
 109
 110         \[[!map pages="* and !blog/*" show=title]]
 111
 112 ## sidebar issues
 113
 114 If you enable the [[plugins/sidebar]] plugin, be careful of what you put in
 115 your sidebar. Any change that affects what is displayed by the sidebar
 116 will require an update of *every* page in the wiki, since all pages include
 117 the sidebar.
 118
 119 Putting an expensive map or inline in the sidebar is the most common cause
 120 of problems. At its worst, it can result in any change to any page in the
 121 wiki requiring every page to be rebuilt.
 122
 123 ## avoid htmltidy
 124
 125 A few plugins do neat stuff, but slowly. Such plugins are tagged
 126 [[plugins/type/slow]].
 127
 128 The worst offender is possibly [[plugins/htmltidy]]. This runs an external
 129 `tidy` program on each page that is built, which is necessarily slow. So don't
 130 use it unless you really need it; consider using the faster
 131 [[plugins/htmlbalance]] instead.
 132
 133 ## be careful of large linkmaps
 134
 135 [[plugins/Linkmap]] generates a cool map of links between pages, but
 136 it does it using the `graphviz` program. And any changes to links between
 137 pages on the map require an update. So, avoid using this to map a large number
 138 of pages with frequently changing links. For example, using it to map
 139 all the pages on a traditional, highly WikiLinked wiki, is asking for things
 140 to be slow. But using it to map a few related pages is probably fine.
 141
 142 This site's own [[plugins/linkmap]] rarely slows it down, because it
 143 only shows the index page, and the small set of pages that link to it.
 144 That is accomplished as follows:
 145
 146         \[[!linkmap pages="index or (backlink(index)"]]
 147
 148 ## overhead of the search plugin
 149
 150 Be aware that the [[plugins/search]] plugin has to update the search index
 151 whenever any page is changed. This can slow things down somewhat.
 152
 153 ## cgi overload workaround
 154
 155 If the ikiwiki.cgi takes a long time to run, it's possible
 156 that under load, your site will end up with many
 157 of them running, all waiting on some long-running thing,
 158 like a site rebuild. This can prevent the web server from doing anything
 159 else.
 160
 161 A workaround for this problem is to set `cgi_overload_delay` to
 162 a number of seconds. Now if ikiwiki.cgi would block waiting
 163 for something, it will instead display a Please wait message (configurable
 164 via `cgi_overload_message`, which can contain arbitrary html),
 165 and set the page to reload it after the configured number of seconds.
 166
 167 This takes very little load, as it all happens within compiled C code.
 168 Note that it is currently limited to GET requests, not POST requests.
 169
 170 ## scaling to large numbers of pages
 171
 172 Finally, let's think about how huge number of pages can affect ikiwiki.
 173
 174 * Every time it's run, ikiwiki has to scan your `srcdir` to find
 175   new and changed pages. This is similar in speed to running the `find`
 176   command. Obviously, more files will make it take longer.
 177
 178   You can avoid this scanning overhead, if you're using git, by setting
 179   `only_committed_changes`. This makes ikiwiki --refresh query git for
 180   changed files since the last time, which tends to be a lot faster.
 181   However, it only works if all files in your wiki are committed to git
 182   (or stored in the [[/plugins/transient]] underlay).
 183
 184 * Also, to see what pages match a [[ikiwiki/PageSpec]] like "blog/*", it has
 185   to check if every page in the wiki matches. These checks are done quite
 186   quickly, but still, lots more pages will make PageSpecs more expensive.
 187
 188 * The backlinks calculation has to consider every link on every page
 189   in the wiki. (In practice, most pages only link to at most a few dozen
 190   other pages, so this is not a `O(N^2)`, but closer to `O(N)`.)
 191
 192 * Ikiwiki also reads and writes an `index` file, which contains information
 193   about each page, and so if you have a lot of pages, this file gets large,
 194   and more time is spent on it. For a wiki with 2000 pages, this file
 195   will run about 500 kb.
 196
 197 If your wiki will have 100 thousand files in it, you might start seeing
 198 the above contribute to ikiwiki running slowly.
 199
 200 ## profiling
 201
 202 If you have a repeatable change that ikiwiki takes a long time to build,
 203 and none of the above help, the next thing to consider is profiling
 204 ikiwiki.
 205
 206 The best way to do it is:
 207
 208 * Install [[!cpan Devel::NYTProf]]
 209 * `PERL5OPT=-d:NYTProf`
 210 * `export PERL5OPT`
 211 * Now run ikiwiki as usual, and it will generate a `nytprof.out` file.
 212 * Run `nytprofhtml` to generate html files.
 213 * Those can be examined to see what parts of ikiwiki are being slow.