Stream from the venti server instead of reading into memory.
[webvac] / README
1 This is a somewhat specialized chunk of code!
2
3 THIS IS ALSO BETA SOFTWARE.  CAVEAT EMPTOR.
4
5 Using a lookup table in Redis and venti as the backing storage, webvac
6 serves static content.  It comes with utilities "webvac-sweep" and
7 "webvac-unsweep" that push things into venti and remove them from the
8 filesystem and place the things back into the filesystem, respectively.
9 The 'webvac' program itself starts up a webserver.  Give these programs
10 '-h' or '--help' to see helpful(?) information, and see below for
11 configuration.
12
13 Currently I am only using it to serve uploads for UGC in Pleroma.  I
14 have been using venti to do incremental backups of the data, and since
15 the uploads are WORM ("write once, read many") data, I thought it'd be
16 cool to serve the data directly out of venti.
17
18 I expect to use this more often and thus expect it to become a bit more
19 general as a result.
20
21 = Quick Start
22
23   [Check that your venti and Redis servers are operational.]
24   $ sudo ed /etc/webvac.json
25   a
26   '{"server_path_prepend":"/where/uploads/get/put/in/the/filesystem"}'
27   .
28   wq
29   $ sudo $EDITOR /etc/nginx/whatever
30   [edit your nginx configuration to proxy requests for files to localhost:8891
31   if the file doesn't exist]
32   $ webvac-server -D
33   $ find /where/uploads/get/put/in/the/filesystem -type f -print0 |
34    xargs -0 -n30 -P8 webvac-sweep -v -- 
35   [At this point, you should be able to rm the files in server_path_prepend
36   to start serving them out of venti.  Big ones are slow for now.]
37
38 = Mise en place
39
40 You will need a venti server and a Redis server.  It'll work fine with
41 either Plan 9 venti or P9P venti.  You will also need the 'vac' and
42 'unvac' utilities that come with P9P.
43
44 You will need to either have all the stuff in the default places, or
45 you'll need to configure a handful of things.  Otherwise, you will need
46 to configure probably one thing.
47
48 = Overhead
49
50 For about 100GB of files, venti takes 86GB of disk (no surprise, since
51 it's mostly JPGs and MP4s, so it's already compressed; the savings are
52 probably from dedup), and Redis takes about 60MB of RAM for this.  All
53 of the files were put into venti as part of the backup solution, but the
54 originals weren't removed if they were bigger than 4MB (see doc/TODO).
55 The workers take some RAM to run.  CPU overhead is negligible.
56
57 = Installation
58
59 `gem install webvac` should do it.
60
61 = Configuration
62
63 The nginx config I used to test is in doc/examples.
64
65 You will need to create a JSON file that specifies the configuration.
66 The first readable file from the following list is used:
67
68 * The filename given in the $WEBVAC_CONFIG environment variable.
69 * ./config/webvac.json
70 * $HOME/.webvac.json
71 * /etc/webvac.json
72
73 Here is an annotated list of configuration options, all of which start
74 with their default values.  You will almost certainly need to change
75 server_path_prepend.
76
77   {
78     // A Redis connection string, one that Redic will take:
79     "redis_url": "redis://localhost:6379/0",
80
81     // These two options are used to turn the request path into a filesystem
82     // path.  Watch this space, I might turn server_path_strip into an array.
83
84     // The beginning of the path that the entire server sits under; that is,
85     // what should be stripped from the front of the path.  For Pleroma, users'
86     // uploads are all under /media, so this works if you're serving uploads from
87     // https://$domain/media/$file .  You should probably not change this one for
88     // now, as Rake routes depend on it.
89     "server_path_strip": "/media",
90     // The beginning of the path in the *filesystem* that corresponds to where
91     // the files are kept.  It is *incredibly* unlikely that you are using the
92     // same path I am.
93     "server_path_prepend": "/media/block/fse",
94
95     // This is where the venti server is.  (This might be an array at some
96     // point.)  This address is in dial(2) syntax, by the way, so $host:$port
97     // should be written "tcp!$host!$port".  
98     "venti_server": "localhost",
99
100     // Where the vac and unvac binaries are kept:
101     "plan9bin": "/opt/plan9/bin",
102
103     // This is to make UGC work safely out of the box.  Hopefully no browser is
104     // dumb enough to run stuff inside <script> tags in something we're serving
105     // as text/plain:
106     "mime_substitutions": {
107       "text/html": "text/plain"
108     }
109   }
110
111 = Usage
112
113 Afer configuring, you can run the server with `webvac-server`.  This will actually serve the content from venti, as long as it is present in the path→score index in Redis (so you can remove content as needed by just removing items from the index).  In order to add items, you run `webvac-sweep`.  
114
115 = TODO
116
117 See doc/TODO
118
119 = See also:
120
121 "Venti: a new approach to archival storage": http://doc.cat-v.org/plan_9/4th_edition/papers/venti/
122
123 "Pleroma":  https://pleroma.social/
124
125 = I feel dirty
126
127 You can throw BTC at 1BZz3ndJUoWhEvm1BfW3FzceAjFqKTwqWV .  Proceeds will go to funding the instance hosting thing.