]> git.vanrenterghem.biz Git - git.ikiwiki.info.git/blob - doc/todo/git-annex_support.mdwn
(no commit message)
[git.ikiwiki.info.git] / doc / todo / git-annex_support.mdwn
1 A dear [[wishlist]] which would resolve [[this question|forum/ikiwiki_and_big_files]]: ikiwiki should support git-annex repositories.
3 I am not sure how this would work, but from my POV, it should do a `git annex get` when new commits are pushed to its bare repo. This would assume, of course, that there's another repo somewhere that ikiwiki has access to, which works for HTTP-style remotes, but could be more problematic for SSH remotes that require a key.
5 Another solution would be to make ikiwiki a remote itself and allow users to push big files to it. The only problem I see with this is those files would end up in the bare repository and not necessarily show up in the web rendering. Ideally, a big file pushed would be hardlinked between the two repos, but it seems [git-annex doesn't support that yet](http://git-annex.branchable.com/todo/wishlist:_use_hardlinks_for_local_clones). --[[anarcat]]
7 > One technical problem with this is that ikiwiki doesn't allow symlinks
8 > for [[security]], but git-annex relies on symlinks (unless you're in
9 > direct mode, but I'm not sure that's really desirable here).
10 > I'd like to make symlinks possible without compromising security,
11 > but it'll be necessary to be quite careful. --[[smcv]]
13 First implementation
14 ====================
16 So as the [[discussion]] shows, it seems it's perfectly possible to actually do this! There's this [gallery site](http://stockholm.kalleswork.net) which uses the [[plugins/contrib/album]] plugin and git-annex to manage its files.
18 The crucial steps are:
20  1. setup a git annex remote in `$srcdir`
22  2. configure direct mode because ikiwiki ignores symlinks for [[security]] reasons:
24         cd $srcdir
25         git annex init
26         git annex direct
28  3. configure files to be considered by git-annex (those will be not committed into git directly):
30         git config annex.largefiles 'largerthan=100kb and not (include=*.mdwn or include=*.txt)'
32  4. make the bare repository (the remote of `$srcdir`) ignored by git-annex:
34         cd $srcdir
35         git config remote.origin.annex-ignore true
36         git config remote.origin.annex-sync false
38     (!) This needs to be done on *ANY* clone of the repository, which is annoying, but it's important because we don't want to see git-annex stuff in the bare repo. (why?)
40  5. deploy the following crappy plugin to make commits work again and make sure the right files are added in git-annex:
42 [[!format perl """
43 #!/usr/bin/perl
44 package IkiWiki::Plugin::gitannex;
46 use warnings;
47 use strict;
48 use IkiWiki 3.00;
50 sub import {
51         hook(type => "getsetup", id => "gitannex", call => \&getsetup);
52         hook(type => "savestate", id => "gitannex", call => \&rcs_commit);
53         # we need to handle all rcs commands maybe?
54 }
56 sub getsetup () {
57         return
58                 plugin => {
59                         safe => 1, # rcs plugin
60                         rebuild => undef,
61                         section => "misc",
62                 },
63 }
65 # XXX: we want to copy or reuse safe_git
67 sub rcs_commit (@) {
68     chdir $config{srcdir};
69     `git annex add --auto`;
70     `git annex sync`;
71 }
73 sub rcs_commit_staged (@) {
74     rcs_commit($@);
75 }
77 1
78 """]]
79 This assumes you know what `srcdir`, `repository` and so on mean, if you forgot (like me), see this reference: [[rcs/git/]].
82 What doesn't work
83 -----------------
85  * the above plugin is kind of flaky and ugly.
86  * it's not an RCS plugin, but probably should be, replacing the git plugin, because really: git doesn't work at all anymore at this point
88 What remains to be clarified
89 ----------------------------
91  * how do files get pushed to the `$srcdir`? Only through the web interface?
92  * why do we ignore the bare repository?
94 See the [[discussion]] for a followup on that. --[[anarcat]]
96 Alternative implementation
97 ==========================
99 An alternative implementation, which remains to be detailed but is mentionned in [[forum/ikiwiki_and_big_files]], is to use the [[underlay]] feature combined with the `hardlink` option to deploy the git-annex'd files. Then git-annex is separate from the base ikiwiki git repo. See also [[tips/Ikiwiki_with_git-annex__44___the_album_and_the_underlay_plugins]] for an example.
101 Also note that ikiwiki-hosting has a [patch waiting](https://ikiwiki-hosting.branchable.com/todo/git-annex_support) to allow pushes to work with git-annex. This could potentially be expanded to sync content to the final checkout properly, avoiding some of the problems above (esp. wrt to non-annex bare repos).
103 Combined with the [[underlay]] feature, this could work very nicely indeed... --[[anarcat]]
105 Here's an attempt:
107 <pre>
108 cd /home/user
109 git clone source.git source.annex
110 cd source.annex
111 git annex direct
112 cd ../source.git
113 git annex group . transfer
114 git remote add annex ../source.annex
115 git annex sync annex
116 </pre>
118 Make sure the `hardlink` setting is enabled, and add the annex as an underlay, in `ikiwiki.setup`:
120 <pre>
121 hardlink: 1
122 add_underlays:
123 - /home/w-anarcat/source.annex
124 </pre>
126 Then moving files to the underlay is as simple as running this command in the bare repo:
128 <pre>
129 #!/bin/sh
131 echo "moving big files to annex repository..."
132 git annex move --to annex
133 </pre>
135 I have added this as a hook in `$HOME/source.git/hooks/post-receive` (don't forget to `chmod +x`).
137 The problem with the above is that the underlay wouldn't work: for some reason it wouldn't copy those files in place properly. Maybe it's freaking out because it's a full copy of the repo... My solution was to make the source repository itself a direct repo, and then add it as a remote to the bare repo. --[[anarcat]]
139 Back from the top
140 =================
142 Obviously, the final approach of making the `source` repository direct mode will fail because ikiwiki will try to commit files there from the web interface which will fail (at best) and (at worst) add big files into git-annex (or vice-versa, not sure what's worse actually).
144 Also, I don't know how others here made the underlay work, but it didn't work for me. I think it's because in the "source" repository, there are (dead) symlinks for the annexed files. This overrides the underlay, because of [[security]] - although I am unclear as to why this is discarded so early. So in order to make the original idea above work properly (ie. having a separate git-annex repo in direct mode) work, we must coerce ikiwiki into tolerating symlinks in the srcdir a little more:
146 <pre>
147 diff --git a/IkiWiki.pm b/IkiWiki.pm
148 index 1043ef4..949273c 100644
149 --- a/IkiWiki.pm
150 +++ b/IkiWiki.pm
151 @@ -916,11 +916,10 @@ sub srcfile_stat {
152         my $file=shift;
153         my $nothrow=shift;
155 -       return "$config{srcdir}/$file", stat(_) if -e "$config{srcdir}/$file";
156 -       foreach my $dir (@{$config{underlaydirs}}, $config{underlaydir}) {
157 -               return "$dir/$file", stat(_) if -e "$dir/$file";
158 +       foreach my $dir ($config{srcdir}, @{$config{underlaydirs}}, $config{underlaydir}) {
159 +               return "$dir/$file", stat(_) if (-e "$dir/$file" && ! -l "$dir/$file");
160         }
161 -       error("internal error: $file cannot be found in $config{srcdir} or underlay") unless $nothrow;
162 +       error("internal error: $file cannot be found in $config{srcdir} or underlays @{$config{underlaydirs}} $config{underlaydir}") unless $nothrow;
163         return;
164  }
166 diff --git a/IkiWiki/Render.pm b/IkiWiki/Render.pm
167 index 9d6f636..e0b4cf8 100644
168 --- a/IkiWiki/Render.pm
169 +++ b/IkiWiki/Render.pm
170 @@ -337,7 +337,7 @@ sub find_src_files (;$$$) {
172                 if ($underlay) {
173                         # avoid underlaydir override attacks; see security.mdwn
174 -                       if (! -l "$abssrcdir/$f" && ! -e _) {
175 +                       if (1 || ! -l "$abssrcdir/$f" && ! -e _) {
176                                 if (! $pages{$page}) {
177                                         push @files, $f;
178                                         push @IkiWiki::underlayfiles, $f;
179 </pre>
181 <del>Now obviously this patch is incomplete: I am not sure we actually avoid the attack, ie. i am not sure the check in `srcdir()` is sufficient to remove completely the check in `find_src_files()`.</del>
183 After reviewing the code further, it seems that `find_src_files` in three places in ikiwiki:
185 <pre>
186 ../IkiWiki/Render.pm:421:       find_src_files(1, \@files, \%pages);
187 ../IkiWiki/Render.pm:846:               ($files, $pages)=find_src_files();
188 ../po/po2wiki:18:my ($files, $pages)=IkiWiki::find_src_files();
189 </pre>
191 The first occurence is in `IkiWiki::Render::process_changed_files`, where it is used mostly for populating `@IkiWiki::underlayfiles`, the only side effect of 
192 `find_src_files`. The second occurence is in `IkiWiki::Render::refresh`. There things are a little more complicated (to say the least) and a lot of stuff happens. To put it in broad terms, first it does a `IkiWiki::Render::scan` and then a `IkiWiki::Render::render`. The last two call `srcfile()` appropriately (where i put an extra symlink check), except for  `will_render()` in `scan`, which I can't figure out right now and that seems to have a lot of global side effects. It still looks fairly safe at first glance. The `rcs_get_current_rev`, `refresh`, `scan` and `rendered` hooks are also called in there, but I assume those to be safe, since they are called with sanitized values already.
194 The patch does work: the files get picked up from the underlay and properly hardlinked into the target `public_html` directory! So with the above patch, then the following hook in `source.git/hooks/post-receive`:
196 <pre>
197 #!/bin/sh
199 OLD_GIT_DIR="$GIT_DIR"
200 unset GIT_DIR
201 echo "moving big files to annex repository..."
202 git annex copy --to annex
203 git annex sync annex
204 </pre>
206 (I am not sure anymore why GIT_DIR is necessary, but I remember it destroyed all files in my repo because git-annex synced against the `setup` branch in the parent directory. fun times.)
208 Then the `annex` repo is just a direct clone of the source.git:
210 <pre>
211 cd /home/user
212 git clone --shared source.git annex
213 cd annex
214 git annex direct
215 cd ../source.git
216 git remote add annex ../annex
217 </pre>
219 And we need the following config:
221 <pre>
222 hardlink: 1
223 add_underlays:
224 - /home/w-anarcat/annex
225 add_plugins:
226 - underlay
227 </pre>
229 ... and the `ikiwiki-hosting` patch mentionned earlier to allow git-annex-shell to run at all. Also, the `--shared` option will [make git-annex use hardlinks itself between the two repos](https://git-annex.branchable.com/todo/wishlist:_use_hardlinks_for_local_clones/), so the files will be available for download as well. --[[anarcat]]
231 > <del>...aaaand this doesn't work anymore. :( i could have sworn this was working minutes ago, but for some reason the annexed files get skipped again now. :(</del> Sorry for the noise, the annex repo wasn't in direct mode - the above works! --[[anarcat]]
233 This [[!taglink patch]] still applies - anything else I should be doing here to try to get this fixed? A summary maybe? --[[anarcat]]
235 > Sorry, I don't have the mental bandwidth at the moment to work through the
236 > implications of this change. I know you want this feature, I know it's an
237 > attractive solution to several use cases, and git annex support is in the
238 > queue, but at right now I'm still trying to deal with mitigating
239 > CVE-2016-3714, and the last thing I want to do is merge new security
240 > risks. --[[smcv]]
242 > > No problem at all, glad that you still have that in the queue, and I hope
243 > > my work was somewhat useful in pushing this forward! Thanks for taking
244 > > care of the Imagetragick situation... :/ --[[anarcat]]
246 Yet another option
247 ==================
249 If you happen to use rsync to deploy, instead of git, this is [much easier](https://www.cs.unb.ca/~bremner/blog/posts/big-files).